Facilities Guide
CHAPTER 6
This chapter presents some implementation details about the Novell exteNd Application Server. Topics include:
At the heart of the J2EE component model are containers. Containers are the runtime environments supplied by J2EE platform providers such as the Novell exteNd Application Server. Containers provide life-cycle management and other services, freeing application developers to focus on the presentation and business logic of their applications.
The application server implements each of the three kinds of J2EE container:
The Web container contains Web applications, which are packaged in Web archive (WAR) files. Each WAR you deploy to the application server functions as a complete, standalone application. The WAR file must contain all JSP pages, servlets, JavaBeans components, utility classes, static HTML pages, images, and sounds used by the application.
JSP pages and servlets Once you've deployed a WAR to the server, each JSP page in the WAR behaves like a servlet. The page is associated with an URL. When a Web client or server-side object performs an operation on that URL, the server finds the associated servlet, instantiates it, and calls the init() and service() methods associated with the servlet. When the servlet is about to be unloaded, the server calls the destroy() method.
The servlet context for any JSP page (or servlet) within the WAR is the WAR itself. That means a JSP page or servlet cannot forward to (or include) a JSP page or servlet that resides in a different WAR, since the WAR defines the boundaries of the application.
Persistence JSP pages running on the application server are not persistent. A new instance of a JSP page might be created for each HTTP request (depending on whether the JSP page is defined as threadsafe in the deployment descriptor).
Response The application server uses the Servlet API to implement response buffering. It uses the following methods of the ServletResponse interface to buffer response data:
Length If a servlet does not specify the length of its content by calling setContentLength(), the server uses HTTP 1.1 chunking to transfer the content as a series of chunks.
When a Web client or server-side object requests a resource in a WAR, the server breaks the request URL down into several components:
The following example shows the components of the URL for a WAR file deployed at myWar:
http://host/db/path/to/war/myWar/foo.jsp/pathinfo/for/jsp
Here the context path is /db/path/to/war, the servlet path is /myWar/foo.jsp, and the pathinfo is /pathinfo/for/jsp.
A JSP page or servlet can forward to (or include) any other JSP page or servlet that resides in the same WAR.
If you use the <jsp:forward> or <jsp:include> action, the target URL can be context-relative or page-relative. A context-relative URL begins with a slash (/) and is interpreted relative to the WAR. A page-relative URL does not begin with a slash and is interpreted relative to the current page.
Suppose the complete URL for a JSP page is http://localhost/myDatabase/jsptests/myjsps/test.jsp, and the URL you give to the WAR at deployment time is jsptests. In this case you can forward a request to the page by embedding the following tag in a JSP page in the same WAR:
<jsp:forward page="/myjsps/test.jsp"/>
In a servlet, if you use the getRequestDispatcher() method of the ServletContext object to specify the target URL, the URL is context-relative. It must begin with a slash and is interpreted relative to the WAR. To forward a request to http://localhost/myDatabase/jsptests/myjsps/test.jsp, you could embed the following code in a servlet in the same WAR:
ServletConfig sconfig = getServletConfig();
ServletContext sc = sconfig.getServletContext();
RequestDispatcher rd =
sc.getRequestDispatcher("/myjsps/test.jsp");
rd.forward(req, res);
The forward() method call passes the implicit request and response objects as arguments.
The application server can use either cookies or URL rewriting to track sessions. It uses cookies if the browser supports cookies and uses URL rewriting if the browser does not.
For more information, see the section on session management in the chapter on server configuration in the Administrator's Guide.
The EJB container provides the runtime environment for EJB2.0 and EJB 1.1 beans. The runtime environment includes such low-level services as naming, remote access, security, and transaction support.
This section describes the features of the EJB container and includes these topics:
The EJB container supports:
Message-driven beans—Message-driven beans let you access messages from a queue or a topic managed by the JMS message server.
Entity beans—Supports both bean-managed (BMP) and container-managed (CMP) entity beans. It supports the following entity bean features:
This section describes the services provided when an EJB is deployed an application server.
The EJB container provides debugging support at both deployment time and runtime.
Deployment debugging support Deployment debugging support is provided through the command-line tool SilverCmd. The following table describes the commands that are most useful for debugging:
For more information on SilverCmd, see SilverCmd Reference.
Runtime debugging support Runtime debugging support is provided through a server startup switch or a command shell from the server console. The following table describes the switches and how to use them:
The EJB container supports instance pooling for entity, stateless session, and message-driven beans. Pooling is per bean and is specified in the deployment plan. To reconfigure the pool size, redeploy the bean with an updated deployment plan.
For entity and session beans, you specify values for the following:
Entity and stateless session bean pooling policies The EJB container does not create the instance pool when you deploy the bean; instead, it populates the pool as the need for instances increases:
When the poolingPolicy element is set to FAIL, the server throws an exception when maximum pool size is exceeded.
When the poolingPolicy element is set to CREATE, the server manages the pool as follows:
When the pool is below the maximum size, the container does not wait for an instance to be freed; it simply creates a new instance for the caller
Before the pool reaches maximum pool size, the container returns instances to the pool when clients are finished with them
While the pool is at maximum pool size, the container discards instances when clients are finished with them
For message-driven beans, the container provides instance pooling by implementing the ServerSessionPool interface.
Stateful session bean passivation The application server monitors memory usage by measuring the Garbage Collection (GC) rate. When the GC rate increases significantly, the server will start stateful session beans passivation. To disable the monitoring and passivation, add the following line to the httpd.props file:
http-server.com.sssw.srv.disableMemMonitor=false
The httpd.props file is located in the server's \Resources directory.
Load balancing is per session. All EJBs used within a single session reside on one server within the cluster. Load balancing is transparent to the user; the client can do a normal JNDI lookup, and the naming server selects the server for the bean to run on.
When using EJBs within a cluster, you must start your servers on different name service ports. The default name service port is 54890. You can configure the name service port via the SMC.
For more information on application server clustering mechanisms, see the chapter on administering a cluster in the Administrator's Guide.
EJBs are registered in the root context of the Java Naming and Directory Interface (JNDI). If you specify a hierarchical naming structure for JNDI names, bean references, resource references, environment variables, or UserTransactions in the deployment plan, the container creates any intermediate subcontexts that do not already exist.
By default, the server registers bean references, environment variables, and resource references in the java:comp/env context. You can follow the recommendations of the EJB specification and store the objects in separate subcontexts, but the application server does not enforce these naming conventions. That means you can use the naming conventions that work best in your own production environment.
The application server supports access to EJBs via RMI/IIOP using Novell exteNd ORB (Object Request Broker). exteNd ORB is an enterprise-class Java-based CORBA ORB and is part of the Novell exteNd Messaging Platform.
For more information on exteNd ORB, see the Novell exteNd Messaging Platform help.
For portable lookups for EJBs, use the CORBA name syntax—like this:
corbaname:iiop:host:port#name
For example:
corbaname:iiop:MyMachine:54520#MyEJB
Client access A client accessing an EJB needs a JAR that contains the EJB's interfaces (for compile-time references) and the container-generated stubs (for runtime).
EJB developers should create an EJB client JAR and verify that the deployment descriptor includes the ejb-client-jar element. When this element is present, the container generates stub classes, places the stubs in the client JAR, and uploads the client JAR to the server.
Since the EJB client JAR is generated by the container and resides on the server, you'll need to download the JAR from the server to the appropriate location on disk. Put the disk location of the EJB client JAR on the classpath of the client. Remember to download a new version of the EJB client JAR each time you make changes to the EJB and redeploy it.
To look up a local bean use:
EJBLocalHome/beanName
The EJB container manages security at runtime using:
When you call an EJB, the server authenticates the user and uses the caller's identity for the duration of the caller's session on that server. All method calls run with the identity of that session. You can map a role name to a principal (user, group, or list of principals) in the deployment plan.
Access authorization is defined by the security-role and method-permission elements specified in the deployment descriptor. If you secure at least one method of a bean in the EJB JAR, you must secure all methods—or the container assumes all methods with unspecified security are restricted and cannot be called by any user. In addition, you can specify a set of methods that should not be called using the exclude-list element of the deployment descriptor. When a restricted method is called, the container throws an AccessRightsViolation Exception. Alternatively, you can choose a nonsecure mode by not securing any methods.
You can establish a secure connection between an EJB client and the application server using SSL. Novell exteNd ORB provides the IIOP over SSL support for RSA only.
You do not need to be running HTTPS. The following are required:
Clients also need the agrootca.jar, as described in Supporting access to secured EJBs.
For more information on establishing a secure connection between an EJB client and the application server, see the chapter on setting up security in the Administrator's Guide.
The EJB container supports distributed transactions via the Novell exteNd JTS server, which fully implements Java Transaction Service (JTS).
If the transaction attribute is not specified in the deployment descriptor, the container uses the Supports attribute as the default transaction attribute.
J2EE application clients are the standard way to provide Java-based clients that run on user machines and access J2EE servers. They are hosted by a client container that (at a minimum) provides JNDI namespace access. Beyond that, the J2EE specification allows for a wide range of client container implementations, from basic to robust.
The application server supplies a client container named SilverJ2EEClient that users can invoke to run J2EE application clients you've deployed to the server. SilverJ2EEClient provides a robust set of supporting services, including:
For details, see SilverJ2EEClient.
The application supports session-level failover for Web applications (WARs) and stateful session beans (EJB JARs). Session-level failover refers to the ability of an application to retain temporary user data (state) across server failures in a cluster. The data is stored in a persistent storage repository (such as a database or file system shared by the servers in the cluster) so that it can be recovered by any server in the cluster in the event of a server failure.
To support session-level failover, you must have a hardware dispatcher installed as the dispatcher for your cluster. All clients accessing the applications configured for session-level failover should access the application via the cluster's (hardware) dispatcher.
Failover support is not a mechanism for load-balancing EJBs belonging to a single session across multiple servers.
The EJB container supports session-level failover for stateful session beans (local and remote). The stateful session beans must meet these requirements:
The recoverable element in the deployment plan must be set to true.
The session bean must support activate and passivate as described in the section on instance passivation and conversational state in the EJB2.0 specification.
The session bean's methods must be transactional (specified in the deployment descriptor). Changes to the session bean's state that occur outside a transaction are not recoverable if the system crashes; changes to the session bean's state that occur in the context of a transaction are recoverable.
If your session beans meet the requirements listed above and a failure occurs, the recovery works like this:
At the end of each transaction that includes one or more recoverable stateful session beans, the EJB container passivates and serializes all recoverable beans used in the transaction and saves them to the database (the AgSessBeans table in the SilverMaster database).
As long as the server is up, the client will continue to use the same server.
If the client gets a communication failure on a remote call, it assumes the server failed:
If the failure occurs between transactions, the client automatically chooses another server in the cluster and retries the call to it (it does not require a hardware dispatcher). The session bean's state is then restored from the database on the new server just as though the bean had been previously passivated.
If the failure occurs when there is already a transaction in progress, the call is not automatically retried. Instead, the transaction is rolled back and the client gets the exception. It is the client's responsibility to recover from a transaction rollback (for example, the client can retry the call).
The performance of your EJB applications might be impacted if the recoverable session bean does a lot of work in the ejbActivate() method. For example, if the session bean allocates and caches a database connection.
To support session-level failover when using IIOP over SSL, you must also configure a range of ports for IIOP SSL communications for the server.
For more information on setting the range of ports, see the section on specifying ORB settings in the Administrator's Guide.
The WAR container supports session-level failover. The Web application must meet the following requirements:
The distributable element must be present in the deployment descriptor.
The recoverable element in the deployment plan must be set to true.
The components in the WAR must follow the rules about distributable objects outlined in the Servlet 2.3 specification.
If your Web application meets the requirements listed above and a failure occurs, the session-level failover recovery works like this:
On each HTTP request to the Web application, the server serializes the HTTPSession state to the database (the AgSessBeans table of the SilverMaster) at the end of each request.
Because the container passivates, serializes, and saves the HTTPSession state to the database at the end of each HTTP request, this can impact the overall performance of the application.
As long as the server is up, client requests will continue to be directed to the same server.
If the server fails between requests and you have a hardware dispatcher, the dispatcher detects the server failure and sends the next request to a different server.
The new server restores the HTTPSession state from the database and the operation continues without interruption.
If the server fails during a request, the browser will eventually time out the response. When the user resubmits (assuming a hardware dispatcher), the resubmitted request goes to a new server that restores the HTTPSession state as described above.
If you use the application server's software Dispatcher (instead of a hardware dispatcher), the user application will have to manually return to the dispatcher after the failure to be redispatched. Once redispatched, the new server will not automatically restore the state, since the session ID cookie will be different.
Because the HTTPSession state is not transactional, updates to the HTTPSession during a request can be lost under certain circumstances—for example, if the server crashes during a request (but before the state is saved). However, if the server crashes after the state is saved but before returning a reply, the state can be recovered.
A J2EE client application can access Web application components or EJBs that support session-level failover as long as the Web components and EJBs meet the session-level failover requirements described in Web application support for session-level failover just above. The J2EE client must initially connect to the cluster's (hardware) dispatcher like this:
SilverJ2EEClient dispatcher-name:port database-name application-name
For details on SilverJ2EEClient, see SilverJ2EEClient.
The application server includes Novell exteNd ORB. exteNd ORB is an enterprise-class Java-based CORBA ORB. You can use exteNd ORB from the application server, SilverJ2EEClient, or any browser. You can use exteNd ORB to develop, deploy, and manage Java-based CORBA applications. The application server uses the following subset of features:
For more information on exteNd ORB, see the Novell exteNd Messaging Platform help.
XML (eXtensible Markup Language) allows you to create XML documents that can be used to exchange data between computer systems (of different types) and applications on the Web. This section describes the application server's use of and support for XML documents and includes the following topics:
The application server uses XML documents for:
For information, see:
If you're new to XML or just need to explore a specific XML topic, try the following learning resources:
This section describes the following internationalization topics:
All JDBC drivers certified for use with the application server have been fully tested to support Western/Eastern European and Asian languages.
To use the multibyte version of the server's JDBC-ODBC bridge driver:
Add the following line to AgUserIni.props in your server's \Resources directory:
com.sssw.srv.ambry.mbcs.AgOdbc=true
The application server includes runtime language libraries for Simplified and Traditional Chinese, English, French, German, Italian, Japanese, Korean, Portuguese, Russian, and Spanish.
If you encounter font-mapping problems in SilverJ2EEClient where the correct characters are not displaying, you can fix the problem by editing the JRE's font.properties file. You must edit the font.properties.XX file in the Novell exteNd Common\jre\lib directory (where XX is the two-character language encoding for the language you are interested in). For example, you would edit font.properties.ko for Korean.
Two sections in the file There are two sections of interest in the file that appear one after the other. They are labeled name aliases and for backward compatibility.
The original version of font.properties.ko is:
# name aliases # # alias.timesroman=serif # alias.helvetica=sansserif # alias.courier=monospaced # for backward compatibility timesroman.0=Times New Roman,ANSI_CHARSET helvetica.0=Arial,ANSI_CHARSET courier.0=Courier New,ANSI_CHARSET zapfdingbats.0=WingDings,SYMBOL_CHARSET
How to proceed The name aliases section maps nonexistent font names to font mappings defined in the file. You should uncomment those alias lines. (This is the preferred way of handling the mapping. The section for backward compatibility is the old way of mapping nonexistent font names to fonts described in the file.)
NOTE: You need to comment the first three lines of this section.
The updated version of the file would then be:
# name aliases # alias.timesroman=serif alias.helvetica=sansserif alias.courier=monospaced # for backward compatibility # timesroman.0=Times New Roman,ANSI_CHARSET # helvetica.0=Arial,ANSI_CHARSET # courier.0=Courier New,ANSI_CHARSET zapfdingbats.0=WingDings,SYMBOL_CHARSET
Copyright © 2003 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...