com.ibm.websphere.i18n.localizabletext
Class LocalizableTextEJBDeploy

java.lang.Object
  |
  +--com.ibm.websphere.i18n.localizabletext.LocalizableTextEJBDeploy

public class LocalizableTextEJBDeploy
extends java.lang.Object

Overview

The LocalizableTextEJBDeploy tool is used by the application deployer to create a deployed LocalizableText EJB jar for the LocalizableText service. The process of deploying the EJB is required for each server per application where the service is to run from. There may be servers that do not require the LocalizableText service installed. The same deployed jar can be included in several application .ear files, but additional steps are required at .ear deployment time (which is furthler discussed below). The application deployer also has to make sure that the application resource bundles are added to the application .ear file as files, and adjust the server classpath to point to the deployed location of the .ear file on the file system. This is so that the resource bundles can be located on the host/server.

Setting up the tool

In order for the tool to work properly, the following has to be set up.
  1. A jar file called 'ltext.jar' has to be in the < Installation Root >\lib directory.
  2. A working directory has to exist for the tool to use. The location is passed to the tool.

Using the tool

The tool requires five parameters to be passed to it. The parameters can be passed in any order, as long as the five parameters are passed. The parameters are: Here is an example of how to use the tool.

java com.ibm.websphere.i18n.localizabletext.LocalizableTextEJBDeploy -i C:\WebSphere\AppServer -h ResourcesHost -s Server045 -w E:\workingDirectory -a CheckingApplication

What the tool creates

When the tool has sucessfully run, there will be a deployed EJB file in the working directory. This file is ready to be included with the application .ear and/or .war file. The file is called and located at:
< Working Directory > \LocalizableTextEJBDeployed-< ApplicationName > .jar

Example environment

The picture helps illistrate the environment in which a LocalizableText EJB can be deployed.
No picture to display.
One of the main issues that LocalizableText had to resolve is a 'Server Targetting' issue. That is, how would a LocalizableTextFormatter 'know' where to find the application's ResourceBundles. In the example above, an application might exist on mulitple servers but not have application ResourceBundles on every server. Application X server D is an example of that configuration. Then you might also have mulitple applications installed on the same server. Server B is an example of that configuration. With the use of this tool, specific servers can be targetted via the deployment of an application specific LocalizableText EJB. When the tool is run, the application name is made part of the JNDI lookup string in the EJBs deployment descriptor with the help of the this tool. The EJB is also named with the host name and server name to keep it 'logically' unique. This keeps every application's EJB independant from the next application EJB. When a LocalizableTextFormatter from any client/server in the naming domain has the format method invoked, with the use of the set application name, it can do a JNDI lookup. The result from the lookup will be an application server that had the LocalizableTextEJBDeploy tool run on it and can access the application's Resource Bundles

Special considerations when deploying a LocalizableText EJB

When the application is being deployed onto a host/server, during the deployment process you will be asked if you want to re-generate the deployment code for the LocalizableText EJB. Do Not Redeploy the EJB. If the EJB is redeployed, the JNDI name will be wrong because of special processing this tool does.

If more than one LocalizableText EJB is to be deployed with an application, there are two possible ways to handle the situation.
  1. Run the LocalizableTextEJBDeploy tool for each Host/Server combination. By doing this, the tool will generate a unique JNDI name for the EJB. Otherwise, even though the EJB has been deployed on multiple hosts/servers, the JNDI name will not have changed, and there will only be one entry in naming.
  2. During the deployment of the application, change the JNDI name for the LocalizableTextEJB to match the following scheme:
    com/ibm/websphere/i18n/localizabletext/homes/<ApplicationName>/<HostName>__<ServerName> __LocalizableTextEJBHome
    Note: The final part of the context has double underscores between the entries.

Manual steps for non-WebSphere Advanced Editions

The process this tool uses can be reproduced with the combination of other tools and/or manual steps. Below, there is an outline of the necessary steps to take when implementing the Localizable Text service on non-WebSphere Advanced editions. Each section is based on the Enterprise JavaBeans 2.0 Specification, Public Draft 2, dated September 11, 2000, Chapter 21, Deployment descriptor.

Bean Provider's responsibility

As stated in the specification, 'The Bean Provider is responsible for providing the structural information for each enterprise bean in the deployment descriptor.' Below is the needed information from the bean provider for creating the deployment descriptor for the LocalizableText bean. Here is a list of additional information that may be useful. This information is not stated as needed in the EJB Spec.

Application Assemblier's responsibility

With the deployment descriptor created from the information in the previous section, assemble the application ejb-jar file from the LocalizableText.jar file provided. All of the class's the LocaliableText service require, are in the jar file. The ejb-jar.xml file can be used as an template for the deployment descriptor.

Bean Deployer's responsibility

The bean deployer is responsible for deploying the enterprise bean in to the server/container of choice. After the application jar file is created, generate a deployable ejb-jar file. Then deloy the bean using a JNDI name with the JNDI name specified in the section above (Special considerations when deploying a LocalizableText EJB). In summary, to manually step through the process again, follow these steps
  1. Create a deployment descriptor with the above information.
  2. Assemble the application jar file with the created deployment descriptor and the LocalizableText.jar file.
  3. Generate a deployable ejb-jar file from the application jar file.
  4. Deploy the deployable ejb-jar file in to the server with the application specific JNDI name.


Constructor Summary
LocalizableTextEJBDeploy()
          Default constructor.
 
Method Summary
 java.lang.String getApplicationName()
          Returns the application name set.
 java.lang.String getHostName()
          Returns the host name set.
 java.lang.String getInstallRoot()
          Returns the installation name set.
 java.lang.String getServerName()
          Returns the server name set.
 java.lang.String getWorkingDirectory()
          Returns the working directory set.
static void main(java.lang.String[] args)
          Runs the application for command line use.
 void run()
          This method runs all of the necessary methods dependant on the action set.
 void setApplicationName(java.lang.String newApplicationName)
          Sets the application name for the tool to use.
 void setHostName(java.lang.String newHostName)
          Sets the host name for the tool to use.
 void setInstallRoot(java.lang.String newInstallRoot)
          Sets the installation location for the tool to use.
 void setServerName(java.lang.String newServerName)
          Sets the server name for the tool to use.
 void setWorkingDirectory(java.lang.String newWorkingDirectory)
          Sets the working directory location for the tool to use.
 void usage()
          Displays the correct usage of this tool.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

LocalizableTextEJBDeploy

public LocalizableTextEJBDeploy()
Default constructor. All of the required parameters will have to be set with the set methods.
Method Detail

getApplicationName

public java.lang.String getApplicationName()
Returns the application name set.
Returns:
java.lang.String

getHostName

public java.lang.String getHostName()
Returns the host name set.
Returns:
java.lang.String

getInstallRoot

public java.lang.String getInstallRoot()
Returns the installation name set.
Returns:
java.lang.String

getServerName

public java.lang.String getServerName()
Returns the server name set.
Returns:
java.lang.String

run

public void run()
This method runs all of the necessary methods dependant on the action set. If the action set is 'create', the methods of writeEJBDeploymentDesciprotXML, writeXMLConfigXML, executeJetace and executeXMLConfig are run. If the action set is 'delete', the methods of writeXMLConfigXML and executeXMLConfig are run. If this method is being called from another program, remember to call the method isRequiredParametersSet first.

setApplicationName

public void setApplicationName(java.lang.String newApplicationName)
Sets the application name for the tool to use. The application name set here must match (including case) the application name that is going to be used by the LocalizableTextFormatter objects.
Parameters:
newApplicationName - java.lang.String

setHostName

public void setHostName(java.lang.String newHostName)
Sets the host name for the tool to use. The host is also known as the node.
Parameters:
newHostName - java.lang.String

setInstallRoot

public void setInstallRoot(java.lang.String newInstallRoot)
Sets the installation location for the tool to use. This is where WebSphere has been installed on the file system.
Parameters:
newInstallRoot - java.lang.String

setServerName

public void setServerName(java.lang.String newServerName)
Sets the server name for the tool to use.
Parameters:
newServerName - java.lang.String

usage

public void usage()
Displays the correct usage of this tool.

getWorkingDirectory

public java.lang.String getWorkingDirectory()
Returns the working directory set.
Returns:
java.lang.String

main

public static void main(java.lang.String[] args)
Runs the application for command line use.
Parameters:
args - an array of command-line arguments

setWorkingDirectory

public void setWorkingDirectory(java.lang.String newWorkingDirectory)
Sets the working directory location for the tool to use. The final deployed LocalizableText EJB jar will be located in the working directory when this tool has completed its run.
Parameters:
newWorkingDirectory - java.lang.String