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 8-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.
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.
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
|
java.naming.provider. url |
Specifies the URL to connect to the EAServer name server. Set the value to a URL with the following format:
where:
If you do not set this property, the default is |
java.naming.security. principal |
Specifies the user name for the EAServer session. Required if user name/password authentication is enabled for your server.
|
java.naming.security. credentials |
Specifies the password for the EAServer session. Required if user name/password authentication is enabled for your server. |
com.sybase.ejb. ConnectionTimeout |
For applications that run in a cluster, sets a time limit to receive a server response before the connection fails over to try another server in the cluster. Setting this property ensures that failover happens without an unreasonable delay. Specify the timeout period in seconds. The default of 0 indicates no time limit. |
com.sybase.ejb. forceSSL |
If set to true when using a a reverse proxy server, forces use of SSL for the connection to the reverse proxy. Set this property to true if the connection to the reverse proxy must use SSL (HTTPS) tunnelling, but the connection from the proxy to the server does not use SSL tunnelling. For more information, see Chapter 12, “Deploying Applications Around Proxies and Firewalls,” in the EAServer Security Administration and Programming Guide. |
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. http |
Specify whether proxies should use HTTP
tunnelling without trying to use plain IIOP first. The default is |
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.
|
com.sybase.ejb. HttpUsePost |
When using HTTP tunnelling, specifies the HTTP request type used. A value of true indicates that POST requests are to be used. A value of false (the default) specifies that GET requests are to be used. Some Web browsers cannot handle the long URLs generated when using HTTP tunnelling with GET requests. Setting this property to true can work around the issue. |
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 servers. |
com.sybase.ejb. isApplet Applicable only to Java applets. |
Specifies whether the client application
is a Java applet. The default is |
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
|
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 Chapter 12, “Deploying Applications Around Proxies and Firewalls,” in the EAServer Security Administration and Programming Guide for more information. |
com.sybase.ejb. ProxyPort |
Specifies the port number of a reverse proxy server. See Chapter 12, “Deploying Applications Around Proxies and Firewalls,” in the EAServer Security Administration and Programming Guide for more information. |
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 Chapter 5, “Using SSL in Java Clients,” in the EAServer Security Administration and Programming Guide 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 |
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. useJSSE |
Use the Java Secure Sockets Extension (JSSE) classes for secure HTTP tunnelled (HTTPS protocol) connections. JSSE provides an alternative to the built-in SSL implementations when secure connections are needed from an applet running in a Web browser. Additional configuration may be required to use this option. See Chapter 5, “Using SSL in Java Clients,” in the EAServer Security Administration and Programming Guide for more information. |
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 Chapter 12, “Deploying Applications Around Proxies and Firewalls,” in the EAServer Security Administration and Programming Guide 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 Chapter 12, “Deploying Applications Around Proxies and Firewalls,” in the EAServer Security Administration and Programming Guide 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 Chapter 12, “Deploying Applications Around Proxies and Firewalls,” in the EAServer Security Administration and Programming Guide 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.
“Configuring security profiles” in the EAServer Security Administration and Programming Guide describes the security characteristics that are provided with EAServer.
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.
The client runtime writes errors to the console by default. In Java applications, you can modify this behavior by creating a logging profile and specifying the profile name in the Java system properties. For more information, see “Using log profiles in Java client applications” in the EAServer System Administration Guide.
EJB clients that run as applets can set the APPLET parameter for the javax.naming.InitialContext instance used to connect to EAServer. For example:
java.util.Hashtable p = new java.util.Hashtable(); p.put(Context.APPLET, this); // Sybase implementation of InitialContextFactory p.put(Context.INITIAL_CONTEXT_FACTORY, "com.sybase.ejb.InitialContextFactory"); // URL for the Server's IIOP port. Host defaults to // the applet download host. p.put(Context.PROVIDER_URL, "iiop://:9000"); // Username "Guest", password is "GuestPassword" p.put(Context.SECURITY_PRINCIPAL, "Guest"); p.put(Context.SECURITY_CREDENTIALS, "GuestPassword"); // Now create an InitialContext that uses the // properties. InitialContext ic = new InitialContext(p);
Setting the APPLET parameter activates the following convenient features:
The host name can be omitted in the initial context URL that is specified as the PROVIDER_URL context parameter. The default host is the applet download host.
You can set the com.sybase.ejb.autoProxy property and it will work as documented in Chapter 12, “Deploying Applications Around Proxies and Firewalls,” in the EAServer Security Administration and Programming Guide.
