Understanding Express Development

The J2EE architecture defines the typical EJB component's development lifecycle as follows:

Create

Assemble

Deploy and

Run the application.

Express Development provides an easy programming archetype by automating the tasks in the typical J2EE development life cycle. The main features of Express Development are:

Auto-Interface Generation

Auto-compilation of Interfaces

Auto-Packaging

Auto-Updation and

One-shot deployment

Advantages of Express Development

J2EE Development necessitates each J2EE module in the application to be created, assembled and deployed according to the requirements of the specification. Express Development allows steps like assembling and updation of changed components to be automated with default values and always keeps the Desk Root, EJB Modules and Web Modules in a ready-to-deploy state. The user can always modify the default values. The Desk behaves like a J2EE application with Express Development- the Desk, EJB Modules and Web Modules always being in a ready-to-deploy state.

Makes life simple for the beginner by allowing him to deploy applications without getting trapped in the complicated specifications of J2EE deployment.

Allows easy migration from the Express Development archetype to the typical J2EE development archetype. This can be achieved by using the Export as Archive option.

Speeds up development time by keeping a track of and updating all changes

Makes life easy for the advanced user by taking care of all the repetitive steps in a typical J2EE development.

Viewing Express Development Output

Express Development provides feedback each time one of the following events is triggered:

Compilation of any one of the bean files (Home Interface, Remote Interface, Bean class, Local Interface, Local Home Interface)

Clean Build of EJB Module

Saving Bean Properties

Each event's status is displayed as a node in the Express Development tab of Output Panel. The status is shown visually by means of icons and colors. Each event that is triggered has processes that are displayed as sub-nodes under the main node. As these tasks complete, they are marked. The unsuccessful events are displayed in red, and the successful ones in blue.

Clean building a module or a file each time creates a separate node in the tree, and the node's successful completion depends on the completion of all the sub-nodes.

The main node does not change its status until all the sub-nodes have been completed.

The following are some of the actions that can be performed in the Express Development tab in Output Panel:

To copy text from the Express Development tab to a file, select a node, and click on the

icon, and paste in another file. This copies all the text available under the main node.

To search for text, click on the

icon. This brings up the Search for dialog, where enter the text to be found and press enter.

To clear all the text in the Express Development tab, click on

icon. This can also be performed by right clicking anywhere in the Express Development tab and clicking on Clear All.

To expand the tree node, select the node and click on the

icon. This expands the tree node and displays all the sub nodes.

To collapse a tree node, select the node and click on the

icon.

Right click on a node in the tree and select Remove this to delete the node and all its sub nodes from the tree.

Right clicking anywhere in the Express Development tab and selecting Show TimeStamp displays the system date and time. This menu item is a toggle item, and becomes Hide TimeStamp and clicking on this hides the system date and time from being displayed.

To hide the Express Development tab, right click on the tab name and select Hide this. To hide all other tabs, except Express Development tab, right click on the tab name an select Hide All Except This. To view all the tabs, right click on the tab and select Show All.

EJB Module

EJB Module is a Source Root stored directly under the Desk node in the Desk tree hierarchy, which is always in a ready-to-deploy state. The EJB Module represents an extracted archive view of the ejb-jar and provides the user with all the added functions of Express Development.

There can be more than one EJB Module in one Desk and also point to a single Source Root in the file system. More than one EJB Module in the Desk can share a single EJB component.

EJB 1.1 This represents an EJB 1.1 JAR which maintains the ejb-version 1.1 semantics. Beans with ejb-version 2.0 semantics cannot be added to this module.

EJB 2.0 This represents an EJB 2.0 JAR with ejb-version 2.0 semantics. Modules of this type can include both 1.1 and 2.0 beans.

The EJB Module is always in a "ready-to-deploy" state.

The module need not be packaged into a JAR to make it deployable.

The module is aware of all changes made to its sub-components (beans), automatically packages the beans, and also updates packaging and deployment information based on J2EE packaging rules.

The module is enabled for multi-server deployment.

The module can be converted into a JAR file on a single click, Export As Archive.

The module can be opened using the Package tool, and all the packaging information can be viewed here.

The module can be opened using the Deploy tool, and all deployment information can be changed here.

The module supports multiple ejb-names.

Changes made to the bean properties in one module automatically get reflected in the other modules holding the same bean.

File Structure of EJB Module

The following section describes the file system structure of the EJB Module created by Express Development. Creating a bean using the wizard in the EJB Module automatically generates the bean class file, the bean and its interfaces, and also compiles them. The classes directory of the EJB Module, which cannot be changed by the user, is set by Studio based on its name and goes under the Desk's classes directory (specified by the user at Desk creation time). This is set as such, so that Express Development can maintain physical separation between different modules and treat them as virtual ejb-jars.

If the EJB Module name is TestEJB, then the classes are stored in the directory called <Desk-classes-dir>/TestEJB.

The following is the structure of the EJB Module and its files as maintained in Studio:

Modifying EJB Module Properties

Packaging Information (ejb-jar.xml) for a bean under an EJB Module is generated from the Packaging information provided in Bean Properties of that bean. Any changes made to the Packaging information in Bean Properties is picked up by Express Development. Use Bean Properties to change any packaging information. To bring up the Bean Properties panel, right click on the specific Bean Properties node in the Desk and select Open. Some of the attributes that can be set here are:

EJB References

Resource References

Resource Environment References

Transaction Attributes

Environment Entries

CMP Fields (for CMP Bean)

O-R Mapping (for CMP Beans)

Map Finder Queries (for CMP Beans)

Modifying Packaging Properties

Express Development generates the ejb-jar.xml file automatically. The ejb-jar.xml file comprises the enterprise beans, in addition to the packaging information, so that the module functions as a complete EJB application in a "ready-to-deploy state". The ejb-jar file must contain, either by inclusion or by reference, the class files of each enterprise bean as follows:

The enterprise bean class.

The enterprise bean home and component interfaces.

The primary key class if the bean is an entity bean.

To view the ejb-jar.xml properties, right click on the EJB Module and select ejb-jar.xml. This brings up a panel with the EJB Module representing an archive view of the JAR.

The user can only add and make changes to the Security Roles in this dialog box. All other changes to be made should be made in the Bean Properties Panel. The EJB Module displays all the beans to be deployed and their following properties:

EJB References

Resource References

Security Roles

Method Permissions

Transaction Attributes

Environment Entries

Container Managed Fields

CMR Data

Finder/Select Methods

Deleting a Bean from the EJB Module

Deleting a bean from the Desk would automatically remove all beans holding relationships with the bean from the ejb-jar for that EJB module (the related beans are not physically removed).

This process is repeated until the ejb-jar is consistent as per EJB specifications. The ejb-jar.xml is updated accordingly and all related deployment information is modified and updated.

To reconstruct the JAR, new relationships would have to be created once again using the Relationship Manager or by manually editing the bean sources. To add any removed beans, just compile them in the desk. This will trigger Express Development to add these beans to the ejb-jar.xml.

Modifying Deployment Properties

All deployment information for beans under EJB modules are stored in the following files:

pramati-j2ee-server.xml and

pramati-or-map.xml.

The deployment information are all picked up from the Bean properties. Changes made here all put back in the appropriate Bean Properties Panel. Deployment information can be examined and modified for any target server by opening the module in the Deploy Tool, and then saving this information. To open the module in the Deploy tool, go to Tools > Deploy, and in the Deploy tool that comes up, select Archive > Open > Module name. This opens the EJB Module as an archive file, where all deployment information can be modified.

Configuring sub-components to be deployed

The EJB Module can be configured to include or exclude sub-components to be deployed. To do this, right click on the module and select Properties. In the Properties panel that comes up, select the Deploy tab.

Here the Beans option in the Include field, allows beans to be marked as deployable or non-deployable. Non-deployable beans are ignored by Express Development. Un-checking a bean marks it as non-deployable and removes the bean from the packaging information. Other properties that can be configured are files and folders.

Un-checking a CMP 2.0 bean affects all other beans in the relationship (CMR) graph.

Modifying Queries

Information on all queries for EJB 1.1 modules are stored in the file queries.props. This information is also available in the Finders node in Bean Properties Panel. To modify any query, use this panel.

Note for 2.5 users: The Queries are all created and maintained by Express Development.

Exporting into Java Archives

Export as archive asks the user to choose the destination. The following files are available in the exported Java archive -

All files under the classes directory of the module including packaging and deployment xmls and queries.props for EJB 1.1 modules.

All classes mentioned in the ejb-reference tab of packaging information, along with custom classes that they use as method parameters, or exception classes, or return values according to packaging information. These classes are generally picked up based on JNDI names, and if the JNDI name is missing then based on the classpath. If the classes cannot be found, the operation will not stop.

All files mentioned in the Include Files option in the Properties panel.

All files under all the folders mentioned in the Include Folders option in the Properties Panel.

All non-Java files on the Desk in the module.

The exported Java archive can be used in the Desk like any other ejb-jar created through Packaging tool. It is enabled for updation so a right click update will pick up new packaging information. However, as per Packaging tool's Update Operation semantics, the deployment information does not get updated.

Filtering Files for Exporting

Files can be filtered to be excluded when an EJB Module is exported as an archive. Filters are stored in a file named <ModuleName>ExportAsArchiveFitlers.props located under the Desk Root directory. File matching any of the provided patterns in this file, are automatically removed from the archive.

To exclude all CVS files from an exported archive, edit the module's file for filters by adding the entry <ModuleName>.<filterNum>=*CVS/* as the pattern to exclude.

Always use / to indicate path names.The default patterns that are used for EJB Modules are *.java

The Filter files can be edited any time. The changes then get picked up the next time the operation, Export as Archive is performed.

Web Module

A Web Module is a folder directly under the Desk node in the Desk tree hierarchy and is always in a ready-to-be-deployed state. The Web Module represents the archive view of the WAR in the Desk and provides the user with all the added functions of Express Development.

There can be more than one Web Module in a Desk but no two Web Modules can point to the same source root directory in the file system.

It keeps all it components (JSP Pages, Servlets, Filters) updated, with all the latest packaging and deployment information based on the J2EE Packaging rules.

It can be deployed without being converted into a Web archive.

It is always enabled for deployment on multiple servers.

The web-server picks up the JSP files directly from under the Web Module and therefore updating any JSP file requires only opening the file in the editor, making the required changes and saving it. The application need not be re-deployed.

Since a Web Module points to a Source Root in the file system, Servlets can be stored in any of the modules - Java Modules, EJB Modules or Web Modules and then deployed with a Web Module.

It can be converted into a Web archive (WAR).

It can be modified using the Package Tool as well as Deploy Tool.

File Structure of a Web Module

Files are organized under Web Module in a certain way. The classes directory is defined by the J2EE Specification and cannot be modified. It is constructed by <Web Module Location>/WEB-INF/classes.

Modifying Properties

The Web Module automatically generates the web.xml file whenever required. Right Click on the Web Module and choose web.xml for any changes to be made to the web component properties. For these changes to be picked up by the server, re-deploy the application. To modify any packaging and deployment information, open the web.xml file by right clicking on the Web Module > web.xml, and modify all the changes required.

Deployment information can be examined and modified for any target server by opening this module in the Deploy Tool and then saving this information. Open the Deploy tool using Tools > Deploy from the main menu.

Open the Properties panel by right clicking on the Web Module, and select the Deploy tab. All deployable sub-components can be configured in this panel. Here the "Servlets/Filters" option allows Servlets and Filters to be marked as deployable or non-deployable. All available Servlets and Filters can be deployed on any Web Module. Class names must be unique. A successful compilation will cause the Servlet or the filter to be recompiled and added to the classes directory of the WebModule.

References can be auto-packaged into the supportingClasses.jar each time the Web Module is deployed. This can be switched on using the Deploy tab in the Properties panel. The Properties panel is available on a right click on the Web Module.

Note: Update the supportingClasses.jar file before deploying the Web Module, for the file to pick up changes made to interfaces, which effect JSP files in the Web Module.

Deploying Web Module

Web Modules can be deployed by right clicking on them and selecting Deploy. If the deployment information is incomplete and reasonable defaults are not available for that option, the Deploy tool opens, where all the pending tasks can be completed. The changes made are saved back to the module and also to the corresponding Web Module files.

Changes made to the JSP Pages are immediately reflected when they are saved, and the module need not be re-deployed. If the interfaces of the referenced beans are modified, the module must be re-deployed to reflect these changes. This is especially important when References are auto-packaged into supportingClasses.jar as this JAR is updated only on deployment.

Picking Servlets and Filters Classes from WEB-INF/lib/*,jar

Use the Deploy tab in the Properties dialog to pick up Servlets/Filters from a Web Module's classpath and then add them to the web.xml file.

Right Click on the Web Module node in the Explore Panel and select Properties. In the dialog that comes up, select the Deploy tab.

In the Include field, select the option, Servlets/Filters from the combo box.

Clicking on the button, Servlets... allows picking up of Servlets from a JAR under WEB-INF/lib.

Clicking on the button, Filters... allows picking up of Servlets from a JAR under WEB-INF/lib.

Clicking on one of the buttons pops up a dialog that scans the JARs and looks for Servlets or Filters, depending on the option that was selected.

The Scanning dialog displays the Servlets/Filters as they are found. The user does not have to wait for the scanning to end. At any point, the user can select the classes required and click OK. Clicking on OK at any point, interrupts the process and displays all the found Servlets/Filters in the Deploy tab.

The chosen Servlets or Filters from the classpath appear in the table. The added Servlets and Filters are by default selected (they are checked in the Deploy column) to be added to the web.xml. To remove them from the web.xml file, remove the checked tick against the servlet or Filter name.

Note 1: Loose classes from WEB-INF/classes are not scanned and picked up. Only Servlets/Filters in the jar files are picked up.

Note 2: Once a Servlet is added to the Include table it will not be removed from that list even if it is unchecked.

Exporting into Web Archives

The option Export as Archive is used to convert the Web Module into a physical archive visible in the Desk. This can be done by right clicking on the Web Module > Export as Archive. Before exporting into an archive, ensure that a war archive node exists on the Desk. Selecting Export as archive prompts the user for the destination. The following are the files that are added to the archived WAR:

All files under the Web Module including packaging and deployment xml files, and also all files that may not be present on the Desk.

Selecting this option adds all the classes mentioned in the EJB Reference tab in the web.xml file, along with custom classes that they use as method parameters or exception classes or return values. These classes are picked up based on JNDI names and if the JNDI name is missing, on the classpath. The process is not stopped even when these classes are not found.

All files mentioned in the Include Files option.

All files under all folders mentioned in the include folders option

The exported archive can be used in the Desk like any other WAR created through Packaging Tool. It is enabled for updation, and right clicking on the file and selecting Update picks up all the latest packaging information, but deployment information is not updated.

Modifying Context Root

When a Web Module is deployed, the context root is taken as the Web Module name. To modify the context root, follow one of the given methods:

The first method involves creating a new Web Module with the name as the context root's name, and then deploying it.

Create a new Web Module with the name as the context root's name.

Import all the required files into the new Web Module

Close the Desk

Copy the web.xml file of the old Web Module into the new Web Module. The web.xml file is stored in the location, <install_dir>/<desk_dir>/<webmod_dir>/WEB-INF, where <desk_dir> is the directory of where the Desk is located, and <webmod_dir> is where the Web Module is located.

Copy the XML file, pramati-j2ee-server.xml from the old Web Module into the new Web Module. This file is stored in the location, <install_dir>/<desk_dir>/<webmod_dir>

Re-open the Desk in Studio

Deploy the Web Module by right clicking on the node in the Explore Panel and selecting Deploy

Access the application by running the JSP client. For example, http://localhost:8181/context_root/test.jsp, where context_root is the name of the new Web Module, and test.jsp the JSP client used to access the WAR

This method involves creating a WAR using the Export As Archive option, and changing the context root of the WAR file created.

Create a by right clicking on the Web Module node in the Explore Panel and selecting the option, Exporting As Archive

Select Tools > Deploy from the main menu. This starts the server and brings up the Deploy Tool

Open the WAR file in the Deploy Tool

In the WAR file that opens, Select the Web Properties node in the Tool, and modify the context root

Save the Archive by clicking on Archive > Save from the main menu

Deploy the WAR by clicking on Archive > Deploy from the main menu

Alternatively, right click on the JSP file node in the Explore Panel and select Run. This method allows the new Web Module to take advantage of all the Express Development features

This method involves creating a WAR, adding it to an EAR and then deploying the application as an EAR.

Create a WAR using the Package Tool or by Exporting the Web Module as an archive

Add all the Web contents (JSP files, Servlets etc.) into the WAR, if it was created using the Package Tool. Using the option, Export As archive automatically adds all the contents

Create an EAR using the Package Tool

Add the WAR to the EAR. When the WAR is being added to the EAR, enter the context root when prompted

Deploy the EAR

Filtering Files for Exporting

The exported archive picks up all available files in the Web Module for performance reasons. This may result in certain unnecessary files getting packaged, increasing the WAR file size. These files include Java source files, map files used by the Debugger. The Filtering Files option helps avoid this situation, by not including these unnecessary Java source and map files.

Files can be filtered to be excluded when a Web Module is exported as an archive. Filters are stored in a file named <ModuleName>ExportAsArchiveFitlers.props located under the Desk Root directory. File matching any of the provided patterns in this file, are automatically removed from the archive.

Always use / to indicate path names.The default patterns that are used for Web Modules are *.java, *.map

The filter files can be edited any time. The changes get picked up the next time the operation, Export as Archive is performed. Filter Patterns are not applied on the supportingClasses.jar.

Desk Root

A Desk Root is a virtual representation of a J2EE Desk, and is stored. The Desk Root acts as the node containing the entire J2EE application. It represents the archive view of the EAR in the Desk and provides the user with all the added functions of Express Development.

Using the option Deploy available on a right click deploys the modules under the Desk Root. Using Deploy as EAR, available on a right click deploys the application as an enterprise archive. If all the settings required for deployment are not provided, the deploy tool comes up so that the user can make the required changes.

Changes made in the Deploy Tool are not persisted when the Desk is deployed as an EAR. The application gets deployed with the changed deployment information only for the current deployment. The JSP Pages are also not refreshed automatically in this case.

Exporting into Enterprise Archives

To smoothen the progress of moving from the Express Development mode of working to the typical J2EE mode of working, use the Export As Archive option.This option converts the Desk Root node into a physical enterprise archive (EAR).

To do this, right click on the Desk Root node in the Explore Panel and select Export as Archive. This converts it into a physical archive in the Desk. To export the Desk Root into an EAR, the Desk must have a folder of the type, enterprise archive.

These archives are complete J2EE archives and comprise the deployment descriptors (XML files) and can be deployed on the Server or opened in Studio to be modified. These archives have an independent existence from their source. Changes here do not get reflected anywhere else.

Validating the Desk Root

The Desk Root can be validated before deploying, to verify that all tasks to be performed by the bean provider, as mentioned in the EJB 2.0 specification, are complete.

To validate the Desk Root, right click on the Desk Root node in the Explore Panel and select Validate. This exports the Desk Root into an enterprise archive (EAR), and then validates the archive created.

Configuring Deployable Modules

The Desk can be deployed without all the modules under it. This is especially useful when the Desk contains modules that are still being developed, or are incomplete. To do this, right click on the Desk tree node and select Properties. In the Properties panel that comes up, click on the Deploy tab, and un-check the modules that are not to be deployed. The modules that are unchecked are not included in any of the operations - Deploy, Validate, or Export as Archive.

Pending Tasks

Express Development keeps track of user operations and tries to keep the application in a state where all the common, error-prone, manual tasks have been automated. To achieve this, it uses certain user operations like triggers. Example, Bean compilation is treated as trigger.

Such triggers result in requests that have to be processed sequentially. Some of these requests may take some time to get executed. This results in stopping all other operations until the request is executed completely. For example, deployment requests may take a long time to execute completely.

When the user invokes an operation that requires UI feedback like validation, displaying packaging properties, or exporting as archive, the operation may not be executed immediately because of pending tasks. Pending task are tasks in Studio that are yet to be executed.

The Express Development Pending Tasks Panel in such a case, pops-up in the Status Bar and shows all the pending tasks of the different modules. When the specified tasks are executed successfully, the panel disappears from the Status bar. This panel can also be hidden by clicking on the Hide button.

Troubleshooting Tips

The EJB Module, Web Module or the Desk Root in the Desk may not reflect the specified settings of the application. To solve this, Right Click on the Desk Root/EJB Module/Web Module > Properties.

This brings up the Properties dialog box. Click on the Repair tab and use the Sync State button to forcibly regenerate all the deployment information.