Oracle8i Enterprise JavaBeans and CORBA Developer's Guide Release 2 (8.1.6) A81356-01 |
|
This chapter describes the tools you use to deploy CORBA implementations and Enterprise JavaBeans in the Oracle8i Java environment. You run these tools from a Unix shell or the Windows NT DOS prompt.
The tools described in this chapter as follows:
See the Oracle8i Java Developer's Guide for information on loadjava
and dropjava
.
Each database instance running the Oracle8 i JServer software has a session namespace, which the Oracle8 i ORB uses to activate CORBA and EJB objects. A session namespace is a hierarchical collection of objects known as PublishedObjects and PublishingContexts. PublishedObjects are the leaves of the hierarchy and PublishingContexts are the nodes, analogous to UNIX file system files and directories. Each PublishedObject is associated with a class schema object that represents a CORBA or EJB implementation. To activate a CORBA or EJB object, a client refers to a PublishedObject's name. From the PublishedObject, the Oracle8 i ORB obtains the information necessary to find and launch the corresponding class schema object.
Creating a PublishedObject is known as publishing and can be done with the command-line publish
tool or the interactive session shell, both of which this section describes. CORBA server developers create PublishedObjects explicitly after loading the implementation of an object with loadjava
. EJB developers do not explicitly load or publish their implementations; the deployejb
tool (see "deployejb") implicitly does both.
A PublishedObject has the following attributes:
PublishedObjects and PublishingContexts, as with their file and directory counterparts, have owners and rights (privileges). An owner can be a user name or a role name; only the owner can change the ownership or rights of a PublishedObject or PublishingContext. Table 6-1 describes session namespace rights.
Oracle8 i creates a session namespace automatically when the Oracle8 i ORB is configured. The PublishingContexts contained in Table 6-2 are present in all session namespaces:
Name | Owner | Read | Write | Execute |
---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Because by default only /test
is writable by PUBLIC, you will normally create PublishingContexts and PublishedObjects subordinate to /test
.
The publish
tool creates or replaces (republishes) a PublishedObject in a PublishingContext. It is not necessary to republish when you update a Java class schema object; republishing is required only to change a PublishedObject's attributes. To publish, you must have write permission (the write right) for the destination PublishingContext; by default only the PublishingContext /test
is writable by PUBLIC. To republish you must additionally have the write right for the PublishedObject.
publish [options] <name> <class> [<helper>] -user <username> -password <password> -service <serviceURL>
where options are:
[-describe] [{-g | -grant} {<user> | <role>}[,{<user> | <role>}]...] [{-h | -help}] [-iiop] [-role <role>] [-republish] [-schema <schema>] [-ssl] [-useServiceName] [-version]
Table 6-3 summarizes the publish
tool arguments.
Here is a publish
example.
Publish the CORBA server implementation vbjBankTestbank.AccountManagerImpl
and its helper class as /test/bankMgr
in the tool invoker's schema:
publish /test/bankMgr vbjBankTestServer.AccountManagerImpl \ vbjBankTestServer.AccountManagerHelper \ -user SCOTT -password TIGER \ -service sess_iiop://dlsun164:2481:orcl
The remove
tool removes a PublishedObject or PublishingContext from a session namespace. It does not remove the Java class schema object associated with a PublishedObject; use dropjava
to do that.
remove <name> -user <username> -password <password> -service <serviceURL> [options] [{-d | -describe}] [{-h | -help}] [-iiop] [{-r | -recurse}] [-role role] [-ssl] [-useServiceName] [-version]
Table 6-4 describes the remove
arguments.
Here are examples of remove
tool usage.
/test/testhello
:
remove /test/testhello -user SCOTT -password TIGER \ -service sess_iiop://dlsun164:2481:orcl
/test/etrader
:
remove -r /test/etrader -user SCOTT -password TIGER \ -service sess_iiop://dlsun164:2481:orcl
The sess_sh
(session shell) tool is an interactive interface to a database instance's session namespace. You specify database connection arguments when you start sess_sh
. It then presents you with a prompt to indicate that it is ready for commands.
The sess_sh
gives a session namespace much of the "look and feel" of a Unix file system you access through a shell, such as the C shell. For example, the session shell command:
ls /alpha/beta/gamma
means "List the PublishedObjects and PublishingContexts in the PublishingContext known as /alpha/beta/gamma
". (NT users note: /alpha/beta/gamma
, not \alpha\beta\gamma
.) Indeed, many session shell command names that operate on PublishingContexts have the same names as their Unix shell counterparts that operate on directories. For example: mkdir
(create a PublishingContext) and cd
(change the working PublishingContext).
In addition to Unix-style manipulation of PublishingContexts and PublishedObjects, the session shell can launch an executable, which is analogous to a Java standalone application, that is, a class with a static main()
method. Executables must have been loaded with loadjava
, but not published--publishing is for CORBA and EJB objects only.
sess_sh [options] -user <user> -password <password> -service <serviceURL> [-d | -describe] [-h | -help] [-iiop] [-role <rolename>] [-ssl] [-useServiceName] [-version]
Table 6-5 summarizes the sess_sh
command line arguments.
Here is a sess_sh
example.
Open a session shell on the session namespace of the database orcl
on listener port 2481 on host dbserver
.
sess_sh -user scott -password tiger -service sess_iiop://dbserver:2481:orcl
The cd
command is analogous to a Unix shell's cd
command; it changes the working PublishingContext.
cd [path]
Here is an example.
Change to root PublishingContext:
$ cd /
The chmod
command is analogous to a Unix shell's chmod
command; it changes the users or roles that have rights for a PublishingContext or PublishedObject. See Table 6-1 for descriptions of the read, write, and execute rights. Only the object's owner can change its rights.
chmod [options] {+|-}{r|w|e} {<user> | <role>} [, {<user> | <role>} ...] \ <objectname> [-h | -help] [-version]
Table 6-6 summarizes the chmod
arguments.
Here are some chmod examples.
/alpha/beta/gamma
to Scott and Nancy:
$ chmod +x scott nancy /alpha/beta/gamma
$ chmod -w scott /alpha/beta/gamma
The chown command is analogous to the Unix chown command; it changes the ownership of a PublishingContext or PublishedObject. The owner of a newly created PublishingContext or PublishedObject is the user who publishes it. To change a PublishingContext's or PublishedObject's ownership you must be SYS.
chown [options] {<user> | <role>} <objectname> [-h | -help] [-version]
Table 6-7 summarizes the chown
arguments.
Here is a chown
example.
Make Scott the owner of /alpha/beta/gamma
:
$ chown scott /alpha/beta/gamma
The exit
command terminates sess_sh
.
exit
Here is an example:
Leave the session shell:
$ exit %
The help
command summarizes the syntax of the session shell commands.
help
Here is a help
example.
$ help Commands are of the format <command> [arg1, ar2...] Intrinsic Commands: exit exit the shell help prints this message version print version inforamtion pwd print working directory cd change working directory ls list directory ln link name chmod change read, write or execute permissions on an object chown change an objects owner mkdir create a directory mv move an object or directory to another location rm remove an object or directory lls list directory on local file system lpwd print local file system working directory lcd change the local file systems working directory loadjar load java classes, source, resources from jar files into the server loadfile load java classes, source, resources from files into the server publish publish an object republish republish an object java execute the "main" method on a java class
The java
command is analogous to the JDK java
command; it invokes a class's static main()
method. The class must have been loaded with loadjava
. (There is no point to publishing a class that will be invoked with the java
command.) The java
command provides a convenient way to test Java code that runs in the database. In particular, the command catches exceptions and redirects the class's standard output and standard error to the session shell, which displays them as with any other command output. (The usual destination of standard out and standard error for Java classes executed in the database is one or more database server process trace files, which are inconvenient and may require DBA priviliges to read.)
java class [arg1 ... argn] [options] [{-h | -help}] [-schema <schema>] [-version]
Table 6-8 summarizes the java
arguments.
Here is a java
command example.
Say hello and display arguments:
package hello; public class World { public World() { super(); } public static void main(String[] argv) { System.out.println("Hello from the JServer/ORB"); if (argv.length != 0) System.out.println("You supplied " + argv.length + " arguments: "); for (int i = 0; i < argv.length; i++) System.out.println(" arg[" + i + "] : " + argv[i]); } }
Compile, load, publish, and run the executable as follows, substituting your userid, host, and port information as appropriate:
% javac hello/World.java % loadjava -r -user scott/tiger@localhost:2481:orcl hello/World.class % sess_sh -user scott -password tiger -service sess_iiop://localhost:2481:orcl $ java testhello alpha beta Hello from the JServer/ORB You supplied 2 arguments: arg[0] : alpha arg[1] : beta $
The lcd
(local cd
) command changes the local working directory just as executing cd
outside of the session shell would.
lcd [path]
Here is an example of the lcd
command.
Change the file system directory to alpha/beta
:
$ lcd alpha/beta
The lls
(local ls
) command lists the contents of the working directory, just as executing ls
outside of the session shell would.
lls [-l] [<path>]
Table 6-9 summarizes the lls
command's arguments.
Option | Description |
---|---|
-l |
Lists the directory in long format. |
<path> |
Lists the directory named in |
Here is an lls
command example.
List the working file system directory in long format:
$ lls -l
The ln
(link) command is analogous to the Unix ln
command. A link is a synonym for a PublishingContext or PublishedObject. A link can prevent a reference to a PublishingContext or PublishedObject from becoming invalid when you move a PublishingContext or PublishedObject (see "mv Command"); creating a link with the old name makes the object accessible by both its old and new names.
ln <object> <link>
Table 6-10 summarizes the ln
arguments.
Option | Description |
---|---|
<object> |
The name of the PublishingContext or PublishedObject for which a link is to be created. |
<link> |
The synonym by which |
Here is an ln
command example.
Preserve access via old
although the object's name is changed to new
:
$ mv old new $ ln new old
The lpwd
(local print working directory) command displays the name of the working directory, just as executing pwd
outside of the session shell would.
lpwd
Here is an example of the lpwd
command that shows the working directory:
$ lpwd /home/usr/billc
The ls
(list) command shows the contents of PublishingContexts as the Unix ls
command shows the contents of directories.
ls [options] [{<pubcon> | <pubobj} [{<pubcon> | <pubobj}] ...] [-dir] [-h | -help] [-l] [-ld | ldir] [-R] [-version]
Table 6-11 describes the ls
arguments.
Here are examples of the ls
command.
Show contents of the root PublishingContext in short format:
$ ls / bin/ etc/ test/
Show contents of the root PublishingContext in long format:
$ ls -l / Read Write Exec Owner Date Time Name Schema Class Helper PUBLIC SYS PUBLIC SYS Dec 14 14:59 bin/ PUBLIC SYS PUBLIC SYS Dec 14 14:59 etc/ PUBLIC PUBLIC PUBLIC SYS Dec 14 14:59 test/
Show contents of the /test
PublishingContext in long format:
$ ls -l test Read Write Exec Owner Date Time Name Schema Class Helper SCOTT SCOTT SCOTT SCOTT Dec 14 16:32 bank SCOTT Bank.AccountManagerImpl Bank.AccountManagerHelper
The mkdir
command is analogous to the Unix shell mkdir
command; it creates a PublishingContext. You must have the write right for the target PublishingContext to use mkdir
in it.
mkdir [options] <name> [-path]
Table 6-12 describes the mkdir
arguments.
Option | Description |
---|---|
<name> |
Name of PublishingContext to create. |
-path |
Creates intermediate PublishingContexts if they do not exist. |
Here are examples of the mkdir
command.
Create a PublishingContext called /test/alpha
(/test
exists):
mkdir /test/alpha
Create a PublishingContext called /test/alpha/beta/gamma
(/test/alpha/beta
does not exist):
$ mkdir -path /test/alpha/beta/gamma
The mv
command is analogous to the Unix shell mv
command.
mv <old> <new>
Here is an example of the mv
command.
Change the name of /test/foo
to /test/bar
:
$ mv /test/foo /test/bar
The publish
command creates or replaces (republishes) a PublishedObject in a PublishingContext. It is not necessary to republish when you update a Java class schema object that has been published; republish only to change a PublishedObject's attributes. To publish, you must have the write right for the destination PublishingContext; to republish you must also have the write right for the PublishedObject.
publish <name> <class> <helper> [options] [{-e | -executable}] [{-g | -grant} {<user> | <role>}[,{<user> | <role>} ... ]] [{-h | -help}] [-republish] [-schema <schema>] [-version]
Table 6-13 summarizes the publish
command arguments.
Here is an example of the publish
command.
Publish the CORBA server implementation Bank.AccountManagerImpl
and its helper class as /test/bank
in the command invoker's schema:
$ ls -l /test $ publish /test/bank Bank.AccountManagerImpl Bank.AccountManagerHelper$ ls -l /test Read Write Exec Owner Date Time Name Schema Class Helper SCOTT SCOTT SCOTT SCOTT Dec 14 16:32 bank SCOTT Bank.AccountManagerImpl Bank.AccountManagerHelper
The pwd command displays the name of the current working PublishingContext. It is analogous to the Unix pwd
command.
pwd
Here is an example of the pwd
command.
$ pwd /test/alpha
The rm
(remove) command is analogous to the rm -r
Unix shell commands; it removes a PublishedObject or a PublishingContext, including its contents. To remove an object, you must have the write right for the containing PublishingContext.
rm [options] <object> ... <object> [{-h | -help}] [-r] [-version]
Table 6-14 describes the rm
arguments.
Here is an example of the rm
command.
Remove the PublishedObject /test/bank
:
rm /test/bank
Remove the PublishingContext /test/release3
and everything it contains:
rm -r /test/release3
The version
command shows the version of the sess_sh
tool.
version
Here is an example of the version
command.
Display the session shell's version:
$ version 1.0
Instead of loadjava
and publish
, Enterprise JavaBean developers use the deployejb
tool, which performs equivalent operations, as well as generating and compiling infrastructure code for the EJB. The ejbdescriptor
tool is a utility for translating between the text and serialized object forms of EJB deployment descriptors.
From a deployment descriptor and a JAR containing interfaces and classes, the deployejb
tool makes an EJB implementation ready for test or production clients to invoke. deployejb
converts the text descriptor to a serialized object, generates and compiles classes that effect client-bean communication, loads compiled classes into the database, and publishes the bean's home interface name in the session namespace so clients can look it up with JNDI. The BeanHomeName must refer to a PublishingContext for which the deployejb
invoker has the write right; see "publish" for the rights required to publish.
To invoke a deployed bean, the client's CLASSPATH must include the remote and home interface files and the JAR generated by deployejb
.
deployejb -user <username> -password <password> -service <serviceURL> -descriptor <file> -temp <dir> <beanjar> [-addclasspath <dirlist>] [-describe] [-generated <clientjar>] [-help] [-iiop] [-keep] [-republish] [-role <role>] [-ssl] [-useServiceName] [-verbose] [-version]
Table 6-15 summarizes the deployejb
arguments.
deployejb
needs the classes the home and remote interfaces depend on and the classes the bean implementation depends on. These dependency classes can either be included in the <beanjar>
file or directories containing them or can be specified in the -addclasspath
argument. The first approach is less prone to error, the second can substantially reduce deployejb
's run time. If you use -addclasspath
, then you must ensure that the classes have been loaded before you run a client that activates the EJB.
Here is a deployejb
example.
Basic invocation specifying the name of the generated client JAR file:
deployejb -user scott -password tiger -service sess_iiop://dbserver:2481:orcl \ -descriptor myBeanDescriptor.txt -temp /tmp/ejb \ -generated myBeanClient.jar myBean.jar
Each EJB implementation includes a serialized Java object known as a deployment descriptor. The values in a deployment descriptor are not readable by people, yet people must create them and might sometimes have to read them. The ejbdescriptor
tool transforms a serialized deployment descriptor to text and converse. Developers are most likely to use ejbdescriptor
to extract the deployment descriptor data from an EJB developed for a non-Oracle environment. The deployejb
tool calls ejbdescriptor
to build a deployment descriptor from the text file you specify in the -descriptor
argument.
ejbdescriptor {-parse | -dump} <infile> <outfile>
Table 6-16 describes the ejbdescriptor
arguments.
Here are examples of the ejbdescriptor
tool.
Create a text file representation of a descriptor:
ejbdescriptor -dump beandescriptor.ser beandescriptor.ejb
Create a serialized deployment descriptor from a text file:
ejbdescriptor -parse beandescriptor.ejb beandescriptor.ser
Display the contents of a deployment descriptor:
ejbdescriptor -dump beandescriptor.ser
The idl2java
, java2idl
, and java2iiop
tools developed by Inprise for their VisiBroker for Java product (release 3.2) are distributed with Oracle8 i. The Oracle8 i JServer CD contains the documentation for these tools; the documentation can also be viewed or downloaded from http://www.inprise.com
. Because the Oracle8 i run-time environment differs somewhat from the VisiBroker environment, some VisiBroker tool options might not work in Oracle8 i JServer as they are described in the VisiBroker documentation. In particular, do not specify the -portable
option to idl2java
or java2iiop,
because because the current Oracle8 i ORB does not support DII.
This section describes special-purpose tools.
In the current JServer Enterprise JavaBeans implementation, EJBs communicate with clients by RMI-over-IIOP. This presents a difficulty for a CORBA client that wants to pass an object to an EJB for the EJB to invoke (call back) because the CORBA transport is IIOP, not RMI-over-IIOP. The CORBA client needs to pass the EJB an object the EJB can invoke with RMI-over-IIOP. The java2rmi_iiop
tool generates the stubs, skeletons, and other classes a client or server needs to make an object remotely invocable by an EJB. (java2rmi_iiop
is the analog of the VisiBroker for Java java2iiop
tool, except that it expects interfaces that extend java.rmi.Remote
rather than org.omg.CORBA.Object
)
The Java interface definitions must follow the RMI spec:
java.rmi.Remote.
java.rmi.RemoteException.
java2rmi_iiop [options] <file>.java ... [-no_bind] [-no_comments] [-no_examples] [-no_tie] [-root_dir <directory>] [-verbose] [-version] [-W <number>] [-wide]
Table 6-17 summarizes the java2rmi_iiop
arguments.
Generate RMI-over-IIOP class files for an RMI interface:
java2rmi_iiop Dictionary.java
Some aspects of the Oracle8 i ORB are governed by properties it reads when a new session running the ORB starts. You can change these properties with the modifyprops
tool. Developers should change ORB properties only when Oracle technical support provides instructions to do so.
modifyprops {-u | -user} <user/password@<database> [options] {<key> <value> [,<key> <value>] ... | <key> -delete} [{-o | -oci8}] [{-t | -thin}]
Table 6-18 summarizes the modifyprops
arguments.
Argument | Description |
---|---|
|
Specifies a user, password, and optional database connect string. See "user" for details. |
|
Directs |
|
Directs |
<key> <value> |
Oracle technical support will advise you of the values to enter for |
The permissible forms of @<database>
depend on whether you specify -oci8
or -thin
; -oci8
is the default.
-oci8
: @<database>
is optional. If you do not specify, then modifyprops
uses the user's default database. If specified, then <database>
can be a TNS name or a Net8 name-value list.
-thin
: @<database>
is required. The format is <host>:<lport>:<SID>
.