Oracle Application Server Containers for J2EE Services Guide 10g (9.0.4) Part Number B10326-01 |
|
This chapter describes Oracle Application Server Containers for J2EE (OC4J) support for allowing EJBs to invoke one another across different containers using the standard Remote Method Invocation (RMI)/Internet Inter-Orb Protocol (IIOP) protocol.
This chapter covers the following topics:
Java Remote Method Invocation (RMI) enables you to create distributed Java-based to Java-based applications, in which the methods of remote Java objects can be invoked from other Java virtual machines (JVMs), possibly on different hosts.
Version 2.0 of the EJB specification adds features that make it easy for EJB-based applications to invoke one another across different containers. You can make your existing EJB interoperable without changing a line of code: simply edit the bean's properties and redeploy. "Switching to Interoperable Transport" discusses redeployment details.
EJB interoperability consists of the following:
OC4J furnishes the first three of these features.
By default, OC4J EJBs use RMI/Oracle Remote Method Invocation (ORMI), a proprietary protocol, to communicate as described in Chapter 5, "Oracle Remote Method Invocation".
In OC4J, you can easily convert an EJB to use RMI/IIOP, making it possible for EJBs to invoke one another across different EJB containers. This chapter describes configuring and using RMI/IIOP.
OC4J supports the CORBA CosNaming service. OC4J can publish EJBHome
object references in a CosNaming service and provides a JNDI CosNaming implementation that allows applications to look up JNDI names using CORBA. You can write your applications using either the JNDI or CosNaming APIs.
OC4J supports Common Secure Interoperability Version 2 (CSIv2), which specifies different conformance levels; OC4J complies with the EJB specification, which requires conformance level 0.
The EJB2.0 specification stipulates an optional transactional interoperability feature. Conforming implementations must choose one of the following:
The current release of OC4J is transactionally noninteroperable, so, when a transaction spans EJB containers, OC4J raises a specified exception.
In order to access EJBs, you must do the following on the client-side:
oc4j_client.zip
file from http://otn.oracle.com/software/products/ias/devuse.html
d:\oc4jclient
)
d:\oc4jclient\oc4jclient.jar
to your CLASSPATH
The oc4j_client.zip file contains all the JAR files required by the client (including oc4jclient.jar
and optic.jar
). These JARs contain the classes necessary for client interaction. You only need to add oc4jclient.jar
to your CLASSPATH because all other JAR files required by the client are referenced in the oc4jclient.jar
manifest classpath.
If you download this file into a browser, you must grant certain permissions as described in the "Granting Permissions" section of the Security chapter in the Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide.
To invoke or be invoked by CORBA objects, RMI objects must have corresponding stubs, skeletons, and IDL. Use the rmic.jar
compiler to generate stubs and skeletons from Java classes or to generate IDL, as described in "Configuring OC4J for RMI".
For use with RMI/IIOP, be sure to compile using the -iiop
option.
In OC4J, EJBs use RMI/ORMI, a proprietary protocol, to communicate (as described in Chapter 5, "Oracle Remote Method Invocation"). You can convert an EJB to use RMI/IIOP, making it possible for EJBs to invoke one another across EJB containers.
The following four sections provide details on making the conversions.
Follow these steps to convert an EJB to use RMI/IIOP in a standalone environment:
-DGenerateIIOP=true
flag.
admin.jar
. You must obtain the client's stub JAR file using the -iiopClientJar
switch. Here is an example:
java -jar $J2EE_HOME/admin.jar ormi://localhost admin welcome -deploy -file filename
-deployment_name application_name -iiopClientJar stub_jar_filename
classpath
to include the stub JAR file that was obtained during deployment by running admin.jar
with the -iiopClientJar
switch.
A copy of the stub JAR file that were generated by OC4J can also be found in the server's deployment directory at:
application_deployment_directory/appname/ejb_module/module_iiopClient.jar
java.naming.provider.url
to use a corbaname
URL instead of an ormi
URL. For details on the corbaname
URL, see "The corbaname URL".
rmic.jar
to generate IDL (the Interface Description Language) describing its interfaces. See "Configuring OC4J for Interoperability" for a discussion of command-line options.
This section expands upon the preceding section, describing how to convert an EJB to use RMI/IIOP in a standalone environment.
orion_ejb_jar.xml
and in internal_settings.xml
. See "CSIv2 Security Properties (orion-ejb-jar.xml)" and "EJB Server Security Properties (internal-settings.xml)" for details.
-DGenerateIIOP=true
flag.
admin.jar
. You must obtain the client's stub JAR file using the -iiopClientJar
switch. Here is an example:
java -jar $J2EE_HOME/admin.jar ormi://localhost admin welcome -deploy -file filename
-deployment_name application_name -iiopClientJar stub_jar_filename
classpath
to include the stub JAR file that was obtained during deployment by running admin.jar
with the -iiopClientJar
switch.
A copy of the stub JAR file that was generated by OC4J can also be found in the server's deployment directory at:
application_deployment_directory/appname/ejb_module/module_iiopClient.jar
java.naming.provider.url
to use a corbaname
URL instead of an ormi
URL. For details on the corbaname
URL, see "The corbaname URL".
rmic.jar
to generate IDL (the Interface Description Language), describing its interfaces. See "Configuring OC4J for Interoperability" for a discussion of command-line options.
You can access an EJB using RMI/IIOP in an Oracle Application Server environment in two ways:
You can configure an EJB to be accessible by means of RMI/IIOP in an Oracle Application Server environment by using Oracle Enterprise Manager. Follow these steps:
home
.
By default, RMI/IIOP is disabled in an Oracle Application Server environment. To enable RMI/IIOP, ensure that a unique IIOP port (or port range) exists for each OC4J instance by entering the value in the IIOP ports field, as shown in Figure 6-3. Click Apply.
Deploy your application following the Oracle Enterprise Manager deployment wizard.
Enable generation of client IIOP stubs for this application by selecting Generate IIOP stubs, as shown in Figure 6-4.
Finish deploying your application following the Oracle Enterprise Manager deployment wizard.
Follow these steps to manually configure an EJB for remote access by RMI/IIOP in an Oracle Application Server environment:
J2EE_HOME
/opmn/conf/opmn.xml
, that a unique IIOP port (or port range) exists for each OC4J instance to be managed by OPMN.
Here is an example:
<ias-component id="OC4J"> <process-type id="home" module-id="OC4J"> <port id="ajp" range="3000-3100"/> <port id="rmi" range="23791-23799"/> <port id="jms" range="3201-3300"/> <port id="iiop" range="3401-3500"/> <process-set id="default_island" numprocs="1"/> </process-type> </ias-component>
dcmctl
. Use the following command:
dcmctl updateConfig
opmnctl
or Oracle Enterprise Manager, restart all OC4J instances that are managed by OPMN.
For information on opmnctl
, use the following command:
opmnctl help
To stop and restart OPMN and all OPMN-managed processes, first use the following command:
opmnctl stopall
and then:
opmnctl startall
For information on Oracle Enterprise Manager, see the Oracle Application Server Containers for J2EE User's Guide.
dcmctl
, specifying the -enableIIOP
option. Here is an example:
dcmctl deployApplication -f filename -a application_name -enableIIOP
classpath
to include the stub JAR file that was generated by OC4J. This file is normally found in the server's deployment directory:
application_deployment_directory
/appname
/ejb_module
/module
_iiopClient.jar
java.naming.provider.url
to use an OPMN
or corbaname
URL instead of an ormi
URL. For details on the corbaname
URL, see "The corbaname URL". For details on the OPMN URL, see "The OPMN URL".
rmic.jar
to generate IDL (the Interface Description Language), describing its interfaces. See "Configuring OC4J for Interoperability" for a discussion of command-line options.
You can access an EJB using RMI/IIOP in an Oracle Application Server environment in two ways:
The advanced configuring for interoperability using Oracle Enterprise Manager differs from the simple configuring described under "Configuring for Interoperability Using Oracle Enterprise Manager" only in the specification of ports. That is, you must specify an iiop
, iiops1
, and iiops2
port (or port range) for each OC4J instance in which interoperability with CSIv2 is to be enabled. Failure to do so causes OC4J to not configure an IIOP listener, thus automatically disabling interoperability, regardless of the configuration in the internal-settings.xm
file of OC4J. This is shown in Figure 6-5.
This section expands upon the preceding section, describing how to convert an EJB to use RMI/IIOP in an Oracle Application Server environment.
orion_ejb_jar.xml
and in internal_settings.xml
. See "CSIv2 Security Properties (orion-ejb-jar.xml)" and "EJB Server Security Properties (internal-settings.xml)" for details.
J2EE_HOME
/opmn/conf/opmn.xml
, that a unique iiop
, iiops1
, and iiops2
port (or port range) exists for each OC4J instance to be managed by OPMN. These are the port meanings:
iiop
--standard IIOP port
iiops1
--IIOP/SSL port used for server-side authentication only
iiops2
--IIOP/SSL port used for both client and server authentication
Here is an example:
<ias-component id="OC4J"> <process-type id="home" module-id="OC4J"> <port id="ajp" range="3000-3100"/> <port id="rmi" range="23791-23799"/> <port id="jms" range="3201-3300"/> <port id="iiop" range="3401-3500"/> <port id="iiops1" range="3501-3600"/> <port id="iiops2" range="3601-3700"/> <process-set id="default_island" numprocs="1"/> </process-type> </ias-component>
opmnctl
or Oracle Enterprise Manager, restart all OC4J instances that are managed by OPMN.
For information on opmnctl
, use the following command:
opmnctl help
To stop and restart OPMN and all OPMN-managed processes, first use the following command:
opmnctl stopall
and then:
opmnctl startall
For information on Oracle Enterprise Manager, see the Oracle Application Server Containers for J2EE User's Guide.
dcmctl
, specifying the -enableIIOP
option. Here is an example:
dcmctl deployApplication -f filename -a application_name -enableIIOP
classpath
to include the stub JAR file that was generated by OC4J. This is normally found in the server's deployment directory:
application_deployment_directory
/appname
/ejb_module
/module
_iiopClient.jar
java.naming.provider.url
to use an OPMN
or corbaname
URL instead of an ormi
URL. For details on the corbaname
URL, see "The corbaname URL". For details on the OPMN URL, see "The OPMN URL".
rmic.jar
to generate IDL (the Interface Description Language), describing its interfaces. See "Configuring OC4J for Interoperability" for a discussion of command-line options.
To interoperate, an EJB must look up other beans using CosNaming. This means that the URL for looking up the root NamingContext
must use the corbaname
URL scheme instead of the ormi
URL scheme. This section discusses the corbaname
subset that is most used by EJB developers. For a full discussion of the corbaname
scheme, see section 2.5.3 of the CORBA Naming Service Specification. The corbaname
scheme is based on the corbaloc
scheme, which section 13.6.10.1 of the CORBA specification discusses.
The most common form of the corbaname
URL scheme is:
corbaname::host
[:port
]
This corbaname
URL specifies a conventional DNS host name or IP address and a port number. For example,
corbaname::example.com:8000
A corbaname
URL can also specify a naming context by following the host and port by #
and NamingContext
in string representation. The CosNaming service on the specified host is responsible for interpreting the naming context.
corbaname::host
[:port
]#namingcontext
For example:
corbaname::example.com:8000#Myapp
This section describes OPMN URL details specific to RMI/IIOP. For general information about the OPMN URL, see "JNDI Properties for RMI".
In an Oracle Application Server environment, IIOP ports for all OC4J processes within each Oracle Application Server instance are dynamically managed by OPMN. Because the ports are dynamically allocated by OPMN, it might not be possible for clients to know the ports on which OC4J processes are actively listening for IIOP requests. To enable clients to successfully make RMI/IIOP requests in an Oracle Application Server environment without having to know the IIOP ports for all active OC4J processes, modify the jndi.naming.provider.url
property (in the client's jndi.properties
file) with a URL of the following format:
opmn:corbaname::opmn_host[:opmn_port]:]:OC4J_instance_name#naming_context
For example:
opmn:corbaname::dlsun74:6003:home#stateless
When EJBs are invoked over IIOP, OC4J must map system exceptions to CORBA exceptions. Table 6-1 lists the exception mappings.
EJBs that are not hosted in OC4J must add the file oc4j_interop.jar
to the classpath
to invoke OC4J-hosted EJBs. OC4J expects the other container to make the HandleDelegate
object available in the JNDI name space at java:comp/HandleDelegate.
The oc4j_interop.jar
file contains the standard portable implementations of home and remote handles, and metadata objects.
To add interoperability support to your EJB, you must specify interoperability properties. Some of these properties are specified when starting OC4J and others in bean properties that are specified in deployment files.
The following OC4J startup flags support RMI interoperability:
-DGenerateIIOP=true
: generates new stubs and skeletons whenever you redeploy an application.
-Diiop.debug=true
: generates deployment-time debugging messages, most of which have to do with code generation.
-Diiop.runtime.debug=true
: generates runtime debugging messages.
Before EJBs can communicate, you must configure the parameters in the configuration files listed in Table 6-2.
Context | File | Description |
---|---|---|
Server |
|
The <sep-config path="./internal-settings.xml"> |
|
|
This file specifies server extension provider properties that are specific to RMI/IIOP. See "EJB Server Security Properties (internal-settings.xml)" for details. |
Application |
|
The |
|
|
This file specifies client-side security properties for an EJB. See "EJB Client Security Properties (ejb_sec.properties)" for details. |
|
|
This file specifies the URL of the initial naming context used by the client. See "JNDI Properties for Interoperability (jndi.properties)" for details. |
You specify server security properties in the internal-settings.xml
file.
This file specifies certain properties as values within <sep-property>
entities. Table 6-3 contains a list of properties.
The table refers to keystore and truststore files, which use the Java Key Store (JKS), a JDK-specified format, to store keys and certificates. A keystore stores a map of private keys and certificates. A truststore stores trusted certificates for the certificate authorities (CAs, such as VeriSign and Thawte).
Note:
In Table 6-3, the properties |
If OC4J is started by the Oracle Process Management Notification service (OPMN) in an Oracle Application Server (as opposed to standalone) environment, then ports specified in internal-settings.xml
are ignored. If OPMN is configured to disable IIOP for a particular OC4J instance, then, even though IIOP may be enabled through internal-settings.xml
(as pointed to by server.xml
), IIOP is not enabled.
The following example shows a typical internal-settings.xml
file:
<server-extension-provider name="IIOP" class="com.oracle.iiop.server.IIOPServerExtensionProvider"> <sep-property name="port" value="5555" /> <sep-property name="host" value="localhost" /> <sep-property name="ssl" value="false" /> <sep-property name="ssl-port" value="5556" /> <sep-property name="ssl-client-server-auth-port" value="5557" /> <sep-property name="keystore" value="keystore.jks" /> <sep-property name="keystore-password" value="123456" /> <sep-property name="truststore" value="truststore.jks" /> <sep-property name="truststore-password" value="123456" /> <sep-property name="trusted-clients" value="*" /> </server-extension-provider>
Here is the DTD for internal-settings.xml:
<!-- A server extension provider that is to be plugged in to the server. --> <!ELEMENT server-extension-provider (sep-property*) (#PCDATA)> <!ATTLIST server-extension-provider name class CDATA #IMPLIED> <!ELEMENT sep-property (#PCDATA)> <!ATTLIST sep-property name value CDATA #IMPLIED> <!-- This file contains internal server configuration settings. --> <!ELEMENT internal-settings (server-extension-provider*)>
CSIv2 is an Object Management Group (OMG) standard for a secure interoperable wire protocol that supports authorization and identity delegation. You configure CSIv2 properties in three different locations:
"CSIv2 Security Properties (internal-settings.xml)", "CSIv2 Security Properties (orion-ejb-jar.xml)", and "EJB Client Security Properties (ejb_sec.properties)" discusses these configuration files.
This section discusses the semantics of the values you set within the <sep-property>
element in internal_settings.xml
. For details of syntax, see "EJB Server Security Properties (internal-settings.xml)" .
To use the CSIv2 protocol with OC4J, you must both set ssl
to true
and specify an IIOP/SSL port (ssl-port
).
ssl
to true
, then CSIv2 is not enabled. Setting ssl
to true
permits clients and servers to use CSIv2, but does not require them to communicate using SSL.
ssl-port
, then no CSIv2 component tag is inserted by the server into the IOR, even if you configure an <ior-security-config>
entity in orion-ejb-jar.xml
.
When IIOP/SSL is enabled on the server, OC4J listens on two different sockets--one for server authentication alone, and one for server and client authentication. You specify the server authentication port within the <sep-property>
element. The server and client authentication listener uses the port number immediately following.
For SSL clients using server authentication alone, you can specify:
If you specify neither keystore nor truststore, then the handshake may fail if there are no default truststores established by the security provider.
SSL clients using client-side authentication must specify both a keystore and a truststore. The certificate from the keystore is used for client authentication.
If the client does not use client-side SSL authentication, you must set client.sendpassword
in the ejb_sec.properties
file for the client runtime to insert a security context and send the user name and password. You must also set server.trustedhosts
to include your server.
If the client does use client-side SSL authentication, the server extracts the DistinguishedName
from the client's certificate and then looks it up in the corresponding user manager. It does not perform password authentication.
Two types of trust relationships exist:
Clients list trusted servers in the EJB property oc4j.iiop.trustedServers
. See Table 6-4, "EJB Client Security Properties" for details. Servers list trusted clients in the trusted-client
property of the <sep-property>
element in internal-settings.xml
. See "EJB Server Security Properties (internal-settings.xml)" for details.
Conformance level 0 of the EJB standard defines two ways of handling trust relationships:
trusted-client
list, or both
OC4J offers both kinds of trust. You configure trust using the bean's <ior-security-config>
element in orion-ejb-jar.xml
. See "CSIv2 Security Properties (orion-ejb-jar.xml)" for details.
This section discusses the CSIv2 security properties for an EJB. You configure each individual bean's CSIv2 security policies in its orion-ejb-jar.xml
. The CSIv2 security properties are specified within <ior-security-config>
elements. Each element contains a <transport-config>
element, an <as-context>
element, and an <sas-context>
element.
This element specifies the transport security level. Each element within <transport-config>
must be set to supported
, required
, or none
. None
means that the bean neither supports nor uses that feature; supports
means that the bean permits the client to use the feature; required
means that the bean insists that the client use the feature. The elements are:
<integrity>
: Is there a guarantee that all transmissions are received exactly as they were transmitted?
<confidentiality>
: Is there a guarantee that no third party was able to read transmissions?
<establish-trust-in-target>
: Does the server authenticate itself to the client?
<establish-trust-in-client>
: Does the client authenticate itself to the server?
This element specifies the message-level authentication properties.
<auth-method>
: must be set to either username_password
or none
. If set to username_password
, beans use user names and passwords to authenticate the caller.
<realm>
: must be set to default
at the current release.
<required>
: if set to true
, the bean requires the caller to specify a user name and password.
This element specifies the identity delegation properties. It has one element, <caller-propagation>
, which can be set to supported
, required
, or none
. If the <caller-propagation>
element is set to supported
, then this bean accepts delegated identities from intermediate servers. If it is set to required
, then this bean requires all other beans to transmit delegated identities. If set to none
, this bean does not support identity delegation.
An example:
<ior-security-config> <transport-config> <integrity>supported</integrity> <confidentiality>supported</confidentiality> <establish-trust-in-target>supported</establish-trust-in-target> <establish-trust-in-client>supported</establish-trust-in-client> </transport-config> <as-context> <auth-method>username_password</auth-method> <realm>default</realm> <required>true</required> </as-context> <sas-context> <caller-propagation>supported</caller-propagation> </sas-context> </ior-security-config>
The DTD for the <ior-security-config>
element is:
<!ELEMENT ior-security-config (transport-config?, as-context? sas-context?) > <!ELEMENT transport-config (integrity, confidentiality, establish-trust-in-target, establish-trust-in-client) > <!ELEMENT as-context (auth-method, realm, required) > <!ELEMENT sas-context (caller-propagation) > <!ELEMENT integrity (#PCDATA) > <!ELEMENT confidentiality (#PCDATA)> <!ELEMENT establish-trust-in-target (#PCDATA) > <!ELEMENT establish-trust-in-client (#PCDATA) > <!ELEMENT auth-method (#PCDATA) > <!ELEMENT realm (#PCDATA) > <!ELEMENT required (#PCDATA)> <!-- Must be true or false --> <!ELEMENT caller-propagation (#PCDATA) >
Any client, whether running inside a server or not, has EJB security properties. Table 6-4 lists the EJB client security properties controlled by the ejb_sec.properties
file. By default, OC4J searches for this file in the current directory when running as a client or in J2EE_HOME/config
when running in the server. You can specify this file's location explicitly with -Dejb_sec_properties_location=
pathname
.
The following RMI/IIOP properties are controlled by the client's jndi.properties
file:
java.naming.provider.url
may be an OPMN
or a corbaname
URL for the bean to be interoperable. For details on corbaname
URLs, see "The corbaname URL". For details on the OPMN URL, see "The OPMN URL".
contextFactory
can be either ApplicationClientInitialContextFactory
or the class IIOPInitialContextFactory
.
If your application has an application-client.xml
, then leave contextFactory
set to ApplicationClientInitialContextFactory
.
If your application does not have an application-client.xml
, then change contextFactory
to IIOPInitialContextFactory
.
com.evermind.server.ApplicationClientInitialContextFactory
is used when looking up remote objects from stand-alone application clients. It uses the refs
and ref-mappings
found in application-client.xml
and orion-application-client.xml
. It is the default initial context factory when the initial context is instantiated in a Java application.
com.oracle.iiop.server.IIOPInitialContextFactory
is used when looking up remote objects between different containers using the IIOP protocol.
|
Copyright © 1996, 2003 Oracle Corporation. All Rights Reserved. |
|