Chapter 9 Creating Enterprise JavaBean Clients

Instantiating home interface proxies

EJB clients use the Java Naming and Directory Interface (JNDI) to resolve logical Bean home names to proxy instances for a Bean's home interface. Each EJB container vendor provides an implementation of this interface that works with the vendor's server and network protocol.

Obtaining an initial naming context

The core JNDI interface used by client applications is javax.naming.Context, which represents the initial naming context used to resolve names to Bean proxies. To obtain an initial naming context, initialize a java.util.Properties instance and set the properties listed in Table 9-2. Pass the properties instance to the javax.naming.InitialContext constructor. The code fragment below shows a typical call sequence:

import javax.naming.*;

static public Context getInitialContext() throws Exception {
    java.util.Properties p = new java.util.Properties();

    // Sybase implementation of InitialContextFactory
    p.put(Context.INITIAL_CONTEXT_FACTORY,
          "com.sybase.ejb.InitialContextFactory");

    // URL for the Server's IIOP port
    p.put(Context.PROVIDER_URL, "iiop://myhost:9000");

    // Username "pooh", password is "tigger2"
    p.put(Context.SECURITY_PRINCIPAL, "pooh");
    p.put(Context.SECURITY_CREDENTIALS, "tigger2");

    // Now create an InitialContext that uses the properties
    return new InitialContext(p);
}

EJB servers from different vendors require different InitialContext property settings. If you are creating a client application that must be portable to other EJB servers, use an external mechanism to specify properties rather than hard-coding values in the source code. For example, in a Java application use command-line arguments or a serialized Java properties file. To specify properties used by a Java applet, use parameters in the HTML Applet tag that loads the applet.

Sybase InitialContext properties

The Sybase InitialContext implementation recognizes the properties in the following table. You can create multiple contexts with different properties. For example, you might create one context for proxies that connect with plain IIOP and another for proxies that connect using SSL.

Table 9-2: Sybase EJB 1. 0 InitialContext Properties
Property name	Description
java.naming.factory. initial	Specifies the fully qualified Java class name of the class that returns javax.naming.InitialContext instances that interact with the naming provider. Use `com.sybase.ejb.InitialContextFactory` for Jaguar EJB clients.
java.naming.provider. url	Specifies the URL to connect to the Jaguar name server. Set the value to a URL with the following format: `iiop://hostname:iiop-port/initial-context` where: hostname is the host machine name for the Jaguar server that serves as the name server for your application. If omitted, the default is `localhost` . iiop-port is the IIOP port number for the server. initial-context is the initial naming context. This can be used to set a default prefix for name resolution. For example, if you specify USA/Sybase/, all names that you resolve with the context are assumed to be relative to this location in the name hierarchy. When specifying the initial context, the trailing slash is optional; it is added automatically if you do not specify an initial context that ends with a slash. If you do not set this property, the default is `iiop://localhost:9000/` .
java.naming.security. principal	Specifies the user name for the Jaguar session. Required if user name/password authentication is enabled for your Jaguar server.
java.naming.security. credentials	Specifies the password for the Jaguar session. Required if user name/password authentication is enabled for your Jaguar server.
com.sybase.ejb. isApplet Applicable only to Java applets.	Specifies whether the client application is a Java applet. The default is `false` . You must set this property to `true` in Java applets if the applet connects to Jaguar using SSL (https).
com.sybase.ejb. http	Specify whether proxies should use HTTP tunnelling without trying to use plain IIOP first. The default is `false` . With the default setting, the proxy tries to open a connection using plain IIOP, and switches to HTTP tunnelling if the plain IIOP connection is refused. The default is appropriate when some users connect through firewalls that require tunnelling and others do not; the same application can serve both types. If you know tunnelling is required, set this property to `true` . This setting eliminates a slight bit of overhead that is incurred by trying plain IIOP connections before tunnelling is used.
com.sybase.ejb.http. jaguar35Compatible	When set to true, specifies that HTTP tunnelling must be compatible with version 3.5 or older Jaguar servers. The default is false. Compatibility with version 3.5 or older servers The default tunnelling model is incompatible with servers older than version 3.6. If you do not set the `com.sybase.ejb.jaguar35Compatible` property to true, clients using the Jaguar 3.6 or later Java client runtime cannot connect to older Jaguar servers using HTTP tunnelling. Note that HTTP tunnelling may happen automatically when clients connect to the Jaguar server through firewalls.
com.sybase.ejb. RetryCount	Specify the number of times to retry when the initial attempt to connect to the server fails. The default is 5.
com.sybase.ejb. RetryDelay	Specify the delay, in milliseconds, between retry attempts when the initial attempt to connect to the server fails. The default is 2000.
com.sybase.ejb. socketReuseLimit	Specify the number of times that a network connection may be reused to call methods from one server. The default is 0, which indicates no limit. The default is ideal for short-lived clients. The default may not be appropriate for a long-running client program that calls many methods from servers in a cluster. If sockets are reused indefinitely, the client may build an affinity for servers that it has already connected to rather than randomly distributing its server-side processing load among all the servers in the cluster. In these cases, the property should be tuned to best balance client performance against cluster load distribution. In Sybase testing, settings between 10 and 30 proved to be a good starting point. If the reuse limit is too low, client performance degrades.
com.sybase.ejb. ProxyHost	Specifies the machine name or the IP address of a reverse proxy server. See "Using reverse proxies" for more information.
com.sybase.ejb. ProxyPort	Specifies the port number of a reverse proxy server. See "Using reverse proxies" for more information.
com.sybase.ejb. local Deprecated.	For server-side component use only. Specifies whether the proxy references can be used to issue intercomponent calls in user-spawned threads. The default is `true` , which means that intercomponent calls are made in memory and must be issued from a thread spawned by Jaguar. Set this property to `false` if your component makes intercomponent calls from user-spawned threads. This property is deprecated This property is not needed when calling components from threads spawned by the Thread Manager. The Thread Manager is the recommended way to spawn threads in Java components. See Chapter 32, "Using the Thread Manager" for more information.
com.sybase.ejb. GCInterval	Specifies how often the ORB forces deallocation (Java garbage collection) of unused class references. Though this property is set on an individual ORB instance, it affects all ORB instances. The default is 30 seconds. The default is appropriate unless you have set an idle connection timeout of less than 30 seconds. In that case, you should specify a lower value for the garbage collection interval, since connections are only closed while performing garbage collection. In other words, the effective idle connection timeout ranges from the idle connection timeout setting to the smallest integral multiple of the garbage collection interval.
com.sybase.ejb. IdleConnectionTimeout	Specifies the time, in seconds, that a connection is allowed to sit idle. When the timeout expires, the ORB closes the connection. The default is 0, which specifies that connections can never timeout. The connection timeout does not affect the life of proxy instance references; the ORB may close and reopen connections transparently between proxy method calls. Specifying a finite timeout for your client applications can improve server performance. If many instances of the client run simultaneously, a finite client connection timeout limits the number of server connections that are devoted to idle clients. A finite timeout also allows rebalancing of server load in an application that uses a cluster of Jaguar servers.
com.sybase.ejb. SSLCallback Applicable only to Java application clients.	Required if you are using SSL and you wish to provide a callback class to set required SSL settings on an as-needed basis. Specify the name of a Java class that implements the CtsSecurity.SSLCallbackIntf interface. For example: com.acme.AcmeSSLCallback "Implementing an SSL callback" describes how to code a callback class.
com.sybase.ejb. pin Applicable only to Java application clients.	Always required when using SSL. Specifies the PKCS #11 token PIN. This is required for logging in to a PKCS #11 token for client authentication and for retrieving trust information. This property cannot be retrieved. If not set, set to `any` , or set incorrectly, the ORB invokes the getPin callback method.
com.sybase.ejb. certificateLabel Applicable only to Java application clients.	Required when using SSL mutual authentication. Specifies the client certificate to use if the connection requires mutual authentication. The label is a simple name that identifies an X.509 certificate/private key in a PKCS #11 token. If the property is not set and the connection requires mutual authentication, the ORB invokes the getCertificateLabel callback method, passing an array of available certificate names as an input parameter.
com.sybase.ejb. qop Applicable only to Java application clients.	Always required when using SSL. Specifies the name of a security characteristic to use. See "Choosing a security characteristic" for more information.
com.sybase.ejb. useEntrustID Applicable only to Java application clients.	Specifies whether to use the Entrust ID or the Sybase PKCS #11 token for authentication. This is a Boolean (true or false) property. If this property is set to false, Sybase PKCS #11 token properties are valid and Entrust-specific properties are ignored. If this property is set to true, Entrust-specific properties are valid and Sybase PKCS #11 token properties are ignored.
com.sybase.ejb. entrustUserProfile Applicable only to Java application clients.	Specifies the full path to the file containing an Entrust user profile. This property is optional when the Entrust single-login feature is available and required when this feature is not available. If not set, the ORB invokes the getCredentialAttribute callback method.
com.sybase.ejb. entrustPassword Applicable only to Java application clients.	Specifies the password for logging in to Entrust with the specified user profile. This property is optional when the Entrust single-login feature is available and required when this feature is not available. If the password is required but not set or set incorrectly, the ORB invokes the getPin callback method. This property cannot be retrieved.
com.sybase.ejb. entrustIniFile Applicable only to Java application clients.	Specifies the path name for the Entrust INI file that provides information on how to access Entrust. This is required when the useEntrustid property is set to true. If not set, the ORB invokes the getCredentialAttribute callback method.
com.sybase.ejb. userData Applicable only to Java application clients.	Specifies user data (String datatype). This is an optional property. Client code can set user data during NamingContext initialization and access it using SSLSessionInfo::getProperty method in the SSL callback implementation. This may be useful as a mechanism to store context information that is otherwise not available through the SSLSessionInfo interface.
com.sybase.ejb. WebProxyHost Applicable only to Java application clients.	Specifies the host name or IP address of a Web proxy server. Applies to Java applications only. Java applets running in a Web browser will use the proxy address specified by the browser's proxy configuration. In Java applications, there is no default for this property, and you must specify both the host name and port number properties. See "Using Web proxies" for more information.
com.sybase.ejb. WebProxyPort Applicable only to Java application clients.	Specifies the port number at which the Web proxy server accepts connections. Applies to Java applications only. Java applets running in a Web browser will use the proxy address specified by the browser's proxy configuration. In Java applications, there is no default for this property, and you must specify both the host name and port properties. See "Using Web proxies" for more information.
com.sybase.ejb. HttpExtraHeader Applicable only to Java application clients.	An optional setting to specify what extra information is appended to the header of each HTTP packet when connecting through a Web proxy. See "Properties that affect Web proxy use" for more information.

Choosing a security characteristic To use SSL, you must specify the name of an available security characteristic as the value for the com.sybase.ejb.qop property. The characteristic describes the CipherSuites the client uses when negotiating an SSL connection. When connecting, the client sends the list of CipherSuites that it uses to the server, and the server selects a CipherSuite from that list. The server chooses the first CipherSuite in the list that it can use. If the server cannot use any of the available CipherSuites, the connection fails.

The "Security Configuration" chapter in the Jaguar CTS System Administration Guide describes the security characteristics that are provided with Jaguar.

Set the qop property to sybpks_none to prevent any use of SSL on a connection.

Secure server addresses Client proxies will only connect to a server listener that uses an equivalent or greater level of security as requested in the com.sybase.ejb.qop setting. The URL specified with java.naming.provider.url cannot specify a server address that uses a higher level of security than specified by the qop property. For example, if your server uses the typical port configuration, you can specify port 9000 (no SSL) in the name service URL if the qop property specifies mutual authentication. However, you cannot specify port 9002 (mutual authentication) in the name service URL and set the qop property to request server-only authentication.

Resolving Bean home names

Call the Context.lookup method to resolve a Bean's home name to a proxy for the Bean's home interface. If the server or cluster where the Bean is installed has a name context configured, pass the server's name context as part of the Bean home name, in the format:

Server-name-context/Bean-home

Call javax.rmi.PortableRemoteObject.narrow to narrow the returned object to the Bean's home interface class. narrow requires as parameters the object to be narrowed and a java.lang.Class reference that specifies the interface type to returned. To obtain the java.lang.Class reference, use Home.class, where Home is the Bean's home interface type. Cast the object returned by the narrow method to the Bean's Java home interface.

The lookup method throws javax.naming.NamingException if the Bean home name cannot be resolved or the home interface proxy cannot be created. This can happen for any of the following reasons:

The server address specified with the Context.PROVIDER_URL property is incorrect or the server is not running.
Authentication with the specified credentials failed.
The Bean is incorrectly configured on the server. For example, a skeleton has not been generated, or the Bean's properties specify the wrong implementation class.

Check the server's log file if the cause of the error is not clear from the exception's detail message.

The call below instantiates a proxy for a Bean with Java home interface test.p1.Stateless1Home and Bean home name of test/p1/Stateless1:

import test.p1.*;
import javax.naming.*;
javax.rmi.PortableRemoteObject;

try {

  Object o = ctx.lookup("test/p1/Stateless1");
  Stateless1Home home = (Stateless1Home) 
    PortableRemoteObject.narrow(o, Stateless1Home.class);
} catch (NamingException ne) {
  System.out.println("Error: Naming exception: "
    + ne.getExplanation());
}