JBuilder AppServer concepts

General description

AppServer is a class that defines a set of basic methods that describe an application server. By using these methods, JBuilder can perform tasks particular to the defined application server at various times. For instance, it can determine what main class to use when the user wants to run an instance of that application server from within JBuilder.

JBuilder also uses the AppServer setting for its EJB definition wizards, as code must be generated differently for various application servers. Each JBuilder project has an AppServer associated with it. By default this is the Inprise Application Server 4.1, but JBuilder also defines an AppServer implementation for WebLogic 5.1, and EJB 1.1. An AppServer definition can be added to JBuilder by using the OpenTools API, or by defining some basic properties within the Application Server Properties dialog in JBuilder (Choose Project|Project Properties, click the Enterprise tab, click the ... button, select the application server you want to edit, and choose the Edit button). By going through the OpenTools API, however, the user has much more control over the exact actions this AppServer definition will perform at various times.

In addition to the AppServer class, JBuilder provides an EJBDeployer interface, which allows you to define a custom set of actions to deploy a set of .jar files for a particular AppServer. All of the AppServer related classes reside in the com.borland.jbuilder.enterprise.ejb package. The following classes/interfaces are instrumental in defining an AppServer:

All AppServer classes will be available from the Enterprise tab of the Project Properties dialog. The user can modify the properties of a selected AppServer by pressing the ... button on the Enterprise page, selecting an AppServer from the available list, and selecting Edit.

AppServers that are defined through the OpenTools API cannot be removed from this list. If the project gets saved, AppServer values are saved in an appserver.properties file, and will include any changes the user made to the default settings (for example, VM parameters). The next time the project is opened, the AppServer property values will be loaded from the appserver.properties file, instead of the default settings.

Detailed description of feature/subsystem

Registering an AppServer

To add a definition of an AppServer to JBuilder's existing list of AppServer definitions, you must register an AppServer definition with the AppServerManager class. This registered class must extend the AppServer abstract class and implement all of its abstract methods. Do this by defining a static initOpenTool() method in this extended class, as in the following example.
public static void initOpenTool(byte majorVersion, byte minorVersion) { 
   AppServerManager.registerAppServer(new InpriseAppServer41()); 
}
An AppServer reference can be retrieved from the AppServerManager class using either a project reference, or the full name of the desired AppServer. The full name is a combination of the AppServer name and version. The AppServer class has a static function, MakeFullName(), you should call to build the full name. For instance, to retrieve a reference to the AppServer for the Inprise Application Server 4.1, you can use the following call:
AppServer appServer = AppServerManager.getAppServer(   
   AppServer.makeFullName(InpriseAppServer41.INPRISE_APP_SERVER_DEFAULT_NAME, 
   InpriseAppServer41.INPRISE_APP_SERVER_DEFAULT_VERSION)); 
To retrieve the AppServer for a project reference, you can use the following call:
   AppServer appServer = AppServerManager.getAppServer(project); 

Defining the default settings

The return values of the "getDefault..." settings methods are the initial values for those settings. For example, getDefaultVmParameters() will return the initial value of the VM parameters that will be used to run this AppServer. Most of these settings will be modifiable by the user through the Application Server Properties dialog box.

Among other settings, you can also provide a default list of classes or jars that this AppServer needs to run. The getDefaultClassPath() method returns a Url array of these. These classes/jars will usually include the default home directory value. Once the user modifies the home directory in the Application Server Properties dialog, these classes and libraries will be updated to use the new home directory (if their path included the previous home directory).

Running or debugging the AppServer

There are a few ways to run the current AppServer for the project. If the EJB page on the "Run page of the Project Properties dialog is selected, the current AppServer for the project will be run/debugged when the user selects the Run or Debug menus. It will use the parameters displayed in the EJB run page. These parameters are retrieved from the latest settings of the AppServer. The current project's AppServer will be displayed at the top of the EJB page, but you can't change it from that page. The only place to modify the current AppServer for the project is from the Enterprise page of the Project Properties dialog.

Another way to run the current AppServer is to right click on an EJB group in your project view, and select Run or Debug. This will run/debug the project's AppServer, and will use the selected EJB group's .jar file as the EJB jar to pass to the server.

Customizing the VM parameters and the parameters for running/debugging an AppServer

Some functions in the AppServer abstract class have default implementations, but in various cases it might be useful to override the default behavior.

Before JBuilder generates the command line to run/debug the AppServer for the project, it will call the customizeVmParameters() and the customizeParameters() methods for the AppServer to get the customized parameter values. This customization allows you to implement the exact order or the absence or presence of particular parameters in the returned strings. By default this function is defined to return just the existing parameters (they are passed in as an argument to both methods), but if you want specialized behavior, you should override these methods.

For example, the Inprise Application Server 4.1 must insert the server name and the EJB jars to be used by the server in front of the current parameters. This could be done using the following implementation of customizeParameters() :

public String customizeParameters(String currentParameters, 
   ArrayList ejbJarFiles, Project project, Map propertyMap) { 
   
   // add server instance name 
   String serverName = AppServerRunner.SERVER_NAME.getValue(propertyMap); 
   StringBuffer customizedParameters = new StringBuffer( 
     serverName == null ? "" : serverName); 
   customizedParameters.append(' '); 
   
   // add ejb jars 
   int size = ejbJarFiles.size(); 
   for (int i = 0; i < size; i++) { 
     // surround jars with quotes, in case have spaces 
     customizedParameters.append('"'); 
     customizedParameters.append((String)ejbJarFiles.get(i)); 
     customizedParameters.append('"'); 
     customizedParameters.append(' '); 
   } 

   customizedParameters.append(currentParameters); 
   return customizedParameters.toString(); 
   } 

Customized shutdown

Another useful method that you might want to override is shutdown(). This method is called after the AppServer terminates its execution (run or debug). It is useful if you need to perform any kind of clean up after execution completes.

Registering an EJBDeployer

If you register an EJBDeployer interface implementation with the AppServerManager, choosing Tools|EJB Deployment will execute the deployment method you specify in that implementation. The EJBDeployer interface is very simple. It is basically one deploy() method, which has as one of its parameters a list of the .jar files to be deployed. So, if the deployment tool you wish to use accepts multiple .jars, you can send this list to that deployment tool.

When you register the EJBDeployer implementation class, you must associate it with a particular AppServer, using that AppServer's name and version number, as in the following example:

public static void initOpenTool(byte majorVersion, byte minorVersion) { 
   AppServerManager.registerEjbDeployer(new WebLogicAppServer51EjbDeployer(), 
   WebLogicAppServer51.WEBLOGIC_APP_SERVER_DEFAULT_NAME, 
   WebLogicAppServer51.WEBLOGIC_APP_SERVER_DEFAULT_VERSION); 
} 
If you do this, the appropriate deployment implementation can be used when the AppServer for the project changes.