Oracle9iAS Containers for J2EE Services Guide Release 2 (9.0.3) Part Number A97690-01 |
|
This chapter describes OC4J support for cross-platform distributed EJB interoperation and for using RMI over HTTP (RMI tunneling).
This chapter covers the following topics:
Version 2.0 of the Enterprise Java Beans 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. Redeployment details are discussed in "Simple Interoperability" .
EJB interoperability consists of the following:
OC4J provides all these features.
OC4J supports the CORBA CosNaming service. OC4J can publish EJBHome
object references in a CosNaming service. OC4J 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 CSIv2. CSIv2 specifies different conformance levels; OC4J complies with the EJB specification, which requires conformance level 0.
The EJB2.0 specification specifies an optional transactional interoperability feature. Conformant implementations must choose one of the following:
This release of OC4J is transactionally non-interoperable. This means that when a transaction spans EJB containers, OC4J raises a specified exception.
In OC4J, EJBs use RMI/ORMI, a proprietary protocol, to communicate. It is easy to convert an EJB to using RMI/IIOP; this makes it possible for EJBs to invoke one another across EJB containers.
Follow these steps:
-DGenerateIIOP=true
flag.
java.naming.provider.url
to use a corbaname
URL instead of an ormi
URL. For details on the corbaname
URL, see "The corbaname URL".
classpath
to include the stub JAR file generated by OC4J. This will normally be
application_deployment_directory
/appname
/ejb-module
/module
_iiopClient.jar
If you do not have access to the deployment directory, you can obtain the generated stub JAR file during deployment by running admin.jar
with the -iiopClientJar
switch
rmic.jar
to generate IDL describing its interfaces. See "Configuring OC4J for Interoperability" for a discussion of command-line options.
-DGenerateIIOP=true
flag.
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.
java.naming.provider.url
to use a corbaname
URL instead of an ormi
URL. For details on the corbaname
URL, see "The corbaname URL".
classpath
to include the stub JAR file generated by OC4J. This will normally be
application_deployment_directory
/appname
/module
/module
_iiopClient.jar
rmic.jar
to generate IDL describing its interfaces. See "Configuring OC4J for Interoperability" for a discussion of command-line options.
In order 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 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 is discussed in section 13.6.10.1 of the CORBA specification.
The most common form of the corbaname
URL scheme is:
corbaname::host
[:port
]
This specifies a conventional DNS hostname 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 a stringified NamingContext
. 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
In order to invoke or be invoked by CORBA objects, RMI objects must have corresponding stubs, skeletons, and IDL. The rmic.jar
compiler can used to generate stubs and skeletons from Java classes or to generate IDL. The generated IDL can be used to generate non-Java stubs and skeletons using any CORBA IDL compiler.
java -jar rmic.jaroptions
classname
...
The rmic.jar
compiler takes the following options:
-always
(same as -alwaysgenerate
)--Forces the compiler to generate new outputs even when the existing stubs, ties, or IDL are newer than the input class. Requires the -iiop
or -idl
flags.
-classpath
classpath
--Specifies the directories to search for the classes.
-d
pathname
-- Specifies output directory for generated class files.
-g
--Generates debugging information.
-idl
--Generates IDL for all classes in the input, as well as any classes they reference. IDL, the Interface Description Language, is Corba's mechanism for describing methods and data in a language-independent way.
-idlModule <fromJavaPackage<.class>> <toIDLModule>
--Specifies IDLEntity package mapping. An example:
-idlModule foo.bar my::real::idlmod
-idlFile <fromJavaPackage<.class>> <toIDLFile>
--Specifies IDLEntity file mapping. An example:
-idlFile test.pkg.X TEST16.idl
-iiop
--Generates IIOP stubs and ties. Stub classes are called by clients to transmit RMI messages over IIOP; tie classes are called by the server to process incoming calls and dispatch them to the implementation class. Each remote interface has a stub; each server implementation class has a tie. Stub classes are also generated for abstract interfaces. An abstract interface does not extend java.rmi.Remote
; in addition, it either has no methods or all of its methods throw java.rmi.RemoteException
or one of its superclasses.
-keep
(same as -keepgenerated
)--Preserves intermediate generated source files; by default, these are deleted.
-nolocalstubs
--Does not create stubs optimized to run in the same process as the server. Requires -iiop
.
-nowarn
--Turns off all compiler warnings.
-noValueMethods
--Stops generation of IDL for methods and constructors within IDL valuetypes. Requires -idl
.
-v1.1
--Creates stubs and skeletons for 1.1 stub protocol version only. By default. rmic generates stubs and skeletons compatible with both 1.1 and 1.2.
-v1.2
--Creates stubs and skeletons for 1.2 stub protocol version only. By default. rmic generates stubs and skeletons compatible with both 1.1 and 1.2.
-vcompat
(default)--Creates stubs/skeletons compatible with both 1.1 and 1.2 stub protocol versions.
-verbose
--Sends messages about compiler status to stdout
.
When EJBs are invoked over IIOP, OC4J must map system exceptions to CORBA exceptions. Table 10-1, "Java-CORBA Exception Mappings" lists the exception mappings.
EJBs that are not hosted in OC4J must add the file oc4j_interop.jar
to the classpath in order to invoke OC4J-hosted EJBs. OC4J expects the other container to make HandleDelegate
object available in the JNDI namespace 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 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.
The following files contain entries that specify interoperability information.
server.xml
The <sep-config>
element in this file specifies the pathname, normally internal-settings.xml
, for the server extension provider properties.
<sep-config path="internal-settings.xml">
internal-settings.xml
Specifies server extension provider properties specific to RMI/IIOP. See "EJB Server Security Properties (internal-settings.xml)" for details.
orion-ejb-jar.xml
(Server) The <ior-security-config>
sub-entity of the <session-deployment>
and <entity-deployment>
entities specifies Common Secure Interoperability Version 2 (CSIv2) security properties. See "CSIv2 Security Properties" for details.
ejb_sec.properties
(Client) Specifies client-side security properties for an EJB. See "EJB Client Security Properties (ejb_sec.properties)" for details.
jndi.properties
(Client) Specifies the URL of the initial naming context. See "JNDI Properties for Interoperability (jndi.properties)" for details.
You specify server security properties in internal-settings.xml
.
This file specifies the following properties as values within <sep-property>
entities. Table 10-2, "EJB Server Security Properties" contains a list of properties.
The keystore and truststore files use JDK-specified formats 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).
A typical internal-settings.xml
looks like:
<server-extension-provider name="IIOP" class="com.oracle.iiop.server.IIOPServerExtensionProvider"> <sep-property name="port" value="4444" /> <sep-property name="host" value="localhost" /> <sep-property name="trusted-clients" value="*.example.com" /> <sep-property name="ssl" value="true" /> <sep-property name="ssl-port" value="4445" /> <sep-property name="keystore" value="keystore1" /> <sep-property name="keystore-password" value="changeit" /> </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*)>
Common Secure Interoperability version 2 (CSIv2) is an OMG standard for a secure interoperable wire protocol that supports authorization and identity delegation. You configure CSIv2 properties in three different locations:
These configuration files are discussed in "CSIv2 Security Properties (internal-settings.xml)", "CSIv2 Security Properties (orion-ejb-jar.xml)", and "EJB Client Security Properties (ejb_sec.properties)".
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)" .
In order 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 may specify:
If you specify neither keystore nor truststore, 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 in order for the client runtime to insert a security context and send the username 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.
There are two types of trust relationships:
Clients list trusted servers in the EJB property oc4j.iiop.trustedServers
. See Table 10-3, "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 provides 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; requires
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 will use user names and passwords to authenticate the caller.
<realm>
--Must be set to default
at this release.
<required>
--If set to true
, the bean requires the caller to specify a username 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. The following are 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
. Table 10-3 lists the properties controlled by the ejb_sec.properties
file.
The following RMI/IIOP properties are controlled by the client's jndi.properties
file:
java.naming.provider.url
must be a corbaname
URL in order for the bean to be interoperable. For details on corbaname
URLs, see "The corbaname URL".
contextFactory
can now be either ApplicationClientInitialContextFactory
or the new class IIOPInitialContextFactory
.
If your application has an application-client.xml
, leave contextFactory
set to ApplicationClientInitialContextFactory.
If your application does not have an application-client.xml
, change contextFactory
to IIOPInitialContextFactory
.
When EJBs must communicate across firewalls they can use tunneling to transmit RMI across HTTP. This tunneling is supported only with RMI/ORMI; you cannot do HTTP tunneling with RMI/IIOP.
To configure OC4J to support RMI tunneling, do the following:
ormi://hostname:ormi_port/the_app
You should change the URL to:
http:ormi://hostname:HTTP_PORT/the_app
proxyHost
and (optionally) proxyPort
in the command line when starting the EJB client. If you do not supply a value for proxyPort
, it defaults to 80.
-Dhttp.proxyHost=proxy_host -Dhttp.proxyPort=proxy_port
In order to use RMI from OC4J, you must edit the server.xml
and rmi.xml
files.
Your server.xml
file must specify the pathname of the RMI configuration file in the <rmi-config>
element. The syntax is:
<rmi-config path="RMI_PATH
" />
The usual RMI_PATH
is ./rmi.xml
; you can name the file whatever you like.
The file rmi.xml
must specify which host, port, and username/password will be used to connect to (and accept connections from) remote RMI servers. Your file must contain an <rmi-server>
element describing possible connections. An <rmi-server>
element looks like:
<rmi-server host="hostname" port="port"> <server host="hostname" username="username" port="port" password="password" http-path="pathname"/> <log> <file path="logfilepathname" /> Okay </log> </rmi-server>
<rmi-server>
has the following attributes:
is the host or IP name from which your server will accept RMI requests. hostname
can be a particular hostname or "[ALL]
". If you specify a hostname, the OC4J server will only accept RMI requests from that particular host. If hostname
is "[ALL]
" or you omit the host
attribute, the OC4J server will accept RMI requests from any host.
is the port number on which your server listens for RMI requests. If you omit this attribute, it defaults to 23791.
An <rmi-server>
element can contain zero or multiple <server>
elements and zero or one <log>
elements.
Each <server>
element specifies a server that your application can contact over RMI. A <server>
element takes the form:
<server host="hostname" username="username" port="port" password="password"/>
The host
attribute is required; the remaining attributes are optional.
the name or IP address of the server you will contact over RMI.
the username of a valid principal on the remote server
the port number on which the remote server listens for RMI requests
the password used by the principal username
The <log>
element contains the pathname of a log file to which the server will write all RMI requests.
|
Copyright © 1996, 2002 Oracle Corporation. All Rights Reserved. |
|