Show TOC

Procedure documentationAccessing Enterprise JavaBeans from Remote Clients Locate this document in the navigation structure

 

Remote Clients

A remote client is a client that can run on the same or a separate machine and a Java virtual machine (JVM) than the enterprise bean it accesses. A remote client can be a Web component, an application client, or another enterprise bean. The location of the enterprise bean is transparent to the remote client.

To access Enterprise JavaBeans deployed in an application you use the JNDI API. JNDI Registry Service is the standard way to associate names with objects and to find objects by their names. Remote clients use the JNDI to look up objects. To connect to JNDI you have to create a javax.naming.InitialContext object. In this way you access the root of the naming tree and then you look up the desired object.

You access beans from remote clients using the EJB lookup schemes.

EJB Lookup Scheme

The EJB lookup schemes are a new format of the lookup strings for nonstandard Java EE components. The EJB lookup schemes provide the needed abstraction between the client lookup strings and the real bindings in the naming tree. Thus, the EJB container has the freedom to bind its objects to different locations in the naming tree and, at the same time, you do not have to change the lookup strings, they remain compatible.

Note Note

The lookup string has a special format for home interfaces in EJB 2.x. You can still use the <jndi-name> specified in ejb-j2ee-engine.xml as a lookup string, or use the default one <app-name>/<bean-name>. This format, however, is deprecated in the current release of SAP NetWeaver.

End of the note.

Procedure

  1. You create the InitialContext object by specifying the JNDI properties. In addition to the standard properties you have to set the new property: props.put(Context.URL_PKG_PREFIXES, "com.sap.engine.services"), which is obligatory when you use the EJB lookup scheme.

    Syntax Syntax

    1. Properties props = new Properties();
      
      
      
      props.put(Context.INITIAL_CONTEXT_FACTORY,
      
         "com.sap.engine.services.jndi.InitialContextFactoryImpl");
      
      props.put(Context.PROVIDER_URL, "<host>:<port>");
      
      props.put(Context.SECURITY_PRINCIPAL, "<user>");
      
      props.put(Context.SECURITY_CREDENTIALS, "<pass>");  
      
      props.put(Context.URL_PKG_PREFIXES, "com.sap.engine.services");    
      
      InitialContext ctx = new InitialContext(props);
      
    End of the code.

    Note Note

    If your client is running on the same SAP NetWeaver Application Server Java, you do not need the Properties object while creating the InitialContext:

    End of the note.

    Syntax Syntax

    1. InitialContext ctx = new InitialContext ();
      
    End of the code.
  2. You look up the bean using the specific lookup string in the root context ctx.

    Syntax Syntax

    1. Object obj = ctx.lookup(<lookup-string>);
    End of the code.

    You have to replace the <lookup-string> with one of the formats listed below.

Extended Format

ejb:/key1=value1, key2=value2…, where the keys can be the following:

Allowed Keys Table

Key

Presence

Description

interfaceName

Mandatory

The fully-qualified class name of the desired bean interface.

appName

Optional

The name of the application, which contains the desired bean.

jarName

Optional

The name of the JAR, which contains the desired bean.

beanName

Optional

The name of the desired bean. (the value of either the <ejb-name> element in the ejb-jar.xml or the name attribute of the @Stateless or @Stateful annotation).

interfaceType

Optional

The type of the desired bean interface (either local, remote, home or local-home).

multipleResult

Optional

When you look up a bean you define one or more of the keys listed above in this table.

If you want to have all possible beans that match to the certain criteria, set the multipleResult key to true. The result of the lookup is a java.util.Collection of the client views.

If the value of this key is false, the first bean that matches the search criteria is returned by the EJB Container.

The default value is false.

multipleResultSkipError

Optional

To prevent the multiple lookup from failing in case of an application error thrown while creating any of the client views matching the search criteria, set the value of the multipleResultSkipError key to true.

If the value of this key is false and such an error occurs, the multiple lookup fails. This is the default value.

Note Note

You can use this key only if the multipleResult key is set to true.

End of the note.

This is the new lookup format, which brings the whole potential of the JNDI schemes.

Example Example

ejb:/appName=sap.com/TestApp, jarName=TestJar.jar, beanName=TestBean, interfaceName=test.RemoteInterface

ejb:/appName=sap.com/TestApp, beanName=TestBean, interfaceName=test.RemoteInterface

ejb:/appName=sap.com/TestApp, interfaceName=test.RemoteInterface

ejb:/interfaceName=test.RemoteInterface

ejb:/interfaceName=test.RemoteInterface, multipleResult=true

ejb:/appName=sap.com/TestApp, interfaceName=test.RemoteInterface, multipleResult=true, multipleResultSkipError=true

End of the example.

Note Note

If you want to look up EJB 2.x home interfaces with the EJB lookup scheme, you have to use only the Extended format by specifying the interfaceType as ”home” or ”local-home” value.

End of the note.

Note Note

These keys may be treated as search criteria parameters. For example, if you want to find a particular bean only by using the beanName as a search criterion, the container checks the name of the bean out of all deployed applications, which contain enterprise beans. If there are several enterprise beans with the same name, the container may return another bean with the same name that was found in another application or in another EJB module JAR file of the same application. If you search for the same bean using its interface name, the application name, the JAR name, the bean name, and the interface type, there is no conflict because there cannot be two beans with all these keys matching.

Therefore, we recommend using as many keys as possible in your lookup string. More keys mean faster resolving of the EJB and fewer conflicts (a conflict occurs when more than one EJB passes the criteria parameters). If you use the multipleResult and the multipleResultSkipError keys, there will be no conflicts at all, because you collect all beans that match the defined criteria.

End of the note.

Note Note

When you use the multipleResult and the multipleResultSkipError keys without specifying the interface type, by default the collection that is returned contains only beans of local type. You cannot have local and remote client views in one and the same collection. If you want to receive a collection that contains remote client views, you have to specify interfaceType=remote.

End of the note.
Compatibility Format

ejb:/<app-name>/REMOTE or LOCAL/<bean-name>/<interface-name>

This format provides minimal changes to the previous lookup string, which is deprecated in the current version of SAP NetWeaver. Although it is still possible to look up beans by using the <app-name>/<REMOTE or LOCAL>/<bean-name>/<interface-name> string, the EJB lookup scheme is recommended.

In the new format you only have to add the ejb:/ prefix.

Example Example

ejb:/sap.com/TestApp/REMOTE/TestBean/test.RemoteInterface

End of the example.
Simplified Compatibility Format

ejb:/<app-name>/<bean-name>/<interface-name>

This format simplifies the Compatibility format by omitting the access type.

Example Example

ejb:/sap.com/TestApp/TestBean/test.RemoteInterface

End of the example.