iPlanet Application Server Third Party Integration Tools

Integration with VisualCafeTM

Menu Reference

The iPlanet Application Server Integration Tool adds:

iPlanet Functionality Menu Items

The enhanced iPlanet functionality menu items provided by the iPlanet Application Server Integration tool include:

Execute

If this is the first time you are executing an iPlanet Web Application project, a dialog appears prompting you to enter the username and password for the administrator of the local application server. Your local iPlanet Application Server is then registered and set as the default server for all your projects.

In addition, the Execute command packages the project in the <appName>.war file needed to run your application on the iPlanet Application Server. It then deploys the package to run on the application server.

The Execute command initiates the following actions:

This command uses the local server.

Run in Debugger

Run in Debugger initiates debug mode enabling you to debug your program using:

As you find and correct errors, debugger mode is no longer active. However, once you recompile, you can restart the debugger.

For more information on runtime editing with the VisualCafé Expert Edition, see Incremental debugging features in the VisualCafé online help.

The Run in Debugger command performs in the same manner as the Execute command. However, with the Run in Debugger command instead of launching the application in a new window, the project is launched in the VisualCafé debugger and no browser window opens.

This command uses the local server.

Step Into

Selecting Step Into from the Project menu runs your program in the debugger by stopping at the first line of the source code. In an iPlanet project, the application runs until the first line of the first class in the project that starts the engine.

This command uses the local server.

Deploy

The Deploy command deploys the selected application to the iPlanet Application server.

Start EJB Server

If the registered server is not already running, the Start EJB Server command starts the iPlanet Application Server as a Service on the local machine. This command is only active in an EJB project.

This command uses the local server.

Shut Down EJB Server

The Shut Down EJB Server shuts down the application server if it was started as a Service on the local machine from an EJB project.

This command uses the local server.

Configure Deployment Descriptor (for EJBs)

When you implement an EJB project, the Configure Deployment Descriptor dialog displays the Deployment Configuration dialog.

The Configure Deployment Descriptor dialog includes a Target Options Tab to set deployment descriptors for the EJB project that is currently open.

Before you can add an EJB Reference to the Target Options Tab, you must add it to the Environment EJB Reference Tab.

For more information, see the VisualCafé Online Help.

New Menu Items

The new menu items that enable iPlanet Application Server functionality include:

Start Application Server

If the registered application server is not running, the Start Application Server menu item is active. By default, it is set to start the iPlanet Application Server.

Shut Down Application Server

If the registered application server is running, the Shut Down Application Server menu item is active. By default, it is set to shut down the iPlanet Application Server.

Execute in iPlanet Server

The Execute in iPlanet Server command builds, deploys, and executes the current project in the iPlanet Application Server.

This command uses the server specified in the current project, not the server set in the Environment Options.

Deployment Configuration Menu Items

Web Applications and servlets include these corresponding deployment configuration menu items:

Configure iPlanet Web Application

From the Project menu, you can select the Configure iPlanet Web Application menu item to configure your iPlanet Web Application for deployment to the iPlanet Application Server. Through the Configure iPlanet Web Application item you can configure deployment information for the following tabs:

General Tab

The General deployment descriptor tab allows you to set the following fields or columns:

Field/Column Description
Name Enter a short name to be displayed by GUI tools. For example, bank.war could be named bank.
Description Enter descriptive text about the web application.
Distributable If checked, 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 (seconds) Enter the number of seconds to specify a default session timeout interval for all sessions created in this web application. The default is 500 seconds.
Welcome Files Enter the path to the welcome file(s) in the Web Application module. If your application starts with a page other than a logon, you can specify the start page here. The server tries to load the first file from this list, if the file is loaded successful, the server ignores the others. Otherwise, the server tries to load the next file until the end of the file list is reached.
Authentication Type Specify the Authentication Type while logging onto the Web Application: None, Basic, Digest, Form, Client Cert.
Authentication Type: None If selected, no authentication is required while logging on to the Web Application. This is the default.
Authentication Type: Basic If selected, the HTTP Basic Authentication protocol is used for authentication. The authentication is based on a username and password. The web client obtains the username and password and transmits them to the web server using base64 encoding. The web server then authenticates the user.
Authentication Type: Digest If selected, the HTTP Digest Authentication is used for authentication. The authentication is based on passing the username and password in an encrypted form. Digest is not used by iPlanet Application Server 6.0, Service Pack 1, or Service Pack 2.
Authentication Type: Form If selected, the developer controls the look and feel of the login screens, unlike the HTTP browser's built-in authentication mechanisms.

Realm Name: Name to be used for authentication with this Web Application. Realm names are not used by iPlanet Application Server 6.0, Service Pack 1, or Service Pack 2.

Login Form: Enter the location of the login page (login.jsp).

Login Error Page: Specify the location of the error page (error.jsp) used with this type of login. The error page is displayed when the authentication is not successful.
Authentication Type: Client-Cert If selected, 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 the iPlanet Application Server tab for web applications.

Context Tab

Use the Context tab to declare the web application's servlet context initialization parameters. These are accessed by: 

ServletContext context = getServletContext()
//returns context
context.get;InitParameterNames()
//returns enumeration of init parameters
config.getInitParameter(<paramName>)
returns value of a specific parameter

Field/Column Description
Name Enter a name for the parameter.
Value Enter a value for the parameter.
Description Enter a description for the parameter.
Add button Click to add a row to the Context table to specify the web application's servlet context initialization parameters.
Remove button Click to remove the selected row from the Context table.

Environment Tab

Use the Environment tab to identify environmental elements specific to your web application such as sales tax rates or zip codes.

Field/Column Description
Key Name Enter the name of the property. For example, if you are going to enter a zip code, enter the city name in this column.
Type Select the column and choose a desired datatype for the property.
Value Enter the value of the property.
Add button Select to add a column in the table to define the environment properties.
Remove button Select to remove the selected row from the table.

Errors Tab

Use the Errors tab to map error codes to a resource within the web application. This defines what resource will be used (or HTML page to display) if an error occurs.

Field/Column Description
Error Enter an error code or exception type. For example, HTTP error 404 (indicating that the web server cannot find the requested file or script). When specifying an exception type, enter a fully qualified class name of a Java exception type.
Path Enter the location within the web application of the resource to use when this error or exception occurs. For example, an HTML page to display.
Add button Adds a row to the Errors table to map an error to a resource.
Remove button Removes the selected row from the table.

Session Tab

Use the Session tab to configure the web application targeted to your operational iPlanet Application Server environment. For example, the iPlanet Application Server supports single sign-on for multiple web applications. You can create multiple applications where the user needs to log on (be authenticated) only once. For example, you can create 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 log on information can be used by each of the individual airline sites without requiring the user to log on again.

Field/Column Description
Distributed Session If checked, a session can be distributed across multiple iPlanet Application Server machines.

A session can be a distributed fault-tolerant session, or a lightweight local-only session. Local sessions are only available locally in one engine, and have to depend on requests being sticky (See iPlanet Application Server deployment descriptors in the Online Help for more information.) In addition, local sessions have no fault-tolerance if the engine crashes.
Secure Session If checked, the session can only occur on a secure (HTTPS) server.
TimeOut(seconds) Enter a period in seconds that specifies when the client is no longer active. If unspecified, a system-wide default session timeout of 30 minutes is used.
Timeout Type Specify when the timeout count begins: since last access or since session creation.
Data Synchronization If you specified a distributed session on this tab, then select the session type: dsync-local or dysnc-distributed. DSync distributed helps failover across instances of the application server participating in a cluster.
Domain (supports single sign-on) Enter the domain where 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 where the cookie is sent back. You can specify a different domain here, if needed.
Path (supports single sign-on) Enter the path for the session cookie (i.e. the minimum path the URL must have for the cookie to be sent back from the browser. For example, setting the path to /phoenix, sends the cookie back when either of the following URLs are accessed: 

http://my.foo.com/phoenix/bees.htm
http://my.foo.com/phoenix/birds.htm

The path must begin with slash (/). If the path is not set, the default path is assumed to be that of the URL setting the cookie.

Scope (supports single sign-on) A grouping name that identifies applications participating in single sign-on. Each application participating in a single sign-on for a grouping of applications must use the same grouping name.

For example applications such as login, homeBanking, loanCenter within the same application server cluster, can share a session by specifying the same scope variable, myBank.

MIME Tab

Use the Mime tab to identify the mapping between MIME types and MIME Extensions for your web application.

Field/Column Description
MIME Type Enter a MIME type for a file such as text/html or image/gif for files used within your web application.
MIME Extension Enter the file extension in the column that corresponds to the MIME type.
Add button Adds a row in the MIME Types table.
Remove button Removes the selected row from the MIME Types table.

Refs Tab

Use the References tab to identify any of the following references in the source code of any of the web application components:

Field/Column Resource Factory References Description
Resource Name Enter the name of the resource the web application component references. For example, a database.
Description Enter a description of the resource. For example, a JDBC connection to a database.
Resource Class Select 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 Select the authorization type as follows: Application or Container.

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

Container specifies that the enterprise bean code sign on to the resource manager on behalf of the enterprise bean.
JNDI Name Enter the Java Naming and Directory Interface (JNDI) name by which the resource factory is known. The JNDI name becomes the name of the module and the reference name of the resource factory.

Field/Column References to EJB Description
Reference Enter the name of the EJB referenced in the source code of a component of the web application and should match the string used for EJB lookup.
Bean Type Click in the Bean Type column and choose the Bean Type:Session or Entity.
Linked to Bean Click in 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 Choose the authorization type as follows: Application or Container.

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

Container specifies that the enterprise bean code sign on to the resource manager on behalf of the enterprise bean.
JNDI Name Enter the Java Naming and Directory Interface (JNDI) name by which the resource factory is known. The JNDI name becomes the name of the module and the reference name of the resource factory.

SecRoles Tab

Use the Security Roles tab to identify any security roles that the servlet references in its code.
Field/Column Description
Referenced Name Enter the name by which the servlet's code refers to a security role. The developer will often refer to roles in the servlet's code without knowing how these names fit into the security policies of the organization using the web application. For example, the developer could use a security role of: Credit-Worthy Customer.
Link to Role Name of the corresponding security role used within the company. This maps the security role that the developer uses to a role that is actually used within the organization using this web application. For example, Credit-Worthy Customer could be linked to VIP Customer.
Reference Description Enter a comment intended to assist the user who assembles the modules into an application.ear file when choosing a role.

Security Tab

When specifying a security constraint, first define the resource collection then map the resource collections to roles. Then specify the transport layer constraint of the user data. You define the resource collection in the first part of this tab.

Field/Column Description
Collection Enter a name for the resource collection.
URL Pattern Enter the URL pattern(s) for this resource collection as a comma delimited list.
Method Enter the HTTP method(s) as a comma delimited list for this resource collection.

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

The following information is used to map resource collections to roles and specify the transport layer.

Field/Column Description
Security Constraint Enter a name for the security constraint or accept the default.
Collection Enter a one or more resource collection names that you want apply access control.

The resource collection names must be predefined in the top half of this tab.
Roles Enter the roles 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 this column must be defined in the Link to Role column on the Security Role Refs tab for servlet descriptors.
Transport Guarantee Click in the column and choose NONE, INTEGRAL or CONFIDENTIAL to define the type of communication between the client and server as follows:

NONE: The application does not require any transport guarantees.

INTEGRAL: The application requires that data sent between the client and server is not changed in transit (SSL is required).

CONFIDENTIAL: The application requires that data sent between the client and server is not read during transit (SSL is required).
Add button Click to add a new row for you to specify access control for a resource collection.
Remove button Click to remove the selected row from the table.
Edit Collection button Select a row in the table and click the Edit Collection button to open a dialog where you select a new collection name.

The dialog displays collection names that have been created in the first half of this dialog.
Edit Roles button Select a row in the table and click the Edit Roles button to open a dialog where you can select one or more roles that are allowed to access the resource collection.

The dialog displays role names that have been specified on the Roles tab for web applications.

Servlets Tab

Use the Servlets tab to specify the mapping between servlets and the URL pattern that invokes them. Also use this tab to identify any JSP tag libraries used within the web application.

Field/Column Description
Servlet Name After adding a row to the Servlet Mapping table, click in the column and select a servlet that is included in this web application.
URL Pattern Enter a comma delimited list of the URLs that will invoke the servlet.
JSP Tag Lib URI Enter a URI, relative to the location of the web.xml file identifying a Tag Library used in the web application.
JSP TLD Location Enter the location of the Tag Library Description file for the Tag Library relative to the root of the web application.

Configure Servlets

From the Project menu, select Configure Servlets to configure your iPlanet Servlet project for deployment to the iPlanet Application Server. This command opens the Configure Servlets deployment descriptor editor which includes the following tabs:

General Tab

Use the General tab to specify overall properties for a servlet in the web application. You need only to specify deployment descriptors for web application components that the user can access directly.

Field/Column Description
Servlet Name Enter the name of the servlet.
Display Name Enter a short name that will be displayed by the GUI tools accessing this servlet or JSP.
Servlet Class For servlets, displays the fully qualified class name of the servlet.
URL Pattern Displays a comma delimited list of the URLs that invoke the servlet. This information is read from the Servlet (WAR) tab shown in the URL Pattern field.
Description Enter a description of the servlet.
Load Order Enter a number to specify 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 Tab

Use the iAS tab to define iPlanet Application Server-specific options for the servlet to configure the servlet to your targeted operational iPlanet Application server environment.

Field/Column Description
GUID This is the Globally Unique ID that is provided by the Deployment Tool assigned when you registered this servlet.
Number of Singles Enter the number of objects in the servlet pool, when SingleThread mode is used.

In the case of a servlet that implements the SingleThreadModel interface, the servlet container will instantiate multiple instances of that servlet (number of singles) so that it can handle a heavy request load while still serializing requests to a single instance.

In all other cases where the servlet does not implement the SingleThreadModel interface, the container instantiates a single servlet instance per servlet definition per KJS and this option does not apply.
Error Handler Enter the path to a servlet or JSP file to handle messages used when the Error Handler on the iAS Param tab is set to log.
Validation Required If checked, input parameters of a servlet defined in the ias-web.xml file (or on Init Params tab of the DD editor) are validated.
Disable Reload If checked, disables dynamic reloading of this servlet instance.

Otherwise, recompilation or redeployment of this servlet will cause dynamic reloading of the corresponding servlet instance for new requests, without restarting KJS or the iAS instance.
Encryption If checked, specifies communications to the servlet are encrypted for security considerations.
Cache timeout Set a time-out value in seconds for the caching of the servlet. If you set this value to zero, caching is disabled.
Cache size Set a cache size for the servlet. If you set this value to zero, caching is disabled.
Caching criterion 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.

The following table allows you to customize sticky load balancing for this servlet on each iPlanet Application Server machine targeted to deployment. If this table is blank, the Sticky checkbox applies to all deployment machines.

Field/Column Description
IP Address Enter the IP address of the iPlanet Application Server instance you want to customize.
Port Set to true/false to apply/disable sticky load balancing for this servlet on the iAS machine.
Sticky LoadB Set to true/false to apply/disable sticky load balancing for this servlet on the iAS machine.
Sticky LoadB Check to specify that sticky load balancing is activated for this server.
Enable Click to remove the selected row from the Server Information table.
Add Server Click to add a row to the Server Information table.
Remove Server Click to remove the selected row from the Server Information table.

InitParams Tab

Use the Init Params tab to specify initialization parameters that are set in the init() call when the servlet is loaded. The initialization parameters are accessed in the following manner: 

ServletConfig config= getServletConfig() - returns configuration
config.get;InitParameterNames() - returns enumeration of init parameters
config.getInitParameter(<parmName>) - returns value of specific parameter

Field/Column Description
Name Enter the name of the parameter.
Value Enter the value of the parameter.
Description Enter a description of the parameter.
New Parameter button Click to add a new row to the table where you can specify an initialization parameter.
Delete Parameter button Click to remove the selected row from the table.

Copyright ©2000, Sun Microsystems Inc. All rights reserved.
Copyright © 2000, Netscape Communications Corporation. All rights reserved.

Sun, Sun Microsystems, the Sun logo, Java, iPlanet, and the Sun, Java, and iPlanet-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

Netscape and the Netscape N logo are registered trademarks of Netscape Communications Corporation in the U.S. and other countries. Other Netscape logos, product names, and service names are also trademarks of Netscape Communications Corporation, which may be registered to other countries.