Session Namespace Tools

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:

• Schema Object Name: the name of the Java class schema object associated with the PublishedObject

• Schema: the name of the schema containing the corresponding class schema object

• Helper Schema Object Name: the name of the helper class the Oracle8 i ORB uses to automatically narrow a reference to an instance of the CORBA object or EJB.

PublishedObjects and PublishingContexts, like 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-4 describes session namespace rights.

Table 6-4 PublishingContext and PublishedObject Rights

Oracle8 i creates a session namespace automatically when the Oracle8 i ORB is configured. The PublishingContexts contained in Table 6-5 are present in all session namespaces:

Table 6-5 Initial PublishingContexts and Rights

Because by default only /test is writable by PUBLIC, you will normally create PublishingContexts and PublishedObjects subordinate to /test.

publish

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.

Syntax

publish <name> <class> [<helper>] -user <username> -password <password>
-service <serviceURL> [options]
  [-describe] 
  [{-g | -grant} {<user> | <role>}[,{<user> | <role>}]...]
  [{-h | -help}] 
  [-iiop]
  [-role <role>] 
  [-republish]
  [-schema <schema>]
  [-ssl]
  [-version] 

Argument Summary

Table 6-6 summarizes the publish tool arguments.

Table 6-6 publish Tool Argument Summary

sess_iiop://<host>:<lport>:<sid>. 

sess_iiop://localhost:2481:orcl

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 

remove

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.

Syntax

remove <name> -user <username> -password <password> -service <serviceURL> 
[options]
  [{-d | -describe}]
  [{-h | -help}]
  [-iiop]
  [{-r | -recurse}]
  [-role role]
  [-ssl]
  [-version]

Argument Summary

Table 6-7 describes the remove arguments.

Table 6-7 remove Argument Summary

sess_iiop://<host>:<lport>:<sid>. 

sess_iiop://localhost:2481:orcl

Here are examples of remove tool usage.

• Remove a PublishedObject named /test/testhello:

  remove /test/testhello -user SCOTT -password TIGER \ 
  -service sess_iiop://dlsun164:2481:orcl 
      
  
           

• Remove a PublishingContext named /test/etrader:

  remove -r /test/etrader -user SCOTT -password TIGER \ 
  -service sess_iiop://dlsun164:2481:orcl 
  

sess_sh

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.

Syntax

sess_sh [options] -user <user> -password <password> -service <serviceURL>
  [-d | -describe]
  [-h | -help] 
  [-iiop]
  [-role <rolename>]
  [-ssl]
  [-version]

Argument Summary

Table 6-8 summarizes the sess_sh arguments.

Table 6-8 sess_sh Argument Summary

sess_iiop://<host>:<lport>:<sid>. 

sess_iiop://localhost:2481:orcl

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

cd Command

The cd command is analogous to a Unix shell's cd command; it changes the working PublishingContext.

Syntax

cd [path] 

Here is an example.

Change to root PublishingContext:

$ cd /

chmod Command

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-4 for descriptions of the read, write, and execute rights. Only the object's owner can change its rights.

Syntax

chmod  [options] {+|-}{r|w|e} {<user> | <role>} [, {<user> | <role>} ...] \
<objectname>
  [-h | -help] 
  [-version] 

Argument Summary

Table 6-9 summarizes the chmod arguments.

Table 6-9 chmod Argument Summary

Here are some chmod examples.

• Give execute rights for /alpha/beta/gamma to Scott and Nancy:

  $ chmod +x scott nancy /alpha/beta/gamma
      
  
           

• Remove Scott's write rights for the same object:

  $ chmod -w scott /alpha/beta/gamma
  

chown Command

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.

Syntax

chown [options] {<user> | <role>} <objectname>
  [-h | -help] 
  [-version] 

Argument Summary

Table 6-10 summarizes the chown arguments.

Table 6-10 chown Argument Summary

Here is a chown example.

Make Scott the owner of /alpha/beta/gamma:

$ chown scott /alpha/beta/gamma

exit Command

The exit command terminates sess_sh.

Syntax

exit

Here is an example:

Leave the session shell:

$ exit
% 

help Command

The help command summarizes the syntax of the session shell commands.

Syntax

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

java Command

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 (see "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.)

Syntax

java class [arg1 ... argn] [options]
  [{-h | -help}] 
  [-schema <schema>]
  [-version] 

Argument Summary

Table 6-11 summarizes the java arguments.

Table 6-11 java Argument Summary

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
$

lcd Command

The lcd (local cd) command changes the local working directory just as executing cd outside of the session shell would.

Syntax

lcd [path]

Here is an example of the lcd command.

Change the file system directory to alpha/beta:

$ lcd alpha/beta

lls Command

The lls (local ls) command lists the contents of the working directory, just as executing ls outside of the session shell would.

Syntax

lls 
  [-l] 
  [<path>] 

Argument Summary

Table 6-12 summarizes the lls command's arguments.

Table 6-12 lls Argument Summary

Here is an lls command example.

List the working file system directory in long format:

$ lls -l

ln Command

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.

Syntax

ln <object> <link>

Argument Summary

Table 6-13 summarizes the ln arguments.

Table 6-13 ln Argument Summary

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

lpwd Command

The lpwd (local print working directory) command displays the name of the working directory, just as executing pwd outside of the session shell would.

Syntax

lpwd

Here is an example of the lpwd command that shows the working directory:

$ lpwd
/home/usr/billc

ls Command

The ls (list) command shows the contents of PublishingContexts as the Unix ls command shows the contents of directories.

Syntax

ls [options] [{<pubcon> | <pubobj} [{<pubcon> | <pubobj}] ...] 
  [-dir]
  [-h | -help]
  [-l] 
  [-ld | ldir]
  [-R]
  [-version] 

Argument Summary

Table 6-14 describes the ls arguments.

Table 6-14 ls Argument Summary

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 

mkdir Command

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.

Syntax

mkdir [options] <name>
 [-path] 

Argument Summary

Table 6-15 describes the mkdir arguments.

Table 6-15 mkdir Argument Summary

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

mv Command

The mv command is analogous to the Unix shell mv command.

Syntax

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

publish Command

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.

Syntax

publish <name> <class> <helper> [options] 
  [{-e | -executable}] 
  [{-g | -grant} {<user> | <role>}[,{<user> | <role>} ... ]]
  [{-h | -help}] 
  [-republish] 
  [-schema <schema>]
  [-version] 

Argument Summary

Table 6-16 summarizes the publish command arguments.

Table 6-16 publish Command Argument Summary

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 
    

            

pwd Command

The pwd command displays the name of the current working PublishingContext. It is analogous to the Unix pwd command.

Syntax

pwd

Here is an example of the pwd command.

$ pwd
/test/alpha

rm Command

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.

Syntax

rm [options] <object> ... <object>
  [{-h | -help}] 
  [-r]
  [-version] 

Argument Summary

Table 6-17 describes the rm arguments.

Table 6-17 rm Argument Summary

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

version Command

The version command shows the version of the sess_sh tool.

Syntax

version

Here is an example of the version command.

Display the session shell's version:

$ version
1.0