|
|
|
|
|
|
Using the SPI Implementations for JNDI
This topic includes the following sections:
Overview of JNDI in WebLogic Enterprise
In the enterprise, naming and directory services provide the means for your application to locate objects on the network. These services are key to building distributed applications. A naming service provides a mechanism to name objects and retrieve objects by name. A directory service is a naming service that also allows for attributes to be associated with each object, and provides a way to retrieve an object by its attributes instead of its name.
The Java Naming and Directory Interface (JNDI) is an API that provides directory and naming services to Java applications. JNDI is an integral component of the Sun Microsystems Java 2 Platform Enterprise Edition (J2EE) technology.
JNDI is defined to be independent of any specific naming or directory service implementation. A variety of services, new and existing ones, can be accessed in a common way. The JNDI Service Provider Interface (SPI) provides a means by which different naming and directory providers can develop and integrate their implementations so that the corresponding services are accessible from applications that use JNDI.
The JNDI support provided in the WebLogic Enterprise software leverages from the standard Sun Microsystems, Inc., JNDI API classes. This support allows any service-provider implementation to be plugged into the JNDI framework using the standard SPI conventions. The support allows Java applications in WebLogic Enterprise to access external directory services such as LDAP in a standardized fashion, by plugging in the appropriate service-provider.
In addition, BEA provides two WebLogic Enterprise specific SPI implementations to enable access to naming features in the WebLogic Enterprise system. The WebLogic Enterprise SPI provides the following features:
The local objects include deployment information and resources provided to applications within the containing environment of the server. The naming and access conventions for these local objects conforms to the J2EE specifications. There is also a specially named subcontext, wle.factories, in this namespace, which provides a mapping to the WebLogic Enterprise NameManager/FactoryFinder for binding to and looking up global object references.
Note: WebLogic Enterprise CORBA Java clients continue to use the existing WebLogic Enterprise CosLifeCycle::FactoryFinder and CORBA naming services to access named factory objects. Both the CORBA and JNDI naming implementations share the same underlying namespace infrastructure and are functionally equivalent. Both programming styles are supported by a common naming infrastructure.
The JNDI API and SPI
The WebLogic Enterprise SPI implementation for JNDI is based on the Sun Microsystems, Inc. JNDI 1.2 and SPI specifications. The basic JNDI framework implementation is based on version 1.2 of the Sun Microsystems Inc. standard extension classes.
The JNDI API is contained in two packages: javax.naming for the naming operations and javax.naming.directory for directory operations. The JNDI SPI is contained in the package javax.naming.spi.
The Naming Interface - javax.naming
The javax.naming.Context interface is the core interface that specifies a naming context. It defines basic operations such as adding a name-to-object binding, looking up the object bound to a specified name, listing the bindings, removing a name-to-object binding, and creating and destroying subcontexts of the same type.
Context.lookup() is the most commonly used operation. The context implementation can return an object of whatever class is required by the Java application.
The application is not exposed to any naming service implementation. In fact, a new type of naming service can be introduced without requiring the application to be modified or even disrupted if it is running.
The Directory Interface - javax.naming.directory
The WebLogic Enterprise SPI supports the external interfaces in the javax.naming and javax.naming.spi packages. There is no WebLogic Enterprise SPI support for the directory interfaces in javax.naming.directory. However, third-party directory provider services can be plugged-in, as shown in "Unified Naming and Directory Services" on page 1-7.
The Service Provider Interface - javax.naming.spi
The JNDI SPI allows different naming and directory service providers to develop and integrate their implementations so that the corresponding services are accessible from applications that use JNDI. Also, JNDI allows specification of names that span multiple namespaces. If one service provider implementation needs to interact with another in order to complete an operation, the SPI provides methods that allow different provider implementations to cooperate to complete client JNDI operations.
Additional WebLogic Enterprise SPI Implementations
In addition to the standard Sun Microsystems Inc. interfaces for the JNDI API, WebLogic Enterprise provides its own implementation that uses the standard JNDI SPI interfaces. The two InitialContextFactory class implementations that are provided in WebLogic Enterprise are:
com.beasys.jndi.WLEInitialContextFactory
weblogic.jndi.WLInitialContextFactory
In your application code, you do not instantiate either of these classes directly. Instead you use the standard javax.naming.InitialContext class and set the appropriate Hashtable keys, as documented in the section "Using the Remote Naming Service for Client Connections and SSL Support" on page 1-8. All interaction is done through the javax.naming.Context interface, as described in the JNDI Javadoc.
As a convenience to application programmers, WebLogic Enterprise also provides a com.beasys.jndi.WLEContext interface. This interface extends javax.naming.Context. There are some JNDI constants defined that you can use with the JNDI environment. These constants are used for authentication on the InitialContext, as explained in the section "WebLogic Enterprise Keys Required for BEA TUXEDO Style Authentication" on page 1-11.
WebLogic Enterprise JNDI Packaging
The server classes for WebLogic Enterprise JNDI are set automatically when the JavaServer is booted.
The client classes for WebLogic Enterprise JNDI are in:
<drive>:\wledir\java\jdk\m3envobj.jar
<drive>:\wledir\java\jdk\wleclient.jar
<drive>:\wledir\java\jdk\wlej2eecl.jar
<drive>:\wledir\java\jdk\weblogicaux.jar
Verify that your CLASSPATH is set correctly. If necessary, set your CLASSPATH to include the following JAR files:
Client on Windows NT:
set JDIR=%TUXDIR%\java\jdk
set CLASSPATH=.;%JDIR%\m3envobj.jar;%JDIR%\wleclient.jar;
%JDIR%\wlej2eecl.jar;%JDIR%\weblogicaux.jar
set JDIR=
Client on UNIX:
export JDIR=${TUXDIR}/java/jdkexport CLASSPATH=.:${JDIR}/m3envobj.jar:${JDIR}/wleclient.jar:
${JDIR}/wlej2eecl.jar:${JDIR}/weblogicaux.jar export JDIR=
Location of the WebLogic Enterprise JNDI Javadoc
On the following Javadoc start page under the installed WebLogic Enterprise directory, there is a hyperlink to the Sun Microsystems, Inc. JNDI API documentation:
<drive>:\wledir\docs\index.html
Unified Naming and Directory Services
The WebLogic Enterprise JNDI SPI implements the standard unified interface to multiple naming and directory services. The implementation allows a WebLogic Enterprise J2EE Java application to connect to any naming and directory service, such as LDAP, NDS, or NIS, if the appropriate third-party JNDI service provider is used.
WebLogic Enterprise provides this support by utilizing and redistributing the standard JNDI extension classes, provided by Sun Microsystems with JNDI version 1.1.2. BEA and any third-party vendors conforming to the JNDI Service Provide Interface (SPI) may provide access to vendor-specific naming and directory services.
The following code fragment uses JNDI to access a Sun Microsystems Inc. LDAP service provider.
Hashtable env = new Hashtable();
/*
* Specify the initial context implementation to use.
* The service provider supplies the factory class.
*/
env.put(Context.INITIAL_CONTEXT_FACTORY,
"com.sun.jndi.ldap.LdapCtxFactory");
/* Specify host and port of LDAP server */
env.put(Context.PROVIDER_URL, "ldap://ldap.bigfoot.com:389");
/* Connect to the server and establish the initial context */
DirContext ctx = new InitialDirContext(env);
/* Access the LDAP directory using the context */
.
.
.
Using the Remote Naming Service for Client Connections and SSL Support
The WebLogic Enterprise remote naming SPI provides an InitialContext implementation that allows remote Java clients to connect into a WebLogic Enterprise system. The client can specify standard JNDI context environment properties to identify the WebLogic Enterprise system and other related connection parameters for logging into a WebLogic Enterprise system.
To participate in a session with a WebLogic Enterprise server application, a Java client must be able to get an object reference for a remote object and invoke operations on the object. To accomplish this, the client application code must perform the following:
Step 1: Set Up JNDI Environment Properties for the Initial Context
All Java remote client applications must first create environment properties. The InitialContext factory uses various properties to customize the InitialContext for a specific environment. You can set these properties by using a Hashtable. These properties, which are name-to-value pairs, determine how the WLEInitialContextFactory creates the WLEContext:
WLEContext.INITIAL_CONTEXT_FACTORY Property
Set this property to the WebLogic Enterprise initial context factory, com.beasys.jndi.WLEInitialContextFactory, to access the WebLogic Enterprise domain and remote naming services.
The class com.beasys.jndi.WLEInitialContextFactory provides the implementation for delegating JNDI methods to the WebLogic Enterprise JNDI implementation. The class com.beasys.jndi.WLEInitialContextFactory provides an entry point for a client into the WebLogic Enterprise domain namespace.
For example:
Hashtable env = new Hashtable();
/*
* Specify the initial context implementation to use.
* The service provider supplies the factory class.
*/
env.put(WLEContext.INITIAL_CONTEXT_FACTORY,
"com.beasys.jndi.WLEInitialContextFactory");
.
.
.
WLEContext.PROVIDER_URL Property
Set the URL of the service provider with the property name java.naming.provider.url. This property value should specify an IIOP Listener/Handler for the desired WebLogic Enterprise target domain.
For example:
.
.
.
env.put(WLEContext.PROVIDER_URL,
"corbaloc://myhost:1000");
.
.
.
The URL is interpreted directly by the Tobj_Bootstrap. The same syntax rules apply to indicate the search order or equivalence of handler addresses. You can also use the URL to specify an SSL connection using the corbalocs: URL scheme. The acceptable syntaxes for the URL are described in the Javadoc file for Tobj_Bootstrap.
The host and port combination specified in the URL must match the ISL parameter in the WebLogic Enterprise application's UBBCONFIG file. The format of the host and port combination, as well as the capitalization, must match. If the addresses do not match, the communication with the WebLogic Enterprise domain fails.
A WebLogic Enterprise server that acts as a client should not specify this Context.PROVIDER_URL property because the server is already connected to the application in which it is booted. If this property is specified on the server it must be set to an empty string or null values.
WLEContext.SECURITY_AUTHENTICATION Property
The WebLogic Enterprise system supports different levels of authentication. The SECURITY_AUTHENTICATION value determines whether certificate-based SSL authentication is attempted or BEA TUXEDO style authentication is used.
Valid values for this property key are "none", "simple", or "strong", as recommended by the Sun Microsystems Inc. JNDI specification.
For example:
.
.
.
env.put(WLEContext.SECURITY_AUTHENTICATION,
"strong");
.
.
.
If you explicitly specify WLEContext.SECURITY_AUTHENTICATION="none", this setting causes WebLogic Enterprise client software to bypass all security setup on the initial connection. If you do not include the WLEContext.SECURITY_AUTHENTICATION property at all, the default behavior is for the client code to check the current security level on the target domain and check for any required authentication parameters. You can explicitly set WLEContext.SECURITY_AUTHENTICATION="none" if your intention is to bypass the security level checking and authentication setup on the client. This might be done, for example, in a case where you know there is no authentication required on the target domain and you want to optimize performance. However, if authentication is required on the target domain and the WLEContext.SECURITY_AUTHENTICATION="none", a security exception might be generated until the client later attempts to access an object on the server.
If you specify the "strong" value, certificate-based authentication is attempted using SSL protocols. This is implemented using the CORBA PrincipalAuthenticator.authenticate method with an AuthenticationMethod value of CertificateBased.
If the SECURITY_AUTHENTICATION value is "simple" or is not specified, BEA TUXEDO style authentication is used. See the next section for information about the WebLogic Enterprise specific keys used to support BEA TUXEDO style authentication.
WebLogic Enterprise Keys Required for BEA TUXEDO Style Authentication
The WebLogic Enterprise specific property keys in this section provide the additional parameters needed for BEA TUXEDO style authentication. For example:
Hashtable env = new Hashtable();
env.put(WLEContext.PROVIDER_URL, "corbaloc://myhost:1000");
env.put(WLEContext.INITIAL_CONTEXT_FACTORY,
"com.beasys.jndi.WLEInitialContextFactory");
// Add Authentication parameters
env.put(WLEContext.SECURITY_AUTHENTICATION, "simple");
env.put(WLEContext.SYSTEM_PASSWORD, "RMI");
env.put(WLEContext.SECURITY_PRINCIPAL, "user");
env.put(WLEContext.CLIENT_NAME, "client");
env.put(WLEContext.SECURITY_CREDENTIALS, "userpw");
Context ctx = new InitialContext(env);
The property keys are as follows:
WLEContext.SECURITY_PRINCIPAL
Specifies the identity of the principal for authenticating the caller to the WebLogic Enterprise domain.
WLEContext.SECURITY_CREDENTIALS
Specifies the credentials of the principal for authenticating the caller to the WebLogic Enterprise domain. For SSL certificate-based authentication, enabled via SECURITY_AUTHENTICATION="strong", it specifies a pass phrase for accessing the private key and client certificate. For BEA TUXEDO style authentication, it identifies a String user password or an arbitrary Object user_data for the BEA TUXEDO AUTHSVC.
WLEContext.CLIENT_NAME
Specifies the client name for BEA TUXEDO style authentication.
WLEContext.SYSTEM_PASSWORD
Specifies the system password for BEA TUXEDO style authentication.
WLEContext.CODEBASE
Specifies the URL for network class loading.
Step 2: Establish an InitialContext with the WebLogic Enterprise Domain
To access a service provider using JNDI, you create an InitialContext and identify a context factory, which creates the context for a certain provider.
To access a WebLogic Enterprise domain, use the WebLogic Enterprise context factory, "com.beasys.jndi.WLEInitialContextFactory" as an argument. After the context is created, it provides client access to factory names in the WebLogic Enterprise domain using WebLogic Enterprise as the name service provider.
To create a WebLogic Enterprise remote domain context from a remote Java client, you must minimally specify this factory as the initial context factory, and specify the JNDI environment as properties passed to the constructor of the InitialContext.
The following example shows how to setup the initial environment properties and create the initial context:
Hashtable env = new Hashtable();
/*
* Specify the initial context implementation to use.
* This example will access the remote WLE domain context.
*/
env.put(WLEContext.INITIAL_CONTEXT_FACTORY,
"com.beasys.jndi.WLEInitialContextFactory");
/*
* Specify host and port of ISL/ISH gateway - this is only
* specified for remote clients.
*/
env.put(WLEContext.PROVIDER_URL, "corbaloc://myhost:1000");
/* Connect to the domain and establish the initial context */
Context ctx = new InitialContext(env);
.
.
.
Step 3: Use the Context to Look Up a Named Server Object
The client application must obtain an initial object that provides services for the application. This object is named by the server and is bound to the domain namespace.
For EJB applications this object is usually an EJB Home object and provides references to other remote objects in the application. The lookup method on the Context object is used to obtain this named object. The argument passed to the lookup method is a string that contains the name of the desired server object.
The following code fragment shows how to get access to a named server object:
CartHome cartHome = (CartHome) ctx.lookup("johns-carts");
Step 4: Use the Named Server Object to Get a Reference for the Desired Remote Object, and Invoke Operations on the Remote Object
CORBA client applications get object references to other CORBA remote objects from factories.
EJB client applications get object references to EJB remote objects from EJB Homes.
RMI client applications can also get object references to other RMI remote objects from an initial named object.
All of these initial named remote objects are known to the WebLogic Enterprise system generically as a "factory". A factory is any server object that can return a reference to another remote object and is bound into the WebLogic Enterprise domain namespace.
The client application invokes a method on a factory to obtain a reference to a remote object of a specific class. The client applications then invoke methods on the remote object, passing any arguments that it requires.
The following code fragment obtains the desired remote object, and then invokes a method on the remote object:
Cart cart = cartHome.create("John", "7506");cart.addItem(66);
Step 5: Complete the Session
After a client is finished working with a context, the client should close the context in order to release resources for the session and implicitly logoff. For example:
try {
ctx.close();} catch (Exception e) {
// a failure occurred
}
Providing Remote Client Access to the UserTransaction Interface
The Java Transaction API (JTA) defines the UserTransaction interface that is used by applications to start and commit or abort transactions. An application client gets a UserTransaction object through a JNDI lookup by using the name "java:comp/UserTransaction".
For example:
Context initCtx = new InitialContext(env);
UserTransaction utx = (UserTransaction)initCtx.lookup(
"java:comp/UserTransaction");
utx.begin();
.
.
.
utx.commit();
Using the Application Naming Service to Access Local Objects
The WebLogic Enterprise application naming SPI provides an application naming service for both:
By default the root context and any application-created subcontexts are mapped into a local namestore on the server. This local namestore allows Java server applications to access local objects using standard JNDI conventions. This application naming service supports a hierarchical namespace and the creation of subcontexts.
Note: There is also a predefined subcontext named wle.factories that is mapped to the FactoryFinder/NameManager services in the WebLogic Enterprise domain. This global context is discussed in the section "Accessing the Factories Subcontext" on page 1-17.
If an application running on a WebLogic Enterprise server, such as an EJB or RMI object, needs access to local objects in the current JavaServer, it can create a JNDI Context. Because the object making the call is already logically in the environment of the server, there is no need to specify environment properties to access the default application namespace.
To create a context from within a server-side object, all you need to do is construct a new InitialContext. For example:
Context ctx = new InitialContext();
You do not need to specify a factory or a provider URL. By default, the context will be created as a WebLogic Enterprise application context and will connect to the default naming service.
Using the Application Naming Service to Access Global Objects
This section describes the following topics about using the WebLogic Enterprise application naming service to access global objects:
The WebLogic Enterprise application naming SPI provides an application naming service for both:
The WebLogic Enterprise application naming SPI provides a specially identified named subcontext, wle.factories, that provides naming services for server objects identified throughout a WebLogic Enterprise domain.
The WebLogic Enterprise application naming SPI also provides support for named objects imported from other domains via the FactoryFinder cross-domain feature. This subcontext uses the WebLogic Enterprise FactoryFinder and NameManager services to manage its bindings. To increase availability and reliability, you can create multiple FactoryFinders and NameManagers in the event one FactoryFinder or NameManager fails.
The wle.factories subcontext is mapped directly into the namespace managed by the FactoryFinder and NameManager. This subcontext is a flat namespace:
The underlying namespace is also used by CORBA clients, and is extended via JNDI to support EJB and RMI clients. The CORBA client uses the CORBA FactoryFinder to access remote CORBA factory objects. An EJB or RMI client uses JNDI to access registered remote objects. An application may choose to implement naming conventions if it is desirable to prevent name collisions or to partition the namespace using its own syntax conventions.
Accessing the Factories Subcontext
Remote Java clients access the WebLogic Enterprise domain namespace using the procedures described in the section "Using the Remote Naming Service for Client Connections and SSL Support" on page 1-8. Remote clients may perform lookup methods on the remote context, but cannot perform binding methods on the namespace.
Server applications access the WebLogic Enterprise domain namespace by using the wle.factories subcontext under the default InitialContext on the server. The server initializes the wle.factories subcontext to the domain namespace in which it is booted. Server applications have full access to the subcontext and may bind objects into it. In the following example, a server object connects to the factories subcontext:
/* Get a default context and retrieve the factories subcontext */
Context rootCtx = new InitialContext();
Context factoryCtx = (Context) rootCtx.lookup("wle.factories");
Binding Objects into the Factories Subcontext
Server applications can create named objects in the domain namespace, which then allows client applications to easily locate the objects managed by the server. These objects are usually factories so that client applications can obtain references to other remote objects in the application from the initial named objects. The binding of named remote objects into the domain namespace is typically the final step of the server application initialization process.
Note: For EJB applications the named factories are called Home objects. The EJB bean provider code does not need to explicitly bind the Home into the Context. The binding operation is done automatically by the EJB Container during server deployment, based on the bean-name in the deployment descriptor.
To use an object in the WebLogic Enterprise domain namespace, WebLogic Enterprise requires that objects returned by lookup must be remotely accessed from the client in a form that preserves its functionality. Thus it must be known to WebLogic Enterprise as a remote object. What is actually stored in the underlying WebLogic Enterprise NameManager is a mapping from the registered name to the WebLogic Enterprise remote object reference.
The sample program in Listing 1-1 shows how to bind an RMI remote object into the WebLogic Enterprise factories context during server startup. This makes the object available to clients who wish to lookup the object by name. The sample also shows how to remove the object from the JNDI context during server shutdown.
Listing 1-1 Sample bind.java Program
import javax.naming.*; // Use standard JNDI 1.2 interfaces
public class ServerImpl extends com.beasys.Tobj.Server {
static final String factoryName = "SimpFactory";
SimpFactoryImpl factory;
Context factoryCtx;// The initialize method is called during JavaServer startup
public boolean initialize(String[] argv) {
try {
// Get the "wle.factories" subcontext from the default InitialContext
factoryCtx = (Context) new InitialContext().lookup("wle.factories");// Create the factory and make it available to clients via JNDI
factoryCtx.bind(factoryName, new SimpFactoryImpl());
} catch (Exception e) {
e.printStackTrace();
return false;
}
return true;
}
// The release method is called during JavaServer shutdown
public void release() {
try {
// Remove the binding from the "wle.factories" subcontext
factoryCtx.unbind(factoryName);
} catch (Exception e) {
e.printStackTrace();
}
}
}
Unbinding Objects from the Factories Subcontext
Once a server application receives a request to shut down, the server application can no longer receive requests from clients. During server shutdown it should unbind each of the objects previously bound into the namespace.
// Remove this factory reference from the WLE namespace
factoryCtx.unbind(tellerFname);
J2EE Requirements
The enterprise bean's Home interface defines the methods for the client to create, remove, and find EJB objects of the same type. That is, they are implemented by the same enterprise bean. The Home interface is specified by the Bean Provider. The Container creates a class that implements the Home interface. The Home interface extends the javax.ejb.EJBHome interface.
The container is responsible for making the Home interfaces of the deployed enterprise beans available to the client through JNDI. A client can locate an enterprise Bean Home interface through the WebLogic Enterprise JNDI remote namespace provider. When an EJB-JAR module is deployed into a WebLogic Enterprise JavaServer, the runtime system will automatically read the deployment descriptor and bind the remote Home into the JNDI factories subcontext.
Cross-Domain Support
For multidomain configurations the FactoryFinder supports access to named object references in another domain. You or your administrator define domain parameters in the application's DMCONFIG configuration file. The WebLogic Enterprise application naming service is built on top of the FactoryFinder. When the FactoryFinder is configured for multidomain naming support, cross-domain names are available through the WebLogic Enterprise application namespace.
The domain of an object reference is unknown to the application, and invocations on an object reference for a remote domain are transparent to the application. This transparency allows administrators to configure services in individual domains and to spread resources across multiple domains. Administrators are required to identify any named remote objects that can be used in the current (local) domain, but that are resident in a different (remote) domain. You identify these objects in a FactoryFinder domain configuration file named factory_finder.ini. This is an ASCII file that can be created and updated using a text editor.
For related information, see Configuring Multiple Domains (WebLogic Enterprise System) in the WebLogic Enterprise online documentation.
The J2EE Naming Context
This section describes the following topics about the J2EE naming context:
The Sun Microsystems Inc. J2EE specification at http://java.sun.com/j2ee/ identifies specific JNDI requirements for an enterprise component to access named objects and external resources in a uniform manner. These requirements include:
An EJB reference is a special entry in the application component's environment.
A resource factory reference is a special entry in the application component's environment.
Accessing Environment Entries
An EJB component instance locates the environment naming context using the JNDI interfaces. An instance creates a javax.naming.InitialContext object by using the constructor with no arguments, and looks up the naming environment via the InitialContext under the name java:comp/env.
The EJB's environment entries are stored directly in the environment naming context, or in any of its direct or indirect subcontexts. The value of an environment entry is of the Java type declared by the Bean Provider in the deployment descriptor. The environment entries are declared using the <env-entry> elements in the deployment descriptor.
The following code fragment shows how an EJB accesses its environment entries:
public void setTaxInfo(int numberOfExemptions, ...)
throws InvalidNumberOfExemptionsException {
.
.
.
// Obtain the application component's environment naming context.
Context initCtx = new InitialContext();
Context myEnv = (Context)initCtx.lookup("java:comp/env");
// Obtain the maximum number of tax exemptions
// configured by the Deployer.
Integer max = (Integer)myEnv.lookup("maxExemptions");
// Obtain the minimum number of tax exemptions
// configured by the Deployer.
Integer min = (Integer)myEnv.lookup("minExemptions");
// Use the environment entries to customize business logic.
if (numberOfExeptions > max.intValue() ||
numberOfExemptions < min.intValue())
throw new InvalidNumberOfExemptionsException();
// Get some more environment entries. These environment
// entries are stored in subcontexts.
String val1 = (String)myEnv.lookup("foo/name1");
Boolean val2 = (Boolean)myEnv.lookup("foo/bar/name2");
// The application component can also lookup using full pathnames.
Integer val3 = (Integer)
initCtx.lookup("java:comp/env/name3");
Integer val4 = (Integer)
initCtx.lookup("java:comp/env/foo/name4");
.
.
.
}
Using EJB References
This section describes the programming and deployment descriptor interfaces that allow the Bean Provider to refer to the Homes of enterprise beans using logical names called EJB references. The EJB references are special entries in the EJB's environment. The Deployer binds the EJB references to the enterprise bean's Home interfaces in the WebLogic Enterprise operational environment.
The deployment descriptor also allows the Application Assembler to link an EJB reference declared in one application component to an enterprise bean contained in an EJB-JAR file in the same J2EE application. The link is an instruction to the tools used by the Deployer that the EJB reference should be bound to the home of the specified target enterprise bean.
The following example shows how an application component uses an EJB reference to locate the Home interface of an enterprise bean:
public void changePhoneNumber(...) {
.
.
.
// Obtain the default initial JNDI context.
Context initCtx = new InitialContext();// Look up the home interface of the EmployeeRecord
// enterprise bean in the environment.
Object result = initCtx.lookup(
"java:comp/env/ejb/EmplRecord");
// Convert the result to the proper type.
EmployeeRecordHome emplRecordHome = (EmployeeRecordHome)
javax.rmi.PortableRemoteObject.narrow(result,
EmployeeRecordHome.class");
.
.
.
}
In the previous example, the Bean Provider assigned the environment entry ejb/EmplRecord as the EJB reference name to refer to the Home of an enterprise bean. The Bean Provider must declare all the EJB references using the <ejb-ref> elements of the deployment descriptor.
Obtaining Resource Factory References
A resource is an object that encapsulates access to a resource manager. A resource factory is an object that is used to create resources. For example, an object that implements the java.sql.Connection interface is a resource that provides access to a database management system, and an object that implements the javax.sql.DataSource interface is a resource factory.
This section describes the application component programming and deployment descriptor interfaces that allow the application component code to refer to resource factories using logical names called resource factory references. The resource factory references are special entries in the EJB's environment. The Deployer binds the resource factory references to the actual resource factories in the WebLogic Enterprise operational environment.
The following code fragment illustrates obtaining a resource:
public void changePhoneNumber(...) {
.
.
.// obtain the initial JNDI context
Context initCtx = new InitialContext();
// perform JNDI lookup to obtain resource factory
javax.sql.DataSource ds = (javax.sql.DataSource)
initCtx.lookup("java:comp/env/jdbc/EmployeeAppDB");
// Invoke factory to obtain a resource.
java.sql.Connection con = ds.getConnection();
.
.
.
}
The Bean Provider must declare all the resource factory references in the deployment descriptor using the <resource-ref> elements.
Obtaining a UserTransaction Object
Many J2EE application component types are allowed to use the JTA UserTransaction interface to start, commit, and abort transactions. Such application components can find an appropriate object that implements the UserTransaction interface by looking up the JNDI name java:comp/UserTransaction.
The container is only required to provide java:comp/UserTransaction for those components that can make valid use of it. Any such UserTransaction object is only valid within the component instance that performed the lookup. Only some application component types are required to have access to a UserTransaction object. For details, refer to the Sun Microsystems Inc. EJB 1.1 specification.
Note: For your convenience, a PDF copy of the EJB 1.1 specification is included with the WebLogic Enterprise online documentation. To access the HTML page that includes a copy of the EJB 1.1 specification, click the PDF Files button at the top of a WebLogic Enterprise online documentation HTML page.
The following example illustrates how an application component acquires and uses a UserTransaction object:
public void updateData(...) {
.
.
.// Obtain the default initial JNDI context.
Context initCtx = new InitialContext();
// Look up the UserTransaction object.
UserTransaction tx = (UserTransaction)initCtx.lookup(
"java:comp/UserTransaction");
// Start a transaction.
tx.begin();
.
.
.
// Perform transactional operations on data.
.
.
.
// Commit the transaction.
tx.commit();
.
.
.
}
|
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|