Previous     Contents     Index     DocHome     Next     
iPlanet Application Server 6.0 Administration and Deployment Guide



Chapter 2   Deploying and Upgrading Applications


This chapter describes how to deploy applications on an iPlanet Application Server machine using the iAS Deployment Tool.

The following topics are included in this chapter:



Deploying a J2EE Application Using the Deployment Tool

You can deploy an application using the Deployment Tool, a separate tool accessible from iPlanet Application Server (iAS) Administration Tool or from iPlanet Application Builder (iAB). When you deploy an application, the Deployment Tool installs all the application's files and registers all its components on the destination server, an iAS machine. An application must be deployed before it can be used.

Typically, a developer creates an application on a development machine using tools such as iAB, then deploys that application from the development machine to an application server using the Deployment Tool.


Specifying Application Directories

Before you deploy an application, you can change the application root directories that specify where the Java Server (kjs) or C++ Server (kcs) processes should look for application component files. By referencing application root directories, you can move these components around without having to rewrite application code. If you do not specify particular root directories, application files are deployed to default directories.

The Java Server and C++ Server processes use root directories to find application components when those components are needed. For example, after a result set is returned from the database, the application most likely uses JavaServer Pages to format the data. The process, whether Java Server or C++ Server, scans the template root directory or directories to find the specified JSP referenced by the application.

To specify application root directories, perform the following steps:

  1. From the iAS Administration Tool toolbar, click the Application button to open the Application window.

  2. In the left pane of the Application window, select the iAS machine whose application root directories you want to change.

  3. In the right pane of the Application window, use the text boxes to modify root directories for the specified application components as shown in the following figure:



    Use a semicolon-delimited list when specifying more than one directory for an application component.

  4. Click Apply Changes to save your changes to your iAS machine.


Starting the Deployment Tool

You use the iAS Deployment Tool for packaging application components and then deploying them to one or more iAS machines. You can launch the iAS Deployment Tool in one of the following ways:

  • From the iAS Administration Tool Application window, click the Launch iASDT button.

  • From the Windows NT Start menu, under Programs, choose iPlanet Application Server 6.0, then iAS Deployment Tool.

  • For UNIX machines, change directories to <iAS installation dir>/ias/bin and then run: ./deployGUI



About Packaging Application Components for Deployment

A J2EE application consists of many standardized components such as EJBs, servlets, JSPs, HTML pages, and other static files. To assemble an application that can be deployed, you first package application components into modules according to the container that will receive them. Then, you assemble the modules into one application Enterprise Archive (.ear) file that can be deployed. An application .ear file consists of:

  • one or more modules

    A module, the basic unit of a J2EE application, is comprised of one or more J2EE components with J2EE and iAS-specific deployment descriptor files.

  • application deployment descriptor

    The application-level deployment descriptor lists the modules included in the application and reconciles J2EE module deployment descriptors, if required.

When you deploy the application .ear file using the iAS Deployment Tool, some archived application files are automatically distributed to their appropriate directories on one or more servers and registered with iAS. For example, static HTML files, JSP files and files in the Web Application module are automatically sent to the applications directory of your application server. The EJB-JAR file is extracted from the .ear file, but individual EJBs and class files are accessed inside the EJB-JAR file.

You can also deploy individual components and component libraries when they are packaged into a module. Figure 2-1 illustrates how application components are packaged into modules and assembled into a deployable .ear file.



Figure 2-1    Packaging and Assembling Application Components for Deployment



About J2EE Modules


A J2EE module is an archived collection of one or more components targeted for the same container upon deployment. With the Deployment Tool, you can create a Web Application, or an EJB-JAR module. Each module also contains a J2EE and an iAS-specific deployment descriptor saved to XML files.

The Document Type Definition (DTD) specification defines the XML grammar for the deployment descriptor. The deployment descriptor DTDs were installed during installation at <iAS installation directory>\ias\Apps. When you create a module using the iAS Deployment Tool, you define the deployment descriptor using a graphical descriptor editor.

The following characterizes a module:

  • A module represents the basic unit of an application.

  • The deployment descriptor for a module contains all of the declarative data (J2EE and iAS-specific) required to deploy the module.

  • A single module can be deployed separately without being archived into a .ear file. However, some manual configuration steps maybe required for the module to run.


Web Application Modules

A Web Application module contains one or more of the following application components:

  • servlets

  • JavaServer Pages (JSP)

  • Tag libraries

  • HTML pages

  • classes and other resources

The components in a Web Application module are archived into a .war file. In addition, a Web Application module contains deployment descriptor files, a web.xml and an ias-web.xml file in the \WEB-INF directory of the archive, with no module name prepended.

A Web Application module can be deployed as stand-alone unit or it can be packaged with other modules to create an application .ear file. The .ear file contains all the modules with the application components required to run an application along with component-level and application-level deployment descriptor files.


Creating a Web Application Module

  1. From the Deployment Tool's File menu, choose New J2EE Module, then Web Application.

    The following dialog box appears:



  2. Type a name for your module.

    This name is used to identify your module.

  3. If required, edit the path to the directory where your .war file will be stored.

  4. Click OK.

  5. From the Edit menu, choose Insert.

    You can choose to insert one or more files in a directory, insert all files in a directory, or insert all files from the subtree of a selected directory.

  6. Navigate to the directory where the application files reside and select the files or directory to include in the module.

    The following dialog may open for you to specify root and relative paths:



    The iAS Deployment Tool tries to construct a single directory hierarchy for the archive file that contains your module, even when the component files come from different places in your file system. For example, you might have class files in directories under \usr\joe\classes and HTML files under \usr\fred\pages. Once the Deployment Tool is aware that these are the roots of the directory hierarchies where you keep different kinds of files, it can project the locations where files should be put within your archive. For example, the file \usr\fred\pages\yellow\start.html would be put in the archive at \yellow\start.html. This dialog box displays when a file being inserted is not under any of the roots known for the current module and prompts you to declare the root of the hierarchy in which this file resides. Use the arrow buttons to partition the file's absolute path into a root and a path relative to that root.


    Note <iPlanet installation directory>\ias\Apps is pre-loaded as a root directory. If you insert files into your module that are in a subdirectory of this directory, the previous dialog will not appear.


  7. Click the Up and Down arrow buttons to define the root and relative paths.

  8. When the paths have been defined, click OK.

    An archive window opens displaying the files you have selected for the module.




    Note If the list of files in your module shows files displayed in red and marked with an asterisk, these files require further action. You can see further information on the status bar.


  9. When you have specified all the files for the module, choose File, then Save to pack the files into the .war archive.

    You can also save the archive file list without packing the files into the archive. For more information, see Saving Archive Files.

    If your files require additional action, the following dialog box appears:



    You can select a file to see what action is required. Click Cancel to dismiss the dialog box and correct these problems or click Save to save the archive file as-is.

  10. Once the application files appear in the .war archive window, you can then continue with such tasks as creating the deployment descriptor files with the Deployment Tool descriptor editor. See Editing Web Application Deployment Descriptor Files to continue.


EJB-JAR Modules

An EJB-JAR module contains one or more Enterprise Java Beans (EJB). An EJB consists of the following classes:

  • implementation

  • remote interface

  • home interface

  • primary key (for entity EJBs)

In addition, an EJB-JAR module may contain other classes, and should contain all classes that are referenced (by name) by the classes that comprise the EJB.

The EJB components in an EJB-JAR module are archived into a .jar file. In addition, an EJB-JAR module contains ejb-jar.xml and ias-ejb-jar.xml files in the \META-INF directory of the archive, with no module name prepended. These files, ejb-jar.xml and ias-ejb-jar.xml, represent the component-level deployment descriptor for the module. Note that the archive may contain other XML files depending upon your declaration of deployment descriptor parameters.


Creating an EJB-JAR Module

  1. From the Deployment Tool's File menu, choose New J2EE Module and then EJB-JAR.

    The following dialog box appears:



  2. Type a name for your module.

    This name is used to identify your module.

  3. If required, edit the path to the directory where your .jar file is stored.

  4. Click OK.

  5. From the Edit menu, choose Insert.

    You can choose to insert one or more files in a directory, insert all files in a directory, or insert all files from the subtree of a selected directory.

  6. Navigate to the directory where the application files reside and select the files or directory to include in the module.


    Note The following dialog may open to indicate that a class could not be found and prompts you to add a directory or JAR file to the class path so that the class can be found. You must also insert the class file into the current module.




    The following dialog may open for you to specify root and relative paths:



    The iAS Deployment Tool tries to construct a single directory hierarchy for the archive file that contains your module, even when the component files come from different places in your file system. For example, you might have class files in directories under \usr\joe\classes and HTML files under \usr\fred\pages. Once the Deployment Tool is aware that these are the roots of the directory hierarchies where you keep different kinds of files, it can project the locations where files should be put within your archive. For example, the file \usr\fred\pages\yellow\start.html would be put in the archive at \yellow\start.html. This dialog box displays when a file being inserted is not under any of the roots known for the current module and prompts you to declare the root of the hierarchy in which this file resides. Use the arrow buttons to partition the file's absolute path into a root and a path relative to that root.


    Note <iPlanet installation directory>\ias\Apps is pre-loaded as a root directory. If you insert files into your module that are in a subdirectory of this directory, the previous dialog will not appear.


  7. Click the Up and Down arrow buttons to define the root and relative directories.

  8. When the paths have been defined, click OK.

    An archive window opens displaying the files you have selected for the module.




    Note If the list of files in your module shows files displayed in red and marked with an asterisk, these files require further action. You can see further information on the status bar.


  9. When you have specified all the files for the module, choose File, then Save to pack the files into the .jar archive.

    You can also save the archive file list without packing the files into the archive. For more information, see Enabling Support for Rich Clients.

    If your files require additional action (displayed in red in the source file list), the following dialog box appears:



    You can click a file to see what action is required. Click Cancel to dismiss the dialog box and correct these problems or click Save to save the archive file as-is.

  10. Once the application files appear in the .jar archive window, you can then continue with such tasks as creating EJBs and deployment descriptor files with the Deployment Tool descriptor editor. See the next section, "Preparing an Enterprise Java Bean for Deployment."


Preparing an Enterprise Java Bean for Deployment

To prepare an EJB application component, you must specify the class files. The iAS Deployment Tool then assigns a Globally Unique ID (GUID) to the application component.

To specify an EJB in your .jar file, perform the following steps:

  1. From the Files tab on the .jar archive window, select the following three types of classes:

    • implementation class

    • remote interface class

    • home interface class

    These classes are required to create an EJB. You can add other classes in addition to these three and should include all classes that are referenced (by name) by the classes that comprise the EJB.

  2. Choose EJB, then Create Descriptor.

    When all requirements for the EJB have been satisfied, the following dialog opens:



    The iAS Deployment Tool has generated a Globally Unique Identifier (GUID) for this EJB.


    Note Instead, another dialog box may display that prompts you to select class files for the EJB. This can occur if you have inserted more than one class of a certain type into the archive. This this case, click the drop-down arrow to select the classes for the EJB.


  3. Click OK to accept the EJB.

    If your EJB is a session bean rather than an entity bean the following dialog box appears:



  4. Select the type of your EJB: Stateful Session or Stateless Session.

    A stateless session bean is completely transient and encapsulates a temporary piece of business logic needed by a specific client for a limited time span.

    A stateful session bean is also transient, but uses a "conversational state" to preserve information about its contents and values between client calls. The conversational state enables the container to maintain information about the state of the session bean and to recreate that state at a later point in program execution when needed.

  5. Select the EJB Descriptor tab shown at the bottom of the .jar archive window

    The descriptor editor opens and the EJB names appear at the left. The General tab is active.

  6. Click each tab and specify deployment information as required.

    See Editing EJB-JAR Deployment Descriptor Files.

  7. Choose File, then Save.

    J2EE deployment descriptor data for the EJB is saved in an ejb-jar.xml file and iAS-specific data is saved in an ias-ejb-jar.xml file. These files are saved in the /META-INF directory of the module's home directory.

  8. Repeat steps 1 thru 7 for each EJB included in the module.

  9. When all EJBs have been added and deployment descriptor data for each has been specified, from the EJB menu, choose Build All Stubs. The Build Stubs menu option, builds stubs for only the selected bean.

    Stubs and skeletons are required by the EJB container and must be deployed with the application files. These stubs and skeletons enable remote communication and allow the container to intercept all bean requests. When you create stubs and skeletons, the Deployment Tool automatically adds them to the list of application files in the archive file.

    As the Deployment Tool builds the stubs, a Message window opens showing the status (this may take a moment or two).

    The EJB-JAR module is now complete.



Editing Web Application Deployment Descriptor Files

After you have specified the files for the module, you select the Servlet Descriptor tab and use the graphical descriptor editor to describe each application component in the module that is directly accessible by the user. In addition, you select the Web App Descriptor tab and describe module-level deployment information. These actions create the information that will appear in the deployment XML files for the module.

J2EE deployment descriptor data for the Web Application module is saved in an war.xml file and iAS-specific data is saved in an ias-war.xml file. These files are saved in the /WEB-INF directory of the module's home directory.


Editing Descriptors for Individual Web Application Components

You can edit the deployment descriptor data of the Web Application components using the graphical descriptor editor. You can access this editor when you select one or more application components displayed in the .war archive window and from the Servlet menu, choose Create Descriptor.

The servlet descriptor editor opens with the following tabs:


General Attributes (Servlets)

To edit the General attributes of a servlet, perform the following steps:

  1. Select application components from the list of files in the .war archive window, and choose Create Descriptor from the Servlet menu.

    The Servlet Descriptor tab of the descriptor editor opens with the application components displayed at the left with the General tab active.


    Note You only need to create the deployment descriptor for Web Application components that the user can directly access. For all other files in the Web Application, select them from the archive window. Choose Servlet and then No JSP Descriptor.




  2. Specify as follows:

    • Servlet Name: The name of the servlet or JSP.

    • Display Name: A short name that is intended to be displayed by GUI tools accessing this servlet or JSP.

    • Servlet Class|JSP file: For servlets, the fully qualified class name of the servlet. For JSP, contains the full path to a JSP file within the Web Application.

    • Description: A description of the servlet/JSP.

    • Load Order: Specifies that this servlet should be loaded on the start-up of the Web Application. Enter a positive number indicating the order in which the servlet should be loaded. Note that lower integers are loaded before higher integers. Enter 0 (or a negative number) to indicate that the container is free to load the servlet at any time in the start-up sequence.


iAS Attributes (Servlets)

You use this tab to iAS-specific options for the servlet. The Globally Unique ID provided by the iAS Deployment Tool displays near the top of this dialog.

To edit the iAS attributes of a servlet, perform the following steps:

  1. If the descriptor editor is not already open, click the Servlet Descriptors tab at the bottom of the .war archive window.

  2. Select the iAS tab.



  3. Specify iPlanet Application Server specific information as follows:

    • Number of Singles: Specifies the number of objects in the servlet pool, when SingleThread mode is used.

    • Validation Required: Specifies input parameters are validated.

    • Disable Reload: Specifies to disable reloading of servlets when dirty.

    • Encryption: If enabled, specifies communications to the servlet are encrypted for security considerations.

    • StickyLoad Balancing: Once a session is created in a given engine, subsequent requests for sticky servlets will continue to be routed to that same engine, thereby eliminating the loss of session information.

    The specifications you provide here apply to each iAS machine targeted for deployment.

  4. To disable/enable Sticky Load Balancing on a per iAS basis, click Add Server.

    A new row is added to the Server Information box.

  5. Enter the IP Address, and Port number of the iAS you want to customize.

  6. Enable/Disable Sticky Load Balancing for this iAS instance.


Initialization Parameters (Servlets)

To edit the initialization parameters of a servlet, perform the following steps:

  1. If the descriptor editor is not already open, click the Servlet Descriptors tab at the bottom of the .war archive window.

  2. Select the Init Params tab.



  3. Click the New Parameter button to add a new row.

  4. Specify the following:

    • Name: The name of the parameter.

    • Value: The value of the parameter.

    • Description: A description of the parameter.


Security Role References (Servlets)

You must identify any security roles that the current servlet references.

To identify servlet security role references, perform the following steps:

  1. If the descriptor editor is not already open, click the Servlet Descriptors tab at the bottom of the war archive window.

  2. Select the Security Role Refs tab.



  3. Click the New Reference button to add a new row to the window.

  4. Complete the row as follows:

    • Referenced Name: Name by which the servlet's code refers to the security role. The developer refers to roles but may not know how they fit into the security policies of your organization. For example, the developer could use a security role of "Credit-Worthy Customer."

    • Link to Role: Name of the actual security role. The security role that the developer has used is linked to a role that is actually used within the organization using this application. For example, "Credit-Worthy Customer" could be linked to "VIP Customer."

    • Reference Description: A comment intended to assist the user who assembles the modules into an application .ear file when choosing a role.


Cache (Servlets)

You use this tab to specify servlet caching. If you want to disable caching for this servlet, you can set the values to zero.

To configure servlet caching, perform the following steps:

  1. If the descriptor editor is not already open, click the Servlet Descriptors tab at the bottom of the war archive window.

  2. Select the Cache tab.



  3. Specify servlet caching as follows:

    • Cache timeout: Set a time-out for the caching of the servlet in seconds. If you set this value to zero, caching is disabled.

    • Cache size: Sets a cache size for the servlet. If you set this value to zero, caching is disabled.

  4. To specify the criteria for caching, click the New Criterion button to add new row.

  5. Express your caching criteria as a series of comma-delimited string descriptors. Each descriptor defines a match with one of the input parameters to the servlet.

After you have edited the deployment descriptors for individual components in the Web Application, continue with the next section, "Editing Descriptors for the Web Application."


Editing Descriptors for the Web Application

There are certain global deployment descriptor parameters that you can specify at a module level for the Web Application. You select the Web App Descriptor tab near the bottom of the archive window to access these parameters.

The Web App descriptor editor opens with the following tabs:


General (Web Application)

To edit the general properties of the Web Application, perform the following steps:

  1. If the descriptor editor is not already open, click the Web App Descriptor tab at the bottom of the .war archive window.

  2. Select the General tab.



  3. Specify as follows:

    • Name: A short name that is intended to be displayed by GUI tools.

    • Description: Descriptive text about the Web Application.

    • Distributable: If enabled, specifies that the Web Application has been programmed appropriately so that the servlets can be deployed across multiple Java Virtual Machines running on the same or different hosts.

    • Session Timeout: Specifies the default session timeout interval for all sessions created in this Web Application.

  4. To specify Welcome Files for the Web Application, enter the path to a welcome file in the text box and click Add.


iAS Session (Web Application)

You use this tab to specify attributes for the Web Application that are supported in iAS. This includes single sign-on support.

Servlets and JSPs provide support for single sign-on. This enables creation of multiple applications that need to authenticate (login) the user once, and then share that login information among all applications, so that the user does not need to login again. A usage scenario for this feature could be a consolidated airline booking service, which searches all airlines, and provides links to different airline web sites. Once the user is authenticated on the consolidated booking service, the logon information can be used by each of the individual airline sites, without requiring the user to logon again.

To edit the iAS Session properties of the Web Application, perform the following steps:

  1. If the descriptor editor is not already open, click the Web App Descriptor tab at the bottom of the .war archive window.

  2. Select the iAS Session tab.



  3. Specify as follows:

    • Distributed Session: If enabled, the session can be distributed across multiple iAS machines.

    • Secure Session: If enabled, specifies that the session can only occur on a secure (HTTPS) server.

    • Timeout: A period in seconds to specify when the client is no longer active. If unspecified, a system-wide default session timeout of 30 minutes is used. You can specify when the timeout count begins: since last access or since session creation.

    • Data Synchronization: Specify to run the Web Application locally or distributed across multiple iAS machines.


      Note The following Domain, Path and Scope attributes provide support for single sign-on authentication across multiple applications.


    • Domain: The domain to which the cookie is sent back from the web browser. By default, the domain of the URL that sets the cookie is assumed to be the domain that the cookie is sent back to. You can specify a different domain here.

    • Path: The path for the session cookie (i.e. the minimum path that the URL must have for the cookie to be sent back from the browser. For example, setting the path to /phoenix, will send the cookie back when either of the following URLS are accessed:

      http://my.foo.com/phoenix/birds.html

      http://my.foo.com/phoenix/bees.html

      The path must begin with a "/". If the path is not set, then the default path is assumed to be that of the URL setting the cookie.

    • Scope: A grouping name that identifies applications participating in single sign-on. Each application participating in single sign-on for this grouping of applications should use the same grouping name.


NLS (Web Application)

With the Nationalization Language and Localization Setting, you can specify to substitute character sets when running the Web Application in different locales.

To edit the NLS properties of the Web Application, perform the following steps:

  1. If the descriptor editor is not already open, click the Web App Descriptor tab at the bottom of the .war archive window.

  2. Select the NLS tab.



  3. Click Add.

    A new row is added to the NLS box.

  4. In the left column, enter a locale in which the Web Application is targeted to run.

  5. In the right column, enter a character set for this locale.

  6. When you have defined all the locales in which this Web Application will run, specify a default locale from the drop-down list.


Login (Web Application)

The login tab is used to configure the authentication method that should be used and the attributes that are needed by the form login mechanism.

To edit the Login properties of the Web Application, perform the following steps:

  1. If the descriptor editor is not already open, click the Web App Descriptor tab at the bottom of the .war archive window.

  2. Select the Login tab.



  3. Specify the Authentication Type with logging onto the Web Application as follows:

    • Basic: If enabled, HTTP Basic Authentication protocol is used for authentication. The authentication is based on a username and password. The web client obtains the username and the password and transmits them to the web server using base64 encoding. The web server then authenticates the user.

      Also, specify the realm name to be used for authentication with this Web Application (Currently, realm names are not used by iAS 6.0).

    • Digest: If enabled, HTTP Digest Authentication is used for authentication. The authentication is based on passing the username and password in an encrypted from. (Currently, digest is not used by iAS 6.0).

    • Form: If enabled, the developer controls the look and feel of the login screens, unlike the HTTP browser's built-in authentication mechanisms.

      Also enter the location in the Web Application of the login page and the error page that is used with this type of login. The error page is displayed when the authentication is not successful.

    • Client Cert: If enabled, authentication is performed using HTTPS (HTTP over SSL). This secure type of authentication requires the user to possess a Public Key Certificate to logon. Public Key Certificates are useful in e-commerce applications and single sign-on applications. For more information about single sign-on applications see, iAS Session (Web Application).


Servlet Mapping (Web Application)

This dialog allows you to specify the mapping between the servlets and the URL pattern that will invoke them.

To edit the Servlet Mapping properties of the Web Application, perform the following steps:

  1. If the descriptor editor is not already open, click the Web App Descriptor tab at the bottom of the .war archive window.

  2. Select the Servlet Mapping tab.



  3. Click Add.

    A new row is added to the servlet mapping box. Enter the servlet name and a comma delimited list of the URL(s) that will invoke the servlet.

  4. Repeat step 3 until all of the servlets are mapped.


Context (Web Application)

The Context tab allows you to declare the Web Application's servlet context initialization parameters.

To edit the Context properties of the Web Application, perform the following steps:

  1. If the descriptor editor is not already open, click the Web App Descriptor tab at the bottom of the .war archive window.

  2. Select the Context tab.



  3. Click the Add button to specify a context initialization parameter.

    A new row is added to the Context table.

  4. Enter the parameter's name, value and a description.


Environment (Web Application)

Environment properties are elements specific to your application such as sales tax rates or zip codes.

To edit the environment properties of a Web Application, perform the following steps:

  1. If the descriptor editor is not already open, click the Web App Descriptor tab at the bottom of the .war archive window.

  2. Select the Environment tab.



  3. Click the New Property button to add a new row.

  4. Type the name of the property in the Key field.

    For example, if you are going to enter a zip code, enter the city name in the Key column.

  5. Click in the Type column and choose the type of property, such as integer from the list box.

  6. Type the value of the property in the Value column.

    Following the zip code example, enter the zip code corresponding to the city name in the Value column: 49770.


EJB References (Web Application)

You must identify each EJB that the source code of the current Web Application references.

To identify EJB references, perform the following steps:

  1. If the descriptor editor is not already open, click the Web App Descriptor tab at the bottom of the .war archive window.

  2. Select the EJB References tab.



  3. Click the New Reference button.

    A new row is added to the window.

  4. Complete the row as follows:

    • Reference: Enter the name of the EJB that is referenced.

    • Click into the Bean Type column and choose the Bean Type: Session or Entity from the list box.

    • Bean Home Interface: Enter the Bean Home Interface for this EJB.

    • Bean Remote Interface: Enter the Bean Remote Interface for this EJB.

    • Linked to Bean: Optionally, enter the Java Naming and Directory Interface (JNDI) name by which the EJB is known. The JNDI name will be the name of the module and the Reference Name of the EJB (e.g. MyEjbJar1\MyEjb1). In most cases the actual bean that is referred to is not decided until the module is assembled into an application, at which point you will enter the JNDI name for the bean.

  5. Repeat steps 1-5 for each EJB that is referenced by the Web Application.


Resource References (Web Application)

You should identify any resource factories that the current Web Application references. A resource factory is a provider of resources, such as a JDBC driver or a JMS driver. Resource factories are used within a Web Application to acquire resources such as database connections.

To identify Web Application resource references, perform the following steps:

  1. If the descriptor editor is not already open, click the Web App Descriptor tab at the bottom of the .war archive window.

  2. Select the Resource References tab.



  3. Click the New References button and specify the following:

    • Resource Name: The name of the resource that the Web Application references, for example, a database.

    • Description: A description of the resource. For example, a JDBC connection to a database.

    • Click into the Resource Class column and choose a data source from the list box.

      A resource class is a Java interface that specifies the type of data source, for example javax.sql.DataSource.

    • Authorization: Click in the Authorization column and choose Application or Container from the list box.

      Application specifies that the enterprise bean code signs on programmatically to the resource manager.

      Container specifies that it will sign on to the resource manager on behalf of the enterprise bean.

  4. Repeat steps 1-3 until all of the resource factories that the current Web Application references are identified.


MIME Types (Web Application)

To identify the mapping between MIME types and extensions, perform the following steps:

  1. If the descriptor editor is not already open, click the Web App Descriptor tab at the bottom of the .war archive window.

  2. Select the MIME Types tab.



  3. Click the Add button to add a new row to the MIME Types table.

  4. In the left column, enter a MIME type for a file such as text/html or image/gif.

  5. In the right column, enter the file extension.


Security (Web Application)

You can specify security constraints to protect web content by defining a resource collection. A resource collection is a set of URL patterns and HTTP methods that describe a set of resources to protect. All requests that contain a request path that matches a URL pattern described in the resource collection is subject to a security constraint that you specify.

To declare security constraints to protect web content, perform the following steps.

  1. If the descriptor editor is not already open, click the Web App Descriptor tab at the bottom of the .war archive window.

  2. Select the Security tab.

    First, you define the resource collection and then you map the resource collections to roles. Then, you specify the transport layer constraint of the user data.

  3. Click the Add button to specify security constraints for web content.

    A new row is added to the Define Resource Collection table.

  4. Enter a name for the resource collection.



  5. Enter the URL pattern(s) for this resource collection and HTTP method(s) as a comma delimited list.

    HTTP methods can include GET, POST, PUT, depending on what the user's web server supports. If no HTTP methods are specified, then the security constraint applies to all HTTP methods.

  6. Click the Add button in the lower-half of the dialog.

    A new row is added to the Access Control table.

  7. In the left column, enter one or more resource collection names.

    The resource collection names you enter must be defined in the top half of this dialog.

  8. Enter the roles that are allowed to access the resources described by the resource collection.

    Roles names are bound to actual users and groups when you deploy your application. If the user is not a member of an allowed role, the user is denied access to that resource.

    Note that all roles entered in the Roles column must be defined in the Link to Role column on the Security Role Refs tab for servlet descriptors. See Security Role References (Servlets).

  9. Click in the Transport Guarantee column and choose NONE, INTEGRAL or CONFIDENTIAL from the list box. This value specifies the communication between client and server.

    • NONE means that the application does not require any transport guarantees.

    • INTEGRAL means that the application requires that data sent between the client and server is not changed in transit.

    • CONFIDENTIAL means that the application requires that data sent between the client and server is not read during transit.

      SSL is required if INTEGRAL or CONFIDENTIAL is specified.


Security Roles (Web Application)

You use this tab to declare the security roles that are actually used within the organization using this Web application.

To identify security roles, perform the following steps:

  1. If the descriptor editor is not already open, click the Web App Descriptor tab at the bottom of the .war archive window.

  2. Select the Security Roles tab.



  3. Click the Add button.

    A new row is added to the security role box.

  4. Enter the name of the role and a role description.

  5. Repeat steps 3-4 until all roles have been added.


JSP Tag Libraries (Web Application)

You can use this tab to identify any JSP tag libraries that are used within the Web Application. To identify JSP tag libraries, perform the following steps:

  1. If the descriptor editor is not already open, click the Web App Descriptor tab at the bottom of the .war archive window.

  2. Select the JSP Tag Libraries tab.



  3. Click the Add button to add a new row to the table.

  4. In the left column, enter a URI, relative to the location of the web.xml document, identifying a Tag Library used in the Web Application.

  5. In the right column, enter a location for the Tag Library Description file for the tag library relative to the root of the Web Application.


Errors (Web Application)

You can use this tab to map error codes to a resource within the Web Application. This defines what resource is will be used (or HTML page to be used) when an error occurs. To map errors to Web Application resources, perform the following steps:

  1. If the descriptor editor is not already open, click the Web App Descriptor tab at the bottom of the .war archive window.

  2. Select the Errors tab.



  3. Click the Add button to add a new row to the Errors table.

  4. In the Error column enter the error-code or exception type.

    An example of an error code is HTTP error code, 404.

    The exception type contains a fully qualified class name of a Java exception type.

  5. In the Path column enter the location of the resource to be used when this error occurs, e.g. an HTML page to be displayed.

  6. Repeat steps 3-4 until all errors are mapped to web resources.



Editing EJB-JAR Deployment Descriptor Files

After you have specified the EJBs for the module, you use the graphical descriptor editor to describe each EJB in the module. This action creates the deployment descriptor XML files for the module.

Deployment descriptor files include the declarative attributes associated with an EJB (or bean). These attributes tell an EJB's container how to manage the bean. A container is where an EJB "lives" from its creation to its destruction. The container manages the EJB's life cycle and support services while providing services that allow clients to look up the interfaces of installed EJB classes.

You can edit the deployment descriptor data of an EJB using the descriptor editor. The EJB descriptor editor opens with the following tabs:


General (EJBs)

If you have not first prepared the EJBs for the module, see Preparing an Enterprise Java Bean for Deployment.

To edit the General attributes of an EJB, perform the following steps:

  1. If the descriptor editor is not already open, click the EJB Descriptors tab at the bottom of the .jar archive window.



  2. Select an EJB at the left to declare its general deployment parameters.

  3. Complete the General tab as follows:

    • Edit the Bean Name as necessary. (This is the name that other modules would use to look up your EJB, e.g. My Ejb1)

    • For session EJBs: Set the Transaction Management Type of the bean, if required (Bean or Container).

      Specifies whether this EJB will manage its transactions. If "Container" is selected, the Transaction tab of the EJB descriptor editor is used to tell the container how to manage them.

    • For session EJBs: Change the State Management Type of the bean, if required (State and Stateless).

      Specifies whether this EJB needs to maintain state between method calls.

    • For entity EJBs (not shown in previous dialog): Set the Persistence Type of the bean, if required (Bean or Container).

      Specifies whether the container or bean will make the bean's data persistent. If "Container" is selected, the Lightweight CMP tab is used to tell the container how to store and reload an instance of the bean to and from persistent storage, i.e. a relational database.

    • For entity EJBs, Primary Key Class (not shown in previous dialog): Enter the Java class that is the primary key class for this EJB.


iAS-Specific (EJBs)

To set the iAS-specific attributes applicable to the iAS machine in which you are going to deploy, perform the following steps:

  1. If the descriptor editor is not already open, click the EJB Descriptors tab at the bottom of the .jar archive window.

  2. Select an EJB at the left to declare its iAS deployment parameters.

  3. Select the iAS tab.



  4. Complete the iAS tab as follows:

    • Passivation timeout: Enter the number of seconds the EJB will remain in memory until it is written to disk.

    • Failover: If selected, enables failure recovery. When you create stubs and skeletons, extra smart stubs are created to detect failure.

    • Pass by value: If selected, enables marshalling of all call parameters to the EJB. Otherwise, beans are co-located.

    • Enable RMI/IIOP: If selected, enables EJBs to communicate directly with Rich Clients using a bridge path instead of a web path. See Enabling Support for Rich Clients for more information.

    • Specify the number of seconds for the session wait for a response from iAS before it time-outs.

    See the Programmer's Guide (Java) for more information about these values.


Transactions (EJBs)

You can set a global transaction attribute that applies to all the methods in the EJB or you can set a transaction attribute on a per method basis. Note that the Transactions tab is used for entity beans and for session beans if the Transaction Management Type is set to "Container" on the General tab.

To edit the Transaction attributes of an EJB, perform the following steps:

  1. If the descriptor editor is not already open, click the EJB Descriptors tab at the bottom of the .jar archive window.

  2. Select an EJB at the left to declare its transactions deployment parameters.

  3. Select the Transactions tab.



  4. To specify a transaction attribute for a single method, click the Add New Method Override button.

    A dialog box listing available methods appears.

  5. Choose a method and click OK.

    A row is added to the Roles with limited access box with the method name in the left column.

  6. Choose a value for the transaction attribute from the drop-down list in the right column.

  7. After you have finished specifying the transaction attributes for individual methods, click the Transaction Attribute drop-down box and choose an attribute that applies to the remaining methods.


Environment (EJBs)

Environment properties are elements specific to your application such as sales tax rates or zip codes.

To edit the environment properties of an EJB, perform the following steps:

  1. If the descriptor editor is not already open, click the EJB Descriptors tab at the bottom of the .jar archive window.

  2. Select an EJB at the left to declare its environment deployment parameters.

  3. Select the Environment tab.



  4. Click the New Property button to add a new row.

  5. Type the name of the property in the Key field.

    For example, if you are going to enter a zip code, enter the city name in the Key column.

  6. Click in the Type column and choose the type of property, such as integer from the list box.

  7. Type the value of the property in the Value column.

    Following the zip code example, enter the zip code corresponding to the city name in the Value column: 49770.


EJB References (EJB)

You must identify each EJB that the source code of the current EJB references.

To identify EJB references, perform the following steps:

  1. If the descriptor editor is not already open, click the EJB Descriptors tab at the bottom of the .jar archive window.

  2. Select an EJB at the left to declare its EJB references deployment parameters.

  3. Select the EJB Refs tab.



  4. Click the New Reference button.

    A new row is added to the window.

  5. Complete the row as follows:

    • Reference: Enter the name of the EJB that is referenced.

    • Click in the Bean Type column and choose Session or Entity from the list box.

    • Bean Home Interface: Enter the Bean Home Interface for this EJB.

    • Bean Remote Interface: Enter the Bean Remote Interface for this EJB.

    • Linked to Bean: Enter the Java Naming and Directory Interface (JNDI) Name by which the EJB is known. The JNDI name will be the name of the module and the Reference Name of the EJB (e.g. MyEjbJar1\MyEjb1). In most cases the actual bean that is referred to is not decided until the module is assembled into an application, at which point you will enter the JNDI name for the bean.

  6. Repeat steps 1-5 for each EJB that is referenced.


Resource References (EJBs)

You should identify any resource factories that the current EJB references. A resource factory is a provider of resources, such as a JDBC driver or a JMS driver. Resource factories are used within an EJB to acquire resources such as database connections.

To identify EJB resource references, perform the following steps:

  1. If the descriptor editor is not already open, click the EJB Descriptors tab at the bottom of the .jar archive window.

  2. Select an EJB at the left to declare its resource references deployment parameters.

  3. Select the Resource Refs tab.



  4. Click the New References button and specify the following:

    • Resource Name: The name of the resource that the EJB references. For example, a database.

    • Description: A description of the resource. For example, a Java connection to a database.

    • Click into the Resource Class column and choose a data source from the list box.

      A resource class is a Java interface that specifies the type of data source, for example javax.sql.DataSource.

    • Authorization: Click in the Authorization column and choose Application or Container from the list box.

      Application specifies that the enterprise bean code signs on programmatically to the resource manager.

      Container specifies that it will sign on to the resource manager on behalf of the enterprise bean.

  5. Repeat steps 1-3 until all of the resource factories that the current EJB references are identified.


Security Roles (EJBs)

You use this tab to declare the security roles that are actually used within the organization using this application.

To edit the Security Roles of an EJB, perform the following steps:

  1. If the descriptor editor is not already open, click the EJB Descriptors tab at the bottom of the .jar archive window.

  2. Select an EJB at the left to declare its security roles deployment parameters.

  3. Select the Security Roles tab.



  4. Click the New Reference button to add a new row.

  5. Enter a new role name and role description used to set authorization to the EJB.


    Note The roles that you link to on the Security Role References tab must be specified on this tab (Security Roles).



Security Role References (EJBs)

You must identify any security roles that the current EJB references in its source code. The developer refers to roles but may not know how they fit into the security policies of your organization. You will then link these security role references to ones that were identified on the Security Roles tab.

To identify EJB security role references, perform the following steps:

  1. If the descriptor editor is not already open, click the EJB Descriptors tab at the bottom of the .jar archive window.

  2. Select an EJB at the left to declare its security role references deployment parameters.

  3. Select the Security Role Refs tab.



  4. Click the New Reference button to add a new row to the table.

  5. Complete the row as follows:

    • Referenced Name: Name by which the EJB's code refers to the security role. The developer refers to roles but may not know how they fit into the security policies of your organization. For example, the developer could use a security role of "Credit-Worthy Customer."

    • Link to Role: Name of the actual security role. You link a role that the developer has used to a role that is actually used within the organization using this application. For example, "Credit-Worthy Customer" could be linked to "VIP Customer."

    • Reference Description: A comment intended to assist the user who assembles the modules into an application .ear file when choosing a role.


Method Permissions (EJBs)

Method permissions specify roles for a method or an entire EJB. Only users and groups that are members of these roles are allowed to invoke the method or EJB.

The Allowed Roles shows which roles are currently able to access the EJB. You can set a different role access on an individual method. For instance, if the role "All Users" have access to a DataAccess bean, you can limit the users who may access the create() method of that bean.

To edit the EJB method permissions, perform the following steps:

  1. If the descriptor editor is not already open, click the EJB Descriptors tab at the bottom of the .jar archive window.

  2. Select an EJB at the left to declare its method permissions deployment parameters.

  3. Select the Method Permissions tab.



    The Allowed Roles displays the roles that have access any method in this EJB.

  4. To edit the allowed roles, click the Edit Default Roles button.

    A dialog box opens displaying the roles that have been defined on the Security Roles tab.

  5. To change role access on an individual method basis, click the Add Method Overrides button.

    A dialog box opens displaying a list of methods available.

  6. Choose a method and click OK.

    A row is added to the Roles with limited access box with the method name in the left column.

  7. To specify an role for this method that is different than those displayed in the Allowed Roles box, highlight the new row and click Edit Allowed Roles.

    A dialog box listing the roles that have been defined in the Security Roles tab opens.

  8. Select a role for this method and click OK.


Lightweight CMP (EJBs)

The Lightweight CMP tab is enabled when you are editing the deployment descriptor files for an entity bean. For container-managed persistence entity beans, the developer does not write the database access calls into the code. Instead, the container generates the database access calls at the time the entity bean is deployed (and installed into the container). You use this tab to specify the list of the instance fields for which the container must generate access calls. For more information about container-managed persistence, see the Programmer's Guide (Java).

The upper portion of this tab allows you to specify the database table where the EJB instances will be persistently stored. The table in the lower portion of this tab displays the variable fields (attributes) that the implementation class for the EJB has that you might want to store persistently. Also, displayed are the attribute's corresponding Java types.

Note if the loading of the EJB class failed, the table will be empty. An error dialog will appear explaining why the load failed. Normally, the table will have a row for each attribute and you cannot add or remove rows.

To edit the container-managed persistence for an entity bean, perform the following steps:

  1. If the descriptor editor is not already open, click the EJB Descriptors tab at the bottom of the .jar archive window.

  2. Select an EJB at the left to declare its container-managed persistence deployment parameters.

  3. Select the Lightweight CMP tab.



  4. Factory class: Enter the class which was used to create a PersistenceManager for this bean.

  5. Data Source: The name of the database that contains a table used for persistence storage, for example tnsnames.ora.

  6. Table: The name of the table within the specified database where you will persistently store instances of the EJB as rows.

  7. For Commit Option B enter (This option is currently not read by iAS):

    • Ready Pool Timeout

    • Ready Pool Cache Size

    Whenever an entity bean is used it is not destroyed immediately, instead it is cached in a pool for future use. The size of the pool is specified in Ready Pool Cache Size. Ready Pool Timeout is used for recycling the beans in the cache.

  8. For Commit Options C enter (This option is currently not read by iAS):

    • Free pool size

    All entity beans that are accessed are put in the free pool for future use and are not recycled.

  9. In the Database Column enter the names of columns in the database table.

    Each entry specifies a column in a table where the corresponding attribute's value will be stored. If no column name is entered, the value will not be stored at all. You should verify that the column names you enter actually exist in the database table and the types of those columns are suited to the types of EJB's attributes.

  10. In the Key column, check the box corresponding to an attribute if that attribute is (or is part of) the primary key for looking up instances of the EJB.

When you save an EJB-JAR archive that has entity beans with persistent storage, additional XML files are created in the META-INF directory, for example MyBean-ias-cmp.xml. These files contain SQL queries and other information that iAS can use when managing persistent storage for instances of the EJB.



About Creating an Application .ear File


An application .ear file consists of one or more modules (Web Application and EJB-JAR) and an application deployment descriptor. The application-level deployment descriptor, application.xml, is saved in the /META-INF directory of the archive. As a minimum, an application .ear file consists of modules and an application deployment descriptor. An application .ear file may also include libraries referenced by the modules, help files and documentation.


Creating an Application .ear File

To create an application .ear file that you can deploy, perform the following steps:

  1. From the iAS Deployment Tool, choose New, then J2EE Application.

    The New Application dialog opens.



  2. Enter an unique name for the application and click OK.

    The descriptor editor opens.



  3. Specify the General tab as follows:

  4. Display Name: Enter a short name for the application.

  5. Description: Enter an application description.

  6. Small Icon: Specify the location within the Web Application of a file (.GIF, JPEG) that contains the small (16X16 pixel) icon image used to represent the Web Application in a GUI tool.

  7. Large Icon: Specify the location within the Web Application of a file (.GIF, JPEG) that contains the large (32X32 pixel) icon image used to represent the Web Application in a GUI tool.

  8. Click the Modules tab.



    You must specify the modules to include in the application .ear file.

  9. Click the Add Module button to add a module.

  10. Navigate to the location of the module and click OK.

  11. Optionally, highlight an included module and click the Edit Descriptor button to create an alternate deployment descriptor file for a module.

    For example, if the module's deployment descriptor data contains vendor specific information that does not apply to this application, you can edit the module's descriptor to create an alternate deployment descriptor in the application package. Then when the application is deployed, the alternate deployment descriptor is used for that module.

  12. Optionally, highlight an included module and click the Extract Module button to copy the .war or .jar to your file system for editing.

    If you make changes that you want to include in the .ear file, you may need to remove the module from the .ear file and use the Add Module button to add back in the file that you extracted.

  13. Click the Files tab.



    In addition to the modules, you can also include libraries referenced by the modules, help files and documentation.

  14. Click the Security tab.



    You can use this tab to change a description of a security role that has already been specified in a module. For example, if two modules provide different descriptions for the same security role, you can enter a new description here. This description will be used by the Deployment Tool in preference to the descriptions found in the modules, and displayed to the person who deploys the application.


Linking References

As you assemble an application and prepare the application .ear file for deployment, you must verify that all EJB, Role, and Resource references have been linked as follows:

  • Link EJB Refs—You link references to EJBs in the code of the application components to EJB names in the application.

  • Link Role Refs—You link security roles in the source code to security roles defined on the Security Roles tab of the descriptor editor.

    The developer refers to roles but may not know how they fit into the security policies of your organization. You link these security role references with ones that are actually used within the organization using this application. The ones that an organization use are defined on the Security Roles tab of the descriptor editor for both Web Application and EJB-JAR modules.

  • Link Resource Refs—You link resource names referenced in the application component to actual resource factories.

These references and corresponding links were originally defined in the XML files at the module level. The iAS Deployment Tool presents the references to you in a series of dialog boxes.

To link references, perform the following steps:

  1. Choose Assembler, then choose one of the following:

    • Link EJB Refs

    • Link Role Refs

    • Link Resource Refs

    A dialog box similar to the following displays.



    When you click a reference in the left panel, a list of items that are compatible with it and can be linked to it are shown in the right panel. If the reference is already linked to an item, that item is highlighted.

  2. For a reference that is not yet linked, select the item you want to link to and click the Link button to establish the link.

    Or click the Unlink button to change the link of a reference that is already linked.

    The bottom panel shows the details of how the references are linked.

    It is recommended that all references are linked before deploying the application.



Saving Archive Files

As you use the iAS Deployment Tool to create .war, .jar, and .ear archive files, you can use the following commands to save the files.

  • Save (File menu)—Packs any new application components into the .war, .jar, or .ear archive and updates the descriptors in the XML files. Keep in mind that if you make any changes to the application components after they have been packed into the archive file, you will need to update them in the archive. You can do this by selecting the file on the Files tab and choosing Edit, then Update File.

  • Save Descriptor (Servlet, and EJB menus)—Writes the deployment descriptor data to memory. The deployment descriptor files are not updated until you save the archive with File, then Save.

  • Reset Descriptor (Servlet, and EJB menus)—Clears any deployment descriptor data saved to memory.

  • Save File List (File menu)—Writes the source file list to an intermediate .dml file, similar to a project file. The .dml file is simply a file list; the application components are not packed into it. You typically use this command when the application components are not finalized. When they are finalized, you can open the .dml file with the Deployment Tool and then choose File, then Save to save the file. The .dml file is then saved as an archive file with the application components included.



Managing Archive Files

As you use the iAS Deployment Tool to create .war, .jar, and .ear archive files, you can use the following commands to manage the files.

  • Update File (Edit menu)—Replaces a file in the archive with a file that you choose and keeps the existing deployment descriptor parameters. This option allows you to replace an existing file with a new version.

  • Remove File(s) (Edit menu)—Removes a packed file from the archive when it is no longer needed. Note that this command also removes any deployment descriptor parameters that are associated with the file.

  • Options (Edit menu)—Specifies the roots of the directory hierarchies where you keep different kinds of files.

    The iAS Deployment Tool tries to construct a single directory hierarchy for the archive file that contains your module, even when the component files come from different places in your file system. For example, you might have class files in directories under \usr\joe\classes and HTML files under \usr\fred\pages. Once the Deployment Tool is aware that these are the roots of the directory hierarchies where you keep different kinds of files, it can project the locations where files should be put within your archive. For example, the file \usr\fred\pages\yellow\start.html would be put in the archive at \yellow\start.html. This dialog box displays when a file being inserted is not under any of the roots known for the current module and prompts you to declare the root of the hierarchy in which this file resides. Use the arrow buttons to partition the file's absolute path into a root and a path relative to that root.

  • Properties (View menu)—Opens a Properties window when a application component is selected on the Files tab. You can then edit the path to which that file will be written within the archive when you save.

  • By Source/By Destination (View menu)—Toggles between showing the paths where the files now reside on your file system and the paths to which the files will be copied in your archive file when constructing an archive file from individual files, or when you load a file list (.dml).

  • Convert to iAS (Servlet, EJB, and Assembler menus)—Prepares a J2EE compliant .war, .jar, or .ear file to run under iAS. The necessary stubs are built and creates additional iAS-specific deployment descriptors using the defaults. Once the conversion is complete, you can save the archive file, verify iAS-specific settings with the descriptor editor and then deploy.


    Note This should be the FIRST task you complete when you import a J2EE application or module that was built with a tool other than iAB or iASDT (Deployment Tool).


  • Import from 4.0 (Servlet, and EJB menus)—Runs conversion utility and puts the result in a suitable directory and reads in the translated file. For EJBs, converts a properties file. For servlets, converts a NTV file.

    Note that this option replaces any descriptor information that you have already created, so it should be the first task you complete when you import into iASDT 6.0 an application that was built for NAS 4.0.

  • Register Data Source (Assembler menu)—Sends to a server the XML file that iAS uses to specify a data source, such as a database, which causes the server to register the data source so that applications can use it.

    This XML is created outside of the Deployment Tool. The following is an example of a data source definition file:

       <ias-resource>

        <resource>

        <jndi-name>jdbc/SampleOracleDB1</jndi-name>

        <jdbc>

          <database>shstest</database>

          <datasource>shstest</datasource>

          <username>kdemo</username>

          <password>kdemo>

          <driver-type>ORACLE_OCI</driver-type>

        </jdbc>

       </resource>

       </ias-resource>



Deploying an Application/Module

After you have created an application .ear file or a module, you can deploy the application to an iAS machine.

To deploy an application or module, use the iAS Deployment Tool to perform the following steps:

  1. From the iAS Deployment Tool File menu, choose File Open to open the Application .ear file you want to deploy.

  2. Navigate to the directory that has the deployable file, select the file and click OK.

  3. The archive window for that .ear file opens.

  4. Choose File, then Deploy.

    The Deploy Application or Module dialog displays.



  5. From the list of registered servers, choose one or more target iAS machines for deployment.

  6. Optionally, if you need to register additional servers, click Register.



    1. Enter the server name followed by the :port number. If no port number is given, it defaults to 10817.

    2. Enter the Admin user name and password specified during iAS installation.

    3. Click Register and the server is added to the list of registered servers.

    4. When you have finished registering servers, click the Close button.

  7. Click the Deploy button.

    The following dialog appears if your application has specified security roles. Note that you complete this dialog for each iAS machine targeted for deployment.



    Before you deploy an application, the security roles declared in the deployment descriptor data of the application or its modules must be bound to groups and users that are known to the server. This is for authentication when a user tries to gain access to a method or data that is under access control. This information is not part of the application's descriptor, since it can be different for different servers where the application might be deployed. This binding does not modify the application .ear file.

  8. Select a role and click the Bind button.

    The following dialog displays showing the groups which can be part of a role.



  9. Use the left and right arrow buttons to add or remove groups to and from the definition of the current role.

  10. When you are satisfied with the bindings, click OK.

  11. Repeat steps 8 thru 10 until all roles have been bound and then click OK.

    The status of the deployment process appears in a separate window.



    When the deployment process is complete, a dialog opens with a similar message, "Deployment of bank.ear to snickers complete." Deployment is completed to each machine in turn, if several iAS machines are targeted for deployment.

  12. Click the Messages window to select it, and choose File, then Save.

    The contents of the messages window is saved to messages.text in the current directory.



Enabling Support for Rich Clients

You can enable support for Rich Clients can communication directly with EJBs using the Internet Inter-ORB Protocol (IIOP). Typically, requests are made via a web path where requests originate at a Web Browser and then are processed by JSPs and servlets which in turn access EJBs. This web path uses the HTTP protocol. In the case of Rich Clients, requests are made through a Java program directly to EJBs using the CORBA Executive Server (CXS), a Java engine within iAS which acts as a bridge between Rich Clients and EJBs. For more information about Rich Client, see the Programmer's Guide (Java).

To enable EJB support for Rich Clients, perform the following steps:

  1. In the .jar descriptor editor, select an EJB at the left and click the iAS tab.

  2. Check the Enable RMI/IIOP box if you want that bean to specify that this bean should be accessible to the Rich Client.

    This will result in more stubs being built for that bean so that the container can intercept RMI calls to methods of that bean that arrive from a Rich Client.

  3. Repeat step 2 for each EJB that should be accessible to the Rich Client. When you are done, choose EJB, then Build All Stubs to rebuild the stubs for the affected beans, or build their stubs individually if you prefer, using Build Stubs.

  4. Choose EJB, then Save Client Jar.

    This command creates another .jar file which will contain the stubs and interfaces that must be present in your Application Client. This file will be named XXX-RmiCorba.jar where XXX is the name of your EJB-Jar module. The File, Save menu item will also automatically create this file while saving your EJB-JAR module. Note that not all of the additional stubs are needed by the Rich Client, the others must be present on the server machine, and are automatically added to your .jar file when you save it, so that they will be deployed when you deploy this module or an application which contains this module.

  5. Click OK to deploy the XXX-RmiCorba.jar file.

    The Deploy dialog displays for you to choose the target deployment servers.

  6. Select the target servers for which you want to deploy the XXX-RmiCorba.jar file and click the Deploy button.

    The JAR will be copied to <iAS installation directory>\ias\iasclient on the target server. Additionally, you will need to install the JAR file on the Rich Client.


    Note To enable Rich Client support, you need to create an Corba Executive Process (CXS) within iAS after you deploy. See Adding a CXS Process.


  7. Optionally, should you change your mind about wanting a bean to be accessible to your Rich Client, you will have to remove the extra stubs by hand; Select the Files tab and remove stub files whose names begin with an underscore or contain RmiCorbaBridge.



Upgrading an Application

Frequently, application developers must upgrade an application that is already installed on an application server. Upgrading an application involves re-deploying the application .ear file that contains updated application files to your iAS machine through the Deployment Tool, overwriting the previously deployed application.

Upgrading an application is sometimes necessary to fix bugs or to add features to deployed applications. The application developer is ultimately responsible for this upgrade; however, you as the administrator must work with the developer to prepare the iAS machine for the updated application files.

See the Programmer's Guide for specific information about application components and their requirements.



Deploying an Application Manually


After you create an .ear file, you may want to register the .ear file automatically via a batch file at a scheduled time and date. In this case, you would create the .ear file as you normally would using the iAS Deployment Tool, but you would not use the tool for deployment. Instead, you would use the j2eeappreg command to register the J2EE application.

To manually register a J2EE application, perform the following steps:

  1. Create a directory under <iAS install directory>/ias/APPS/<application name>

  2. Copy the application's .ear file to this newly created directory.

    For example, <iAS install directory>/ias/APPS/estore/estore.ear

  3. Verify that your username is the same as the one used to install iAS.

  4. Go to your applications deployment directory.

    cd <iAS installation directory>/ias/APPS/estore

  5. Execute the command:

       <iAS installation directory>/ias/bin/j2eeappreg
       <application name>.ear

    The j2eeappreg utility performs the following:

    • Connects to the directory server.

    • Parses the EAR file and embedded WAR and EJB-JAR files.

    • Registers the J2EE application in the iAS Registry within the directory server.

    • Registers the J2EE modules in the iAS Registry with the directory server.

    • Extracts the following files to the current directory:
      .jsp files
      classes referred to by .jsp files in USEBEAN tags
      JSP tag library descriptors
      static web content
      WAR and EJB-JAR files

    Complete the following steps to verify the application has been registered.

  6. Start the iAS Administration Tool:

    • On a Windows NT system: from the Start menu, choose Programs, then choose iPlanet Application Server 6.0. Finally, choose iAS Administration Tool.

    • On a UNIX system: first make sure your PATH variable contains the absolute path to the iAS bin directory and then type the following at the command prompt:

      ksvradmin &

  7. Click the Application button on the Administration Tool toolbar.

  8. Expand the iAS where you deployed manually.

    A new folder representing your newly registered application displays.




    Note Whenever a new application is deployed, the web server that sends requests to iAS must be re-started before running the application.



Previous     Contents     Index     DocHome     Next     
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.

Last Updated April 25, 2000