BBJSP Command Engine (Deprecated)
The BBJSP system is deprecated. For new development, use BBxServlet.
Description
In BBj 16.0 and higher, the Command Engine is one of the core elements of the BBJSP framework and helps provide the MVC architecture.
Each BBjspCommand is a custom BBj class, which performs business logic based upon data in the HTTP request. The command is linked to a specific URL, processes the input request to make decisions about where to go next and directs the user to another resource such as a BBJSP Page or another BBjspCommand.
Consider a login command for example. The command will receive the username and password from a form in the login page and validate the user. If the credentials are OK then the command could add some information to the BBjspWebSession and forward the user to the main application page. If the credentials are not validated then the user will be sent back to the login page.
How to write and configure a command
BBJSP MVC controller relies on configurable commands to control the flow from page, through business-logic (in the command) to another page. A BBJSP Command is a regular BBj class that implements the BBjspCommand interface. A BBJSP Command will be dynamically mapped to a specific URL and when a request arrives a that URL then the command is executed. The class can use the BBjspCommandContext to gain access to the BBjspWebRequest, BBjspWebResponse and BBjspWebSession objects as well as the BBjspSessionData. The primary role of a BBJSP Command is to execute business logic and return in a BBjspCommandResult object which identifies the command forward to be processed. The Command Engine can then redirect the client to the configured resource.
The class can extend any other BBj class and implement any BBj interface within your application but must have the following method:
METHOD PUBLIC BBjspCommandResult execute(BBjspCommandContext context!)
Write your BBj program using this template:
REM === A BASIC COMMAND ===
class public WibbleCommand implements BBjspCommand
method public BBjspCommandResult execute(BBjspCommandContext
context!)
declare BBjspCommandResult result!
result! = context!.getResult()
request! = context!.getRequest()
response! = context!.getResponse()
session! = request!.getSession()
REM ===
REM === WRITE YOUR BUSINESS LOGIC HERE
REM ===
result!.setForward("success")
methodret result!
methodend
classend
Configuring the BBJSP Command Engine
The BBJSP Command Engine uses an XML configuration file that is loaded when the BBjJettyContext is started. All commands are initialized by the Command Engine during startup and the commands are configured in the application.
Once you have written the basic stub for your BBjspCommand you should configure and deploy it. Use one of the following methods for deployment.
-
Use Enterprise Manager to configure the command. See Enterprise Manager - Context Configuration for a more detailed explanation.
-
Configure your BBjspCommand through the Admin API using the BBjJettyContextConfiguration::addCommandConfig(String, String, String) method.
Command configurations are saved in an XML file within the context's WEB-CFG folder. Here is a simple configuration file with one command action:
<?xml version="1.0" encoding="UTF-8"?>
<bbj-command-config>
<command-mappings>
<command path='/simpleCommand.cmd' classname='SimpleCommand' source='commands/SimpleCommand.bbj'>
<forward name='success' path='/success.bbjsp' redirect='false' />
<forward name='fail' path='/fail.bbjsp' redirect='false' />
</command>
</command-mappings>
</bbj-command-config>
The xml file contains a root element for <bbj-command-config> . There is currently only one valid child element for this which is <command-mappings>.
The <command-mappings> element should encapuslate one or more <command> elements.
The <command> element has the following attributes:
|
Attribute |
Description |
|---|---|
|
path |
the URL for the command |
|
classname |
The name of the class representing the command |
|
source |
The BBj source file containing the class |
|
pipeline |
The optional name of a pipeline to execute on completion of the command. |
|
synchronized |
elements denotes that the command should be executed in a synchronized way |
In addition to the attributes, the command can specify multiple <forward> elements which define possible outcomes from a command such as success or fail which will control what happens after the command execution completes.
Each <forward> element can have the following attributes:
|
Attribute |
Description |
|---|---|
|
name |
the name of the forward |
|
path |
the URL of the page to move to |
|
redirect |
weather to redirect the client to the new location |
BBJSP Commands represent an advanced way to separate business logic from presentation. They can store data as attributes within which will be passed through the BBjspWebRequest object to the destination page.
Error messages and regular messages can also be sent via the BBjspCommandResult to the destination page. Error messages can be used to highlight bad input against field data or simply report a failure status such as 'Invalid username or password'.
When updating data it's important that the program performing the update has exclusive access to the datafile being updated. For this reason you should synchronize the command to make sure that if the command is running for one request that subsequest requests wait until the first has finished.
Synchronized commands should wherever possible be short in terms of execution time, perhaps performing the update and moving to another comnmand where additiobnal business logic can be executed.
Whenever you change update the command configuration(s) either through the Enterprise Manager, the Admin API or by manual edits to the command-engine.xml file you will need to restart the Jetty Context.