![]() |
Copyright © TIBCO Software Inc. All Rights Reserved |
Before you can develop and run an XAL application, you must first install either the OIG J2EE components (for Java environments) or the OIG .NET components (for .NET environments). Refer to Chapter 1, Getting Started with Object Integration Gateway (OIG) for more information.The fastest and easiest way to develop an XAL web application is to deploy the sample XAL application, and to modify it to work with your existing text-based application.A sample JavaServer Pages (JSP) application for XAL is provided in the WebFrame.war file, which is included when you install the J2EE components for OIG. A sample XAL application for .NET is also available by request.
1. Deploy the WebFrame.war application file to your servlet/JSP container, using the procedures specific to your container.For example, if you are using Tomcat, copy the WebFrame.war file into the application deployment directory, which is named webapps by default.This assumes that your servlet/JSP container is also running as the web server, and that it is listening on port 8080 for HTTP requests.A login page should open in a separate browser window that has no navigation buttons. To better emulate 3270‑style navigation using PF keys, the navigation buttons are absent.
5. On the login page, enter your TIBCO Object Service Broker connection parameters, and the name of a startup rule for an existing text-based application. The rule must take no arguments and the rule name must already be entered into the @XAL_APPAUTH table on the TIBCO Object Service Broker system where you are connected.Entering the name of the startup rule in the @XAL_APPAUTH table authorizes you to run the text-based application as an XAL application.The sample web application is a very simple JSP application. Here is a more detailed description of how it works:
1. Entering the URL for the sample application in your web browser takes you to the default page for the site: index.html.
2. The index.html page has a start button. Clicking the start button opens the login.html page in a new browser window that has no forward/backward navigation buttons. The navigation buttons are removed because a text-based application requires that you use PF keys to display screens. Using browser navigation buttons to move from screen to screen would ‘confuse’ the text-based application and cause it to fail.
3. In the login.html page you enter the TIBCO Object Service Broker connection parameters and the name of a no-argument startup rule for a text-based application. When you click the submit button, the connection parameters and rule name are passed to the login.jsp page.
4. The login.jsp page instantiates an XalSession object and initializes it with the parameters in the web.xml file, as well as the connection parameters and startup rule name passed from the login.html page. To specify your own startup rule, simply enter the name of the rule in the RULE field on the login.html page. Remember that the rule must take no arguments, and must be entered in the @XAL_APPAUTH table.
5. The login.jsp page calls the XalSession object’s start() method, which starts the text-based application and allows it to run until the first DISPLAY or DISPLAY & TRANSFERCALL statement is encountered. At that point the XAL framework extracts the displayed screen’s data and metadata and returns them to the XalSession object. When all this is done the start() method returns.
6. The login.jsp page instantiates an HtmlProducer object and calls its paintScreen() method. The paintScreen() method writes HTML to the browser’s output stream. The result is that the browser renders a web page generated by the HtmlProducer object.
7. When you click a PF key, the form is posted to the response.jsp page. The response.jsp page instantiates an HtmlConsumer object that, in turn, processes the fields in the response object such that the XalSession object is updated with all changed data and cursor location information.
8. The response.jsp page calls XalSession.processFcnKey(). This method validates the changed data, and sends it to the XAL framework running in the TIBCO Object Service Broker Execution Environment. The XAL framework updates all necessary screen data, positions the cursor, and returns control to the application.
Unless an error is encountered, the response.jsp page processes both the display and response actions on every screen in the application.The sequence described in the previous section represents an error-free interaction. This section describes what happens in the sample web application if there is a validation error on a modified field.
1. When data is modified, the ScrRowSet object validates the data against the metadata for the screen table, and throws an XalValidationException if constraints are violated.
2. When data is modified, the ScrRowSet object validates the data against any stored reference table information.
3. If a field has a reference table, but the data is not cached in the XalSession object, the data is sent to the Execution Environment where the validation occurs when the screen table is updated. If validation fails, an XalValidationException object is thrown.
4. If an XalValidationException object is thrown in the demo application, the ValidationError.jsp page is used to display the error message. You can correct the input data and resume at this point.There are three basic ways to modify the sample application to achieve the “look and feel” you want for your XAL applications:The sample application includes a cascading style sheet, xal.css, that is used to control the appearance of the application. You can freely modify this style sheet, or create a new style sheet, for your own applications.The xal.css sample style sheet is listed here with comments describing the function of each section./* Attributes particular to the helpkey, which is not an input control, but a button. *//* Screentable data is placed in scrollable divs. In this case they have a thin border so you can see their boundaries. *//* Fields with reference tables attached could be rendered as select controls.The default HtmlProducer does not do this because of horizontal alignment problems. */The screen metadata documents are XML documents. By default, they are retrieved by the XAL client at runtime and parsed into a DOM. This DOM is used by the HtmlProducer class to generate the HTML for the application web page.A screen metadata document is composed of elements, each of which has several attributes and, potentially, child elements. A screen metadata document must conform to the XAL.xsd XML schema document, which is included with XAL. You can use this schema to validate any changes you make. Several of the attributes in a screen metadata document can by modified to affect the way HTML is produced:
• Each element has an ENABLED attribute, which when set to false causes the element and all its children to be skipped by the HtmlProducer object.
• Text boxes can have their type property set to SUBMIT, BUTTON, CHECKBOX, and so on. See the schema document for values.
• A text box with a reference field attached can have its type set to SELECT, which causes a select control composed of the contents of the reference table to be rendered.
• Any of the other properties can be modified. You can even modify any part of the document in ways not supported by the default HtmlProducer class and create a new custom producer class that supports the modification. You could have to extend the XML schema as well.To generate a metadata document for a screen, you run the XAL_GO_DSN rule in a TIBCO Object Service Broker session started with DSBIFTYPE=TEXT. This rule takes the following three arguments:
• SCHEMA_URL — The URL that is placed in the XML document for validation purposes. You should copy the XAL.xsd file onto a local web server and provide that URL. If null, no schema is included in the document and no validation occurs.
• OUTPUTDIR — The directory where to write the metadata documents. If null, the session's DSN directory is used.After using the XAL_GO_DSN rule to write the screen metadata document to a file, you can modify it.To produce an HTML rendition of the currently displayed screen, the HtmlProducer object must obtain the DOM representation of the screen’s metadata. It does this by calling the XalSession.getScreenDomMetaData() method, which returns the DOM for the currently displayed screen. If the DOM for the screen is not cached, and if the XALMETADIR session parameter is specified in the web.xml file, the XalSession.getScreenDomMetaData() method builds the DOM by parsing the screen’s metadata document located in the directory specified in the XALMETADIR session parameter. If the XALMETADIR session parameter is not specified, a default DOM is retrieved from TIBCO Object Service Broker. New DOMs are added to the cache.The HtmlProducer and HtmlConsumer classes are used in the sample application JSPs to produce and consume HTML, and therefore play a significant role in determining the ‘look and feel’ of the application. The source code for these two classes is provided with XAL so you can modify it for your own purposes. Alternatively, you can create extensions of these classes and use them in your JSPs.When creating or modifying Java classes for use in XAL applications, refer to the API documentation for the XAL components. The API documentation is provided in Javadoc format, and is available in your installation folder under OIG for J2EE.Appendix A, Setting OIG Session Initialization Parameters for information about XAL-specific session initialization parameters.
![]() |
Copyright © TIBCO Software Inc. All Rights Reserved |