Oracle8i Java Tools Reference Release 3 (8.1.7) Part Number A83727-01 |
Library | Service | Contents | Index

## 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, 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 1-4 describes session namespace rights.

##### Table 1-4 PublishingContext and PublishedObject Rights

Right | Meaning for PublishingContext | Meaning for PublishedObject
--- | --- | ---
read | List contents and attributes (type, rights and creation time). | List object attributes (type, schema object, schema, helper, rights, and creation time).
write | Create a PublishedObject or PublishingContext in the PublishingContext. | Republish object.
execute | Use contents to resolve a name. | Activate associated class.

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

##### Table 1-5 Initial PublishingContexts and Rights

Name | Owner | Read | Write | Execute
--- | --- | --- | --- | ---
`/` | `SYS` | `PUBLIC` | `SYS` | `PUBLIC`
`/bin` | `SYS` | `PUBLIC` | `SYS` | `PUBLIC`
`/etc` | `SYS` | `PUBLIC` | `SYS` | `PUBLIC`
`/test` | `SYS` | `PUBLIC` | `PUBLIC` | `PUBLIC`

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

The following tools support publishing and managing objects in the namespace:

Note: These tools only support Release 8.1.7. A backward compatible version for these tools are documented in Chapter 2, "Backwards Compatibility Tools".

- publish

- remove

- sess_sh

### 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 permission for the PublishedObject.

Note: All supplied names are case sensitive. Thus, the schema, username, and password will not be uppercased.

#### Syntax

    publish [options] <name> <class> [<helper>]

    	-user | -u <username> -password |-p <password>

    	-service |-s <serviceURL>

where options are:

      [-describe | -d]
      [-g | -grant {<user> | <role>}[,{<user> | <role>}]...]
      [-recursiveGrant | -rg | -rG {<user> | <role>}[,{<user> | <role>}]...]
      [-h | -help]
      [-idl]
      [-iiop]
      [-replaceIDL]
      [-resolver]
      [-role <role>]
      [-republish]
      [-schema <schema>]
      [-ssl]
      [-useServiceName]
      [-version | -v]

Note: If you use the `publish` as a command within sess_sh, you do not supply the user, password, or service command-line arguments.

#### Argument Summary

Table 1-6 summarizes the `publish` tool arguments.

##### Table 1-6 publish Tool Argument Summary

Option | Description
--- | ---
`<name>` | Name of the PublishedObject being created or republished; PublishingContexts are created if necessary.
`<class>` | Name of the class schema object that corresponds to <name>.
`<helper>` | Name of the Java class schema object that implements the `narrow()` method for `<class>`.
`-user` | Specifies identity with which to log into the database instance named in `-service`.
`-password` | Specifies authenticating password for the username specified with `-user`.
`-service` | URL identifying database whose session namespace is to be "opened" by `sess_sh`. The serviceURL has the form:
    sess_iiop://<host>:<lport>:<sid>.
`<host>` is the computer that hosts the target database; `<lport>` is the listener port that has been configured to listen for session IIOP; `<sid>` is the database instance identifier. Example:
    sess_iiop://localhost:2481:orcl
which matches the default installation on the invoker's machine.
`-describe` | Summarizes the tool's operation.
`-grant` | After creating or republishing the PublishedObject, grants read and execute rights to the sequence of `<user>` and `<role>` names. When republishing, replace the existing users/roles that have read/execute rights with the `<user>` and `<role>` names. To selectively change the rights of a PublishedObject, use the `sess_sh`'s `chmod` command. Note that to activate a CORBA object or EJB, a user must have the execute right for both the PublishedObject and the corresponding class schema object. The sequence of user and role names must be a comma-separated list, containing no internal spaces. Note: You must uppercase the schema name.
`-recursiveGrant` | Grants read and execute permission in the same manner as the -grant option; but in addition to the designated object, it also grants these permissions to all contexts that the object exists within. If the context already has a permission level of SYS, the grant for that context is ignored. You can specify either -grant or -recursiveGrant.
`-help` | Summarizes the tool's syntax.
`-idl` | Load the IDL interface definition into the IFR.
`-iiop` | Connects to the target database with IIOP instead of the default session IIOP. Use this option when publishing to a database server that has been configured without session IIOP.
`-replaceIDL` | If an IDL interface definition currently exists within the IFR, replace it with this version. If not specified, the publish command will not replace the existing interface within the IFR. The -replaceIDL flag will replace any interface with the same name in the IFR, even if it was originally stored by another user. Thus, different users can overwrite another user's interface unknowingly.
`-republish` | Directs `publish` to replace an existing PublishedObject; without this option, the `publish` tool rejects an attempt to publish an existing name. If the PublishedObject does not exist, `publish` creates it. Republishing deletes non-owner rights; use the `-grant` option to add read/execute rights when republishing.
`-resolver` | Specifies an explicit resolver spec to store as part of the reference. The classloader uses this resolver spec for object activation. If -resolver is not specified, the default resolver spec, which includes current user's schema and PUBLIC, is used. See "resolver" for details. When activating the object, the ORB first tries to locate all classes using the resolver spec published with the object. If the required classes are not found, the ORB then uses the caller's resolver spec.
`-role` | Role to assume for the publish; no default.
`-schema` | The schema containing the Java <class> schema object. If you do not specify, the `publish` tool uses the invoker's schema.
`-ssl` | Connects to the database with SSL server authentication. You must have configured the database for SSL to use this option, and you must specify an SSL listener port in `-service`.
`-useServiceName` | If you are using a service name instead of an SID in the URL, you must specify this flag. Otherwise, the tool assumes the last string in the URL is the SID.
`-version` | Shows the tool's version.

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 BankTestServer.AccountManagerImpl \
    BankTestServer.AccountManagerHelper \
    -user SCOTT -password TIGER \
    -service sess_iiop://dlsun164:2481:orcl

##### IDL Restrictions

The following are the restrictions when using the IDL options for publish:

1. You store the IDL interface definition within the IFR through the Oracle8i JServer `publish` command. The `publish` command stores the interface within a flat file, `AuroraIFR.idl`. Normally, this file is automatically written to `$ORACLE_HOME/javavm/admin`. However, if this directory is not write-enabled, you can specify another fully-qualified filename within the "`aurora.ifr.file`" system property through the modifyprops tool, as follows:

       modifyprops -user SCOTT/TIGER@dbhost:5521:orcl

                   "aurora.ifr.file" "/private/ifr/myIFRfile"

2. The `-replaceIDL` flag will replace any interface with the same name in the IFR, even if it was originally stored by another user. Thus, different users can overwrite another user's interface unknowingly.

3. Once you have stored the interface in the IFR, there is no method for removing it. This file will continue to grow until you delete the entire file.

### 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.

Note: This tool is more extensive than the `rm` command. It removes the PublishedObject or PublishingContext from the namespace and any related IFR interfaces. The `rm` command solely removes an entity from within the directory.

##### Syntax

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

##### Argument Summary

Table 1-7 describes the `remove` arguments.

##### Table 1-7 remove Argument Summary

Option | Description
--- | ---
`<name>` | Name of PublishingContext or PublishedObject to be removed.
`-user` | Specifies identity with which to log into the instance named in -service.
`-password` | Specifies authenticating password for the `<username>` you specified with `-user`.
`-service` | URL identifying database whose session namespace is to be "opened" by `sess_sh`. The serviceURL has the form:
    sess_iiop://<host>:<lport>:<sid>.
`<host>` is the computer that hosts the target database; `<lport>` is the listener port that has been configured to listen for session IIOP; `<sid>` is the database instance identifier. Example:
    sess_iiop://localhost:2481:orcl
which matches the default installation on the invoker's machine.
`-describe` | Summarizes the tool's operation.
`-help` | Summarizes the tool's syntax.
`-iiop` | Connects to the target database with IIOP instead of the default session IIOP. Use this option when removing from a database server that has been configured without session IIOP.
`-recurse` | Recursively removes `<name>` and all subordinate PublishingContexts; required to remove a PublishingContext.
`-role` | Role to assume for the remove; no default.
`-ssl` | Connects to the database with SSL server authentication. You must have configured the database for SSL to use this option.
`-useServiceName` | If you are using a service name instead of an SID in the URL, you must specify this flag. Otherwise, the tool assumes the last string in the URL is the SID.
`-version` | Shows the tool's version.

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, that is, a class with a static `main()` method. Executables must have been loaded with `loadjava`, but not published--publishing is for CORBA, EJB, and servlet objects only.

#### Syntax

    sess_sh {-service | -s} <serviceURL> {-user | -u} <user>
            {-password  | -p} <password> [options]
      [@<filename>]
      [-batch]
      [-c | -command <command> <args>]
      [-credsFile <creds>]
      [-describe | -d]
      [-h | -help]
      [-iiop]
      [-proxy <host>:<port>]
      [-role <rolename>]
      [-ssl]
      [-useServiceName]
      [-version | -v]

#### Argument Summary

Table 1-8 summarizes the `sess_sh` command-line arguments.

##### Table 1-8 sess_sh Argument Summary

Option | Description
--- | ---
`-service | -s` | URL identifying database whose session namespace is to be "opened" by `sess_sh`. The serviceURL should contain one of the following:
    sess_iiop://<host>:<lport>:<sid>
    jdbc:oracle:<type>:<spec>
    http://<host>:<lport>
`<``host``>` is the computer that hosts the target database; `<``lport``>` is the listener port configured to listen for session IIOP or HTTP `<``sid``>` is the database instance identifier. <`type`> can be either `oci8` or `thin <``spec``>` is the connect string, alias, or URL for the JDBC driver Examples:
    sess_iiop://localhost:2481:orcl
    jdbc:oracle:thin:@dbhost:5521:ORCL
    http://localhost:2481
`-user | -u` | Specifies user's name for connecting to the database. This name case insensitive; the name will always be uppercased.
`-password | -p` | Specifies user's password for connecting to the database. This name case insensitive; the name will always be uppercased.
`@<filename>` | Specifies a script file that contains sess_sh commands to be executed. See "Scripting sess_sh Commands in the @<filename> Option" for structure of the indicated file.
`-batch` | Disables all messages printed to the screen. No help messages or prompts will be printed. Only responses to entered commands are printed.
`-command` | Executes the desired command. If you do not want to run sess_sh in interpretive mode, but only want to execute a single command, execute sess_sh with the -command option followed by a string that contains the command and the arguments. Once the command executes, sess_sh exits. The following executes the "ls -lR" command on the designated host: sess_sh -user SCOTT -password TIGER -service sess_iiop://dbserver:2481:orcl -command "ls -lR"
`-credsFile` | Supply a text file with credentials instead of a username and password for the connect. You create this file by exporting a wallet into a text version.
`-describe | -d` | Summarizes the tool's operation.
`-echo` | Prints out every command before execution. This is useful when executing script files.
`-help` | Summarizes the tool's syntax.
`-iiop` | Connects to the target database with plain IIOP instead of the default session IIOP. Use this option for a database server configured without session IIOP.
`-proxy` | Specifies the proxy host and port number. This is only required if you are using a firewall proxy to communicate with hosts outside your internal network.
`-role` | Role to pass to database; there is no default.
`-ssl` | Connect to the database with SSL server authentication. You must have configured the database for SSL and specify an SSL port to use this option.
`-useServiceName` | If you are using a service name instead of an SID in the URL, you must specify this flag. Otherwise, the tool assumes the last string in the URL is the SID. Alternatively, you can specify USE_SERVICE_NAME in the JNDI properties instead of using this option. See the "JNDI Connections and Session IIOP Service" chapter in either the Oracle8i CORBA or EJB Developer's Guides for more information.
`-version` | Shows the version.

##### Example

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 `sess_sh` commands span several different types of functionality, which are grouped as follows:

- sess_sh Options--describes the options for the `sess_sh` command-line tool

- Shell Commands--describes the commands that are used for manipulating and viewing contexts and objects in the namespace

- Namespace Commands--describes the commands that bind objects, manage namespace groups, and set object properties. This includes binding the UserTransaction and DataSource objects.

- Dynamic Listener Endpoint Configuration Commands--describes commands for adding endpoints to existing listeners

- Web Application Management Commands--describes commands used for managing web applications, such as servlets and Java Server Pages.

#### sess_sh Options

- sess_sh Tool Output Redirection

- Scripting sess_sh Commands in the @<filename> Option

##### sess_sh Tool Output Redirection

You can specify that any output generated by the sess_sh tool is put into a file by appending the "`&><``filename``>`" at the end of the command options. The following pipes all output to the `listDir` file:

    ls -lR &>/tmp/listDir

##### Scripting sess_sh Commands in the @<filename> Option

This option designates a script file that contains one or more `sess_sh` commands. The script file specified is located on the client. The `sess_sh` tool reads in the file and then executes all commands on the designated server. Also, since the script file is executed on the server, any interaction with the operating system in the script file--such as redirecting output to a file or executing another script--will occur on the server. If you direct sess_sh to execute another script file, this file must exist within $ORACLE_HOME directory on the server.

You simply type in the `sess_sh` command followed by any options an any expected input arguments.

The script file contains any `sess_sh` command followed by options and input parameters. The input parameters can be passed in on the `sess_sh` command line. The sess_sh command processes all known `sess_sh` options and then passes on any other options and arguments to the script file.

To access arguments within the commands in the script file, place &1...&n to denote the arguments. If all input parameters are passed into a single command, you can supply a the string "&*" to denote that all input parameters are to be passed to this command.

The following shows the contents of the script file, `execShell`:

    chmod +x SCOTT nancy /alpha/beta/gamma
    chown SCOTT /alpha/beta/gamma
    java testhello &*

Since only two input arguments are expected, you could have also implemented the `java` command input parameters as follows:

    java testhello &1 &2

Note: You can also supply arguments to the -`command` option in the same manner. The following shows an example:
    sess_sh ... -command "cd &1" contexts
After processing all other options, the `sess_sh` tool passes "contexts" in as the argument to the "cd" command.

To execute this file, do the following:

    sess_sh -user SCOTT -password TIGER -service sess_iiop://dbserver:2481:orcl \
            @execShell alpha beta

The `sess_sh` processes all options that it knows about and passes along any other input parameters to be used by the commands that exist within the script file. In this example, the parameters, `alpha` and `beta`, are passed to the `java` command in the script file. Thus, the actual command executed is as follows:

    java testhello alpha beta

You can add any comments in your script file with the hash symbol (#). The "#" symbol makes anything to the end of the line a comment, which is ignored by `sess_sh`. For example:

    #this whole line is ignored by sess_sh

### Shell Commands

The following shell commands behave similarly to their UNIX counterparts:

alias | cd | chmod
chown | connect | echo
env | exit | help
java | ln | ls
mkdir | mv | pwd
rm | setenv | version
whoami |  |

Each of these shell commands contains the following common options:

##### Table 1-9 sess_sh Command Common Options

Option | Description
--- | ---
`-describe | -d` | Summarizes the tool's operation.
`-help | -h` | Summarizes the tool's syntax.
`-version` | Shows the version.

#### alias

You can create an alias used within the script file. You can specify multiple aliases. The definition can include several commands separated on different lines. The entire definition is included within double quotes.

The syntax is as follows:

    alias <name> <definition>

where the `<``name``>` is the alias and `<``definition``>` is any `sess_sh` command. For example, the following creates an alias of "`ll`" to be mapped to "`ls -l &*`"

    alias ll "ls -l &*"

Thus, the command for "`ll bin webdomains`" is translated to "`ls -l bin webdomains`".

To echo an alias, execute alias with just the `<name>` and no `<description>`.

To delete an alias, execute alias with the empty string, as follows:

    alias <name> ""

#### cd

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

##### Syntax

    cd [options] [path]

Here is an example.

Change to root PublishingContext:

    $ cd /

#### chmod

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

Note: All names are case sensitive. Thus, the schema, username, and password will not be uppercased.

##### Syntax

    chmod [options] {+|-}{r|w|x} {<user> | <role>} [, {<user> | <role>} ...]
                                 <objectname>
          [-R]

##### Argument Summary

Table 1-10 summarizes the `chmod` arguments.

##### Table 1-10 chmod Argument Summary

Option | Description
--- | ---
`+/-rwx` | Specifies the right (read, write, or execute) to be added (`+`) or removed (`-`) for `<user>` or `<role>`.
`<user> | <role>` | Specifies the user or role whose rights are to be increased or decreased. This value is case sensitive.
`<objectname>` | Specifies the name of the PublishingContext or PublishedObject whose rights are to be changed.
`-R` | Changes the execute rights recursively. This does not include symbolic links.

Here are some chmod examples.

- Give execute rights for `/alpha/beta/gamma` to SCOTT and NANCY. Note that the schemas are separated by a comma only.

      $ chmod +x SCOTT,NANCY /alpha/beta/gamma

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

      $ chmod -w SCOTT /alpha/beta/gamma

#### chown

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>
          [-R]

##### Argument Summary

Table 1-11 summarizes the `chown` arguments.

##### Table 1-11 chown Argument Summary

Option | Description
--- | ---
`<user> | <role>` | Specifies the user or role to be the new owner.
`<objectname>` | Specifies the name of the PublishingContext or PublishedObject whose owner is to be changed.
`-R` | Changes the ownership recursively. This does not include symbolic links.

Here is a `chown` example.

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

    $ chown SCOTT /alpha/beta/gamma

#### connect

The `connect` tool will connect you to another server without exiting `sess_sh`. It requires the same connection options used in sess_sh. The options for `connect` are as follows:

    connect [-options] {-user | -u} <user> {-password  | -p} <password>
                       {-service | -s} <serviceURL>
      [-credsFile <creds>]
      [-iiop]
      [-proxy <host>:<port>]
      [-role <rolename>]
      [-ssl]
      [-useServiceName]

#### Argument Summary

Table 1-8 summarizes the `connect` command-line arguments.

##### Table 1-12 connect Argument Summary

Option | Description
--- | ---
`-service | -s` | URL identifying database whose session namespace is to be "opened" by `sess_sh`. The serviceURL should contain one of the following:
    sess_iiop://<host>:<lport>:<sid>
    jdbc:oracle:<type>:<spec>
    http://<host>:<lport>
`<``host``>` is the computer that hosts the target database; `<``lport``>` is the listener port configured to listen for session IIOP or HTTP `<``sid``>` is the database instance identifier. <`type`> can be either `oci8` or `thin <``spec``>` is the connect string, alias, or URL for the JDBC driver Examples:
    sess_iiop://localhost:2481:orcl
    jdbc:oracle:thin:@dbhost:5521:ORCL
    http://localhost:2481
`-user | -u` | Specifies user's name for connecting to the database. This name case insensitive; the name will always be uppercased.
`-password | -p` | Specifies user's password for connecting to the database. This name case insensitive; the name will always be uppercased.
`-credsFile` | Supply a text file with credentials instead of a username and password for the connect. You create this file by exporting a wallet into a text version.
`-iiop` | Connects to the target database with plain IIOP instead of the default session IIOP. Use this option for a database server configured without session IIOP.
`-proxy` | Specifies the proxy host and port number. This is only required if you are using a firewall proxy to communicate with hosts outside your internal network.
`-role` | Role to pass to database; there is no default.
`-ssl` | Connect to the database with SSL server authentication. You must have configured the database for SSL and specify an SSL port to use this option.
`-useServiceName` | If you are using a service name instead of an SID in the URL, you must specify this flag. Otherwise, the tool assumes the last string in the URL is the SID. Alternatively, you can specify USE_SERVICE_NAME in the JNDI properties instead of using this option. See the "JNDI Connections and Session IIOP Service" chapter in either the Oracle8i CORBA or EJB Developer's Guides for more information.

Examples for using connect are as follows:

Connect to an IIOP session:

    connect -u scott/tiger -s sess_iiop://mysun:5522:ORCL

Connect to an HTTP SSL session through a firewall:

    connect -u scott/tiger -s https://mysun:9090 -proxy companyx-proxy:2443

#### echo

Prints to stdout exactly what is indicated. This is used mostly in script files.

The syntax is as follows:

    echo [<echo_string>] [<args>]

where `<echo_string>` is a string that contains the text you want written to the screen during the shell script invocation and <`args`> are input arguments from the user. For example, the following prints out a notification:

    echo "Adding an owner to the schema" &1

If the input argument is "SCOTT", the output would be "Adding an owner to the schema SCOTT"

#### env

You can view environment variables and their values with the `env` command.

##### Syntax

    env [<variable>]

##### Argument Summary

Table 1-13 describes the `env` arguments.

##### Table 1-13 env Argument Summary

Option | Description
--- | ---
`<variable>` | The name of the environment variable. If not provided, all variables are printed.

The following example prints out the value of the TEST variable:

    $ env test
    TEST=HELLO

#### exit

The `exit` command terminates `sess_sh`.

##### Syntax

    exit

Here is an example:

Leave the session shell:

    $ exit
    %

#### help

The `help` command summarizes the syntax of the session shell commands. You can also use the `help` command to summarize the options for a particular command.

##### Syntax

    help [<command>]

#### java

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 privileges to read.)

##### Syntax

    java [-schema <schema>] <class> [arg1 ... argn]

##### Argument Summary

Table 1-14 summarizes the `java` arguments.

##### Table 1-14 java Argument Summary

Option | Description
--- | ---
`class` | Names the Java class schema object that is to be executed.
`-schema` | Names the schema containing the class to be executed; the default is the invoker's schema. The schema name is case sensitive.
`arg1 ... argn` | Arguments to the class's `main()` method.

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

#### ln

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"); creating a link with the old name makes the object accessible by both its old and new names.

##### Syntax

    ln [-symbolic | -s] <object> <link>

##### Argument Summary

Table 1-15 summarizes the `ln` arguments.

##### Table 1-15 ln Argument Summary

Option | Description
--- | ---
`-s` | Create a symbolic soft link for the <object> of the <link> name.
`<object>` | The name of the PublishingContext or PublishedObject for which a link is to be created.
`<link>` | The synonym by which `<object>` is also to be known.

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

#### ls

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]
      [-l]
      [-ld | ldir]
      [-R]

##### Argument Summary

Table 1-16 describes the `ls` arguments.

##### Table 1-16 ls Argument Summary

Option | Description
--- | ---
`<pubcon> | <pubobj>` | Name of PublishingContext(s) and/or PublishingObject(s) to be listed; the default is the working PublishingContext.
`-dir` | Shows only PublishingContexts; analogous to the UNIX `ls` `-d` command.
`-l` | Shows contents in long (detailed) format. The long format includes name, creation time, owner, and rights. For PublishedObjects, the option also shows class, schema, and helper. You can use this option in conjunction with -R, as -lR or -Rl.
`-ldir` | Lists PublishingContexts in long format, ignoring PublishingObjects; analogous to UNIX `ls` `-ld` command.
`-R` | Lists recursively. You can use this option in conjunction with -l, as -lR or -Rl.

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

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 | -p]

##### Argument Summary

Table 1-17 describes the `mkdir` arguments.

##### Table 1-17 mkdir Argument Summary

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

#### mv

The `mv` command is analogous to the UNIX shell `mv` command.

##### Syntax

    mv [options] <old> <new>

Here is an example of the `mv` command.

Change the name of `/test/foo` to `/test/bar`:

    $ mv /test/foo /test/bar

#### pwd

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

##### Syntax

`pwd` [options]

Here is an example of the `pwd` command.

    $ pwd
    /test/alpha

#### rm

The `rm` command is analogous to the `rm -r` UNIX shell command; 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>
       [-r]

##### Argument Summary

Table 1-18 describes the `rm` arguments.

##### Table 1-18 rm Argument Summary

Option | Description
--- | ---
`<object>` | Name of PublishedObject or PublishingContext to be removed.
`-r | -recurse` | Interprets `<object>` as a PublishingContext; removes it and its contents recursively.

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

#### setenv

You can set environment variables within a script or for use within the current invocation of the sess_sh tool. These variables are not valid outside of sess_sh and are lost when sess_sh terminates.

##### Syntax

    setenv <variable> <value>

##### Argument Summary

Table 1-19 describes the `setenv` arguments.

##### Table 1-19 setenv Argument Summary

Option | Description
--- | ---
`<variable>` | The name of the environment variable.
`<value>` | The value to set the environment variable to. If no value is given, the defined <variable> is removed.

The following example sets the TEST variable to the string HELLO. Once set, the value is shown with the `env` command.

    $ setenv TEST HELLO
    $ setenv PATH .:/bin:/test/bin
    $ env test
    TEST=HELLO
    PATH=.:/bin:/test/bin

To remove an environment variable, set the variable to the NULL string. The following removes the TEST variable:

    $ setenv TEST ""

#### version

The `version` command shows the version of the `sess_sh` tool. You can also show the version of a specified command.

##### Syntax

    version [options] [<command>]

Here is an example of the `version` command.

Display the session shell's version:

    $ version
    1.0

#### whoami

Prints out the current user that logged into this session.

### Namespace Commands

addgroupentry | bind | bindut
bindds | getgroup | getproperties
publish | removegroupentry | setgroup
setproperties |  |

#### addgroupentry

The `addgroupentry` command adds a single property to an existing property group for the designated JNDI object.

##### Syntax

    addgroupentry <object_name> <group_name> <prop_name> <prop_value>

##### Table 1-20 addgroupentry Command Options

Option | Description
--- | ---
`<object_name>` | A JNDI name that is bound to an object.
`<group_name>` | A property group name, which was created by the setgroup command.
`<prop_name>` | The property name assigned to the group/object.
`<prop_value>` | The value for the property

The following example sets another property for the `wine` group of the `config` object:

addgroupentry config wine type merlot

#### bind

The `bind` command binds an object reference or a naming context into the JNDI namespace. The ordering of the options must be in the order specified here. You cannot mix the options.

##### Syntax

    bind <JNDI_object_name> [options]
       [-context]
       [-rebind]
       {-class | -c <classname>
       [-factory | -f <factory>]
       [-location | -l <URL>]
       [-string <type_name> <string_value> [-string <type_name> <string_value> ...]]
       [-binary <type_name> <string_value> [-binary <type_name> <string_value> ...]]

##### Table 1-21 bind Command Options

Option | Description
--- | ---
`<JNDI_object_name>` | The JNDI name that the object is bound to within the namespace. This is the name that is used to retrieve the bound object.
`-context` | The object to be bound is a JNDI Context or InitialContext.
`-rebind` | If the JNDI name already exists, replace the object that it is bound to with this object.
`-class` | Specify the class name of the bound object.
`-factory` | Specify the factory name for creating the object. JNDI uses this for creating the object.
`-location` | Specify the factory location if the default location is not used. This takes a JNDI URL. Refer to the JNDI specification for more information.
`-string` | Specify a String reference attribute for the object by the type name and value.
`-binary` | Specify a Binary reference attribute for the object by the type and a binary value. The given string value is converted into binary.

The following binds a CORBA IOR reference into the JNDI namespace. The object reference was stringified before the `bind` is executed and is substituted for the input argument $1. In addition, a binary reference attribute for the employee site number of 400 is also bound within the object.

    bind /test/employee -class employee.Employee -factory employee.EmployeeFactory

    	-string EmpObjRef $1 -binary EmpNumber 400

#### bindut

The `bindut` command binds a `UserTransaction` object in the namespace. You must bind a `UserTransaction` object for both single and two-phase commit transactions. In a two-phase commit scenario, the `UserTransaction` is bound with respect to the two-phase commit engine.

Note: If you change the two-phase commit engine, you must update all database links on all `DataSource` objects involved in the transaction, and rebind the `UserTransaction`.

##### Syntax

    bindut <lookup_name> [options]

           [-help | -h]

           [-describe | -d]

           [-version | -v]

           [-rebind]

           [-expprop]

           [-host <hostname> -port <portnum> -sid <SID>]

           [-url <db_url>]

           [-g | -grant {<user> | <role>}[,{<user> | <role>}]...]

           [-recursiveGrant | -rg | -rG {<user> | <role>}[,{<user> | <role>}]...]

           [-user | -u <user>]

           [-password | -p <password>]

##### Argument Summary

Table 1-22 summarizes the `bindut` command-line arguments:

##### Table 1-22 bindut Argument Summary

Option | Description
--- | ---
`<lookup_name>` | The JNDI name of the UserTransaction object
`-help` | Summarizes the tool's syntax.
`-describe` | Summarizes the tool's operation.
`-version` | Shows the tool's version.
`-rebind` | If the JNDI name for the UserTransaction object already exists, you must specify this option if you want it overwritten with this new object. Otherwise, no bind will occur for this option and an AlreadyBound exception is thrown.
`-expprop` | Specify this option only if host/port/sid options are specified. Designates how the transaction is propagated between objects. If an IIOP client invokes an IIOP server method, the transaction context is propagated implicitly for you. However, if your client uses JDBC or HTTP for communicating, the propagation context must be propagated explicitly. Specify this flag in the case of JDBC or HTTP communication.
`-host <host> -port <port> -sid <sid>` | These options specify the Oracle8i database that is acting as the two-phase commit engine. These are only necessary for any global transactions that use two-phase commit. You can either specify the two-phase commit engine location either through these options or within the -url option. The default value for -sid is ORCL.
`-url <db_url>` | This URL specifies the location of the Oracle8i database that is acting as the two-phase commit engine. You can specify the two-phase commit engine either through this option or by specifying each part of the URL separately within the four options mentioned above. This URL can be either JDBC Thin or sess_iiop URL.
`-grant <user> | <role>` | Grants read and execute rights to the sequence of <user> and <role> names. When rebinding any leaf nodes, replace the existing users/roles that have read/execute rights with the <user> and <role> names. To selectively change the rights of a UserTransaction object, use the sess_sh's chmod command. The sequence of user and role names must be a comma-separated list, containing no internal spaces. Note: You must uppercase the schema name.
`-recursiveGrant <user> | <role>` | Grants read and execute permission like the -grant option to the designated object and to all contexts that the object exists within. If the context has a permission level of SYS, the grant for that context is ignored. You can specify either -grant or -recursiveGrant.
`-user | -u <user>` | Specifies user's name for connecting to the two-phase commit engine. This option is only required for two-phase commit scenario.
`-password | -p <password>` | Specifies user's password for connecting to the two-phase commit engine. This option is only required for two-phase commit scenario.

##### Example

The following example binds the `ut1` `UserTransaction` within the namespace designating the two-phase commit engine at `dbsun.mycompany.com`:

    bindut /test/UserTransaction/ut1 -host dbsun.mycompany.com -port 2481 -sid ORCL

The same command could be issued as follows:

    bindut /test/UserTransaction/ut1 -url sess_iiop://dbsun.mycompany.com:2481:ORCL

The options used to bind a `UserTransaction` object depend on whether the transaction uses single or two-phase commit, as described below:

- Single-phase commit--provide the JNDI bound name for the `UserTransaction` object. You do not need to provide the address to a two-phase commit engine. For example, the following binds a `UserTransaction` with the name of "`/test/myUT`" that exists for a single-phase commit transaction:

      bindut /test/myUT

- Two-phase commit--provide the JNDI bound name for the `UserTransaction` object and the address to a two-phase commit engine. For example, the following binds a `UserTransaction` with the name of "`/test/myUT`" and a two-phase commit engine at "`2pcHost`":

      bindut /test/myUT -url jdbc:oracle:thin:@2pcHost:5521:ORCL

  When the transaction commits, the `UserTransaction` communicates with the two-phase engine designated in the -`url` option to commit all changes to all included databases. The `UserTransaction` tracks all databases involved in the transaction; the two-phase commit engine uses the database links for these databases to complete the transaction.

#### bindds

The `bindds` command binds a `DataSource` object in the JNDI namespace. In order to enlist any database--including the local database--you must bind a JTA `DataSource` object to identify each database included in the transaction. If you require a two-phase commit transaction, your system administrator must create public database links from the two-phase commit engine to each database involved in the transaction. These database link names are included when binding `DataSource` objects.

Note: If you change the two-phase commit engine, you must update all database links on all `DataSource` objects involved in the transaction, and rebind the `UserTransaction`.

For JTA, XA, or JNDI, you might need to bind a `DataSource` object in the JNDI namespace for later retrieval and activation of a database connection. There are four types of `DataSource` objects that you can bind using the `bindds` command.

- `OracleDataSource`--a `DataSource` object modified for use with an Oracle8i database.

- `OracleJTADataSource`--a `DataSource` object modified for use within global JTA transactions. Within JTA, in order to enlist any database--including the local database--you must bind an `OracleJTADataSource` object to identify each database included in the transaction.

- `OracleConnectionPoolDataSource`--a `DataSource` object modified for use with a pool of `DataSource` objects.

- `OracleXADataSource`--a `DataSource` object modified for use within an XA-type connection.

The `DataSource` object type is specified with the -`dstype` option of the `bindds` command, as described below:

##### Syntax

    bindds <lookup_name> [options]

           [-help | -h]

           [-describe | -d]

           [-version | -v]

           [-dstype <datasource>]

           [-host <hostname> -port <portnum> -sid <SID> -driver <driver_type>]

           [-url <db_url>]

           [-dblink <DBLINK>]

           [-g | -grant {<user> | <role>}[,{<user> | <role>}]...]

           [-recursiveGrant | -rg {<user> | <role>}[,{<user> | <role>}]...]

           [-rebind]

           [-user | -u <user>]

           [-password | -p <password>]

##### Argument Summary

Table 1-23 summarizes the `bindds` command-line arguments:

##### Table 1-23 bindds Argument Summary

Option | Description
--- | ---
`<lookup_name>` | The JNDI name of the DataSource object
`-help` | Summarizes the tool's syntax.
`-describe` | Summarizes the tool's operation.
`-version` | Shows the tool's version.
`-dstype <datasource>` | The type of DataSource object that you are currently binding. Values can be one of the following: do not specify this option to bind an OracleDataSource jta--OracleJTADataSource xa--OracleXADataSource pool--OracleConnectionPoolDataSource If you do not specify this option, the default is an OracleDataSource object.
`-host <host> -port <port> -sid <sid> -driver <drv_type>` | These options specify the location of the database and driver type for the connection to be established to the database. This information enables anyone retrieving this object to establish a connection to this database. You can alternatively specify this information within a URL format within the -url option. The default value for -sid is ORCL. Values for -driver can be thin, oci8, or kprb.
`-url <db_url>` | This JDBC URL specifies the location of the database. With this information bound within the DataSource object, a connection can be created to this database. Alternatively, you can specify this information within the four options mentioned above. You must specify a JDBC URL; an IIOP (sess_iiop) address is not permitted.
`-dblink <DBLINK>` | The fully-qualified database link, which must be previously configured by an administrator, from the two-phase commit engine to the database described by this DataSource object. This option is only necessary for two-phase commit transactions. The public database link must be previously created by a system administrator on the two-phase commit engine.
`-grant <user> | <role>` | Grants read and execute rights to the sequence of <user> and <role> names. When rebinding, replace the existing users/roles that have read/execute rights with the <user> and <role> names. To selectively change the rights of a DataSource, use the sess_sh's chmod command. The sequence of user and role names must be a comma-separated list, containing no internal spaces. Note: You must uppercase the schema name.
`-recursiveGrant <user> | <role>` | Grants read and execute permission like the -grant option to the designated object and to all contexts that the object exists within. If the context has a permission level of SYS, the grant for that context is ignored. You can specify either -grant or -recursiveGrant.
`-rebind` | If the DataSource object already exists, you must specify this option if you want it overwritten with this new object. Otherwise, no bind will occur for this option.
`-user | -u <user>` | Specifies user's name for connecting to the database. Stores the username within the DataSource object. If no username is supplied within the JNDI Context when creating the database connection, this username is used.
`-password | -p <password>` | Specifies user's password for connecting to the database. Stores the password within the DataSource object. If no password is supplied within the JNDI Context when creating the database connection, this username is used.

##### Binding an OracleJTADataSource Object

You bind an `OracleJTADataSource` object for any databases included in a global transaction. If you require a two-phase commit transaction, your system administrator must create public database links from the two-phase commit engine to each database involved in the transaction. These database link names must be included when binding the `OracleJTADataSource` object.

Note: In a two-phase commit scenario, the `DataSource` object is bound with respect to the two-phase commit engine. If you change the two-phase commit engine, you must update all database links, and rebind all concerned `DataSource` objects.

The following example binds the `ds1` `OracleJTADataSource` into the namespace with `ds1db` as the database link name created on the two-phase commit engine:

    % bindds /test/ds1 -host dbsun.mycompany.com -port 2481

    	-sid ORCL -driver thin -dstype jta -dblink ds1db.oracle.com

The options used to bind an `OracleJTADataSource` object depend on whether the transaction uses single or two-phase commit, as described below:

- Single-phase commit--provide the JNDI bound name and the URL address information for this database within the `OracleJTADataSource` object. You do not need to provide a database link. For example, the following binds an `OracleJTADataSource` with the name of "`/test/myUT`" that exists within a single-phase commit transaction:

      bindds /test/ds1 -host dbsun -port 5521 -sid ORCL -driver thin -dstype jta

- Two-phase commit--provide the JNDI bound name for the object, the URL for creating a connection to the database, and the database link from the two-phase commit engine to this database.

      bindds /test/myUT -url jdbc:oracle:thin:@dbsun:5521:ORCL -dstype jta

      	-dblink mydsdblink.oracle.com

  This includes not only the information for creating a connection to this database, but also the information needed by the two-phase commit engine to facilitate committing a global transaction.

#### getgroup

The `getgroup` command lists all of the properties within a property group for the designated JNDI object.

##### Syntax

    getgroup <object_name> <group_name>

##### Table 1-24 getgroup Command Options

Option | Description
--- | ---
`<object_name>` | A JNDI name that is bound to an object.
`<group_name>` | A property group name, which was created by the setgroup command.

The following example displays all properties defined for the `wine` group of the `config` object:

getgroup config wine

#### getproperties

The `getproperties` command lists all properties associated with the given JNDI name.

##### Syntax

    getproperties [-all] <object_name>

##### Table 1-25 getproperties Command Options

Option | Description
--- | ---
`-all` | Display all properties information including the reference information, such as the class, factory, and factory location.
`<object_name>` | A JNDI name that is bound to an object.

#### publish

The `publish` command performs the same function as the publish tool. Refer to "publish" for command syntax and examples.

#### removegroupentry

The `removegroupentry` command removes a single property to an existing property group for the designated JNDI object.

##### Syntax

    removegroupentry <object_name> <group_name> <prop_name>

##### Table 1-26 removegroupentry Command Options

Option | Description
--- | ---
`<object_name>` | A JNDI name that is bound to an object.
`<group_name>` | A property group name, which was created by the setgroup command.
`<prop_name>` | The property name assigned to the group/object.

The following example removes the `type` property from the `wine` group of the `config` object:

removegroupentry config wine type

#### setgroup

The `setgroup` command creates a property group for a JNDI object. You add properties to an existing group through the addgroupentry command. Each execution of `setgroup` either creates a new group or overwrites an existing group. To specify multiple properties, enclose all name-value pairs within double-quotes (") and separate each name-value pair with a newline.

##### Syntax

    setgroup <object_name> <group_name> "<prop_name=prop_value>
              [<prop_name=prop_value>...]"

##### Table 1-27 setgroup Command Options

Option | Description
--- | ---
`<object_name>` | A JNDI name that is bound to an object.
`<group_name>` | The property group name to be used for categorizing the given properties.
`<prop_name>` | The property name that has already been created with the setproperties command.
`<prop_value>` | The value for the property

The following example sets three properties for `wine` group in the `config` object:

    setgroup config wine "debug=true
    >servlet.class=SCOTT:winemasters.tasting.Tasting
    >details=high"

#### setproperties

The `setproperties` command assigns name-value pairs to an object with the given JNDI name. Each execution of `setproperties` resets all properties for this object to what is indicated on the command-line. To specify multiple properties, enclose all name-value pairs within double-quotes (") and separate each name-value pair with a newline.

##### Syntax

    setproperties <object_name> "<prop_name=prop_value>
              [<prop_name=prop_value>...]"

##### Table 1-28 setproperties Command Options

Option | Description
--- | ---
`<object_name>` | A JNDI name that is bound to an object.
`<prop_name>` | The name of the property.
`<prop_value>` | The current value for the property.

The following example sets three properties for the `config` object:

    setproperties config "debug=true
    >servlet.class=SCOTT:winemasters.tasting.Tasting
    >details=high"

### Dynamic Listener Endpoint Configuration Commands

The following sess_sh commands are provided to modify an existing listener.

- regep

- unregep

#### regep

In order to receive incoming requests, the listener must be configured with an endpoint for each presentation type. Most listeners are configured to accept Net8 (`TTC`) connections. The other two types of supported presentations are IIOP (`oracle.aurora.server.SGiopServer`) and HTTP (`HTTP://webserver`). In addition, if you create your own presentation, the listener must have an endpoint registered for that presentation.

You can either statically configure these endpoints within the listener configuration (either through the Net8 configuration tool or by modifying the listener configuration file) or dynamically register these endpoints through the `regep` tool.

The register endpoint (`regep`) command dynamically registers an endpoint within the existing listener for the specified presentation type. For example, you can modify a listener that exists primarily for TTC requests to also accept IIOP requests.

This tool requires you log on as a system user.

##### Syntax

    regep -pres <presentation_string> [-host <hostname>] -port <portnum>
          [-listener <lsnr_addr>]
          [-ssl]
          [-persistent]
          [-describe | -d]
          [-help | -h]
          [-version | -v]

##### Argument Summary

Table 1-29 summarizes the `regep` command-line arguments:

##### Table 1-29 regep Argument Summary

Option | Description
--- | ---
`-pres` | A presentation string. For IIOP requests, this string is "oracle.aurora.server.SGiopServer". For HTTP requests, this string is "`HTTP://webserver`"
`-host` | Specifies the hostname or IP address where the endpoint is to be registered. If you omit this option or supply "*" as the value, this endpoint will listen on all IP interfaces for the host. That is, you can connect using the IP address, the host name, or the localhost logical name. If you choose to listen on all IP interfaces, lsnrctl will return only one of these values.
`-port` | Specifies the port number for the endpoint. Must be a valid port number.
`-listener` | If specified, defines a listener with the specified address. The address equals the string given within the "address=" portion of the listener configuration string. If unspecified, the local listener is used.
`-ssl` | If specified, the endpoint is defined as an SSL endpoint.
`-persistent` | If specified, the endpoint is made persistent. The default is non-persistent. A persistent endpoint re-registers itself after the database has been restarted.
`-describe | -d` | Summarizes the tool's operation.
`-help | -h` | Summarizes the tool's syntax.
`-version | -v` | Shows the version.

#### unregep

The unregister endpoint (`unregep`) command unregisters an existing dynamic listener endpoint. This tool requires you log on as a system user.

##### Syntax

    unregep -pres <presentation_string> -host <hostname> -port <portnum>
          [-describe | -d]
          [-help | -h]
          [-version | -v]
          [-delete]

##### Argument Summary

Table 1-30 summarizes the `unregep` command-line arguments:

##### Table 1-30 unregep Argument Summary

Option | Description
--- | ---
`-pres` | A presentation string. For IIOP requests, this string is "oracle.aurora.server.SGiopServer". For HTTP requests, this string is "`HTTP://webserver`"
`-host` | Specifies the hostname where the endpoint is to be unregistered.
`-port` | Specifies the port number for the endpoint.
`-describe | -d` | Summarizes the tool's operation.
`-help | -h` | Summarizes the tool's syntax.
`-version | -v` | Shows the version.
`-delete` | Deletes the endpoint completely. If not specified, this endpoint will be registered upon database startup.

### Web Application Management Commands

The session shell provides a set of specialized commands for manipulating the OSE JNDI namespace, the web server and publish servlets. The uses and syntax requirements of each command are described in the following sections:

- Service Configuration--Create the service root for a designated service within the namespace.

- Web Domain Configuration--Create one or more domains within the service root.

- Servlet Context Management--Create servlet contexts in one of the defined domains.

- Servlet Management--After copying the servlets into the servlet context, you publish it so that the clients can access it.

- JavaServer Pages Management--You must publish any JavaServer Pages before a client can access them.

- Export Commands--Export configuration information about a web domain into a mod_OSE format.

- Security Management--Specify the security realm.

### Service Configuration

The following session shell commands are provided to create a new service. Each service is associated with a different presentation string and protocol.

addendpoint | createservice | createwebservice
destroyservice | rmendpoint |

#### addendpoint

Adds a new endpoint dynamically with the database listener. The listener must already exist. This command only registers a new endpoint for a web service with the existing listener.

##### Syntax

    addendpoint [options] <service> <name>
    	[-listener <lsnr>]

    		[-net8]

    	[-interface <int_spec>]

    	[-port <port_num>]

    	[-register]

    	[-ssl]

    	[-threads <min> <max>]

    	[-timeout <seconds>]

##### Argument Summary

Table 1-31 summarizes the `addendpoint` command-line arguments:

##### Table 1-31 addendpoint Command Options

Option | Description
--- | ---
`<service>` | The service that the endpoint will listen for incoming requests on. For example, `webservice` is a valid service name.
`<name>` | The name of the endpoint.
`-listener <lsnr>` | The address of the listener to add the endpoint to for this service. If not specified, the endpoint is added to the default listener.
`-net8` | Specifies that the endpoint is configured to accept requests over the Net8 protocol. If not specified, the endpoint is configured to accept requests over the TCP protocol. Use Net8 when using mod_OSE to communicate with Servlets.
`-port <port_num>` | The port number that the endpoint is registered for listening on.
`-interface <int_spec>` | The IP address used to connect to this service. The default allows all IP addresses. The IP address specified is mapped to the service domain.
`-register` | This option specifies that the endpoint should always exist. That is, every time this listener is initiated, the endpoint exists on that listener. If not specified, the endpoint terminates when the listener terminates.
`-ssl` | Specifies that the endpoint listens for secure requests that use the SSL protocol.
`-threads <min> <max>` | The minimum and maximum number of threads for the endpoint. The minimum value is started upon listener initialization; the maximum value is used to deny any more incoming requests.
`-timeout <seconds>` | The socket read timeout value in seconds. The amount of time that the web server will allow you to block on the socket.

The following example adds a listener endpoint on port 8080 for the `webserver` service. It starts up three threads and has a socket read timeout of 300 seconds.

    addendpoint -port 8080 -threads 3 5 -timeout 300 webserver endpt1

#### createservice

Creates basic information for a service that is used during service installation. The service can either be an HTTP or IIOP based service, or a brand-new service that you have developed.

##### Syntax

    createservice [options] <service>
    	[-http | -iiop]

    	[-service <class>]

    	[-properties <prop_groups>]

    	[-root <location>]

    	[-globalTimeout <seconds>]

##### Argument Summary

Table 1-32 summarizes the `createservice` command-line arguments:

##### Table 1-32 createservice Argument Summary

Option | Description
--- | ---
`<service>` | The user-defined name of the new service.
`-http` | The service is HTTP-based.
`-iiop` | The service is IIOP-based.
`-service <class>` | The Java class that implements the `<service>`. Defaults to Oracle-provided classes if specifying -`http` or -`iiop`. Other presentations require this option.
`-properties <prop_groups>` | List of property groups to use as the defaults for this service. Specify the name-value pairs in the same way as in the setgroup command.
`-root <location>` | JNDI location for the service configuration.
`-globalTimeout <seconds>` | Timeout for database sessions processing requests for this service. Timeout is specified in seconds.

#### createwebservice

Creates basic information for a web-based service that is used during service installation. This service uses the HTTP protocol for connecting. This is the similar to executing `createservice` `-http`.

##### Syntax

    createwebservice [options] <service_name>
    	-root <location>

    	[-properties <prop_groups>]

    	[-ip]

    	[-virtual]

##### Argument Summary

Table 1-33 summarizes the `createwebservice` command-line arguments:

##### Table 1-33 createwebservice Argument Summary

Option | Description
--- | ---
`<service>` | The user-defined name of the new service.
`-root <location>` | JNDI location for the web service configuration.
`-properties <prop_groups>` | List of property groups to use as the defaults for this service. Specify the name-value pairs in the same way as in the setgroup command.
`-ip` | The web service allows IP-based multi-homed domains.
`-virtual` | The web service allows VirtualHost multi-homed domains.

Note: If neither -`ip` or -`virtual` are specified, the web service is a single domain web service. The name given will be the service root name.

The following example creates a web service, `webserver`, that is defined in the "`/webdomains`" directory. The "`/webdomains`" directory should have been created by the createwebdomain command.

    createwebservice -root /webdomains webserver -properties "debug=true
    >servlet.class=SCOTT:customer.CustMain
    >details=default"

#### destroyservice

Removes a defined service (created either by the createservice or createwebservice commands), unregisters all endpoints, and removes the endpoints so that they will not be started when the listener is initiated again.

    destroyservice [-all] <service_name>

##### Argument Summary

Table 1-34 summarizes the `destroyservice` command-line arguments:

##### Table 1-34 destroyservice Command Options

Option | Description
--- | ---
`<service>` | The service created by the createservice or createwebservice commands.
`-all` | Erases everything under this service root.

The following example deletes the `webserver` service.

    destroyservice webserver

#### rmendpoint

Removes a specific endpoint from a service and unregisters it from the listener.

##### Syntax

    rmendpoint <service> <name>

##### Argument Summary

Table 1-35 summarizes the `rmendpoint` command-line arguments:

##### Table 1-35 rmendpoint Command Options

Option | Description
--- | ---
`<service>` | The service that the endpoint will listen for incoming requests on. For example, `webservice` is a valid service name.
`<name>` | The name of the endpoint that was created with addendpoint.

The following example deletes the `endpt1` endpoint:

    rmendpoint webserver endpt1

### Web Domain Configuration

Within the service root, you create one or more web domains. These web domain store servlet contexts. Use web domains to organize your servlet contexts. These commands enable you to create and destroy any web domain.

- createwebdomain

- destroywebdomain

#### createwebdomain

Creates a web domain owned by the specified schema. This domain contains services. The services contain servlets, which execute under the schema's identity. Each web domain is initialized with the "`/default`" servlet contexts.

##### Syntax

    createwebdomain [options] <domain_name>

    	[-docroot <location>]

    	[-properties <prop_groups>

##### Argument Summary

Table 1-36 summarizes the `createwebdomain` command-line arguments:

##### Table 1-36 createwebdomain Command Options

Option | Description
--- | ---
<domain_name> | The full path of where the domain should be located and its name.
`-docroot <location>` | The location of the servlet static pages for this webdomain's default context. Other context's docroot location is specified in the createcontext command.
`-properties <prop_groups>` | List of property groups to use as the defaults for this service. Specify the name-value pairs in the same way as in the setgroup command.

The following command creates the `/webserver` domain in the root directory.

    createwebdomain /mywebserver

#### destroywebdomain

Removes the web domain created by the `createwebdomain` command. This command also deletes any servlet contexts contained within the domain.

##### Syntax

    destroywebdomain <domain_name>

##### Argument Summary

Table 1-37 summarizes the `destroywebdomain` command-line arguments:

##### Table 1-37 destroywebdomain Command Options

Option | Description
--- | ---
`<domain_name>` | The full directory and name used within `createwebdomain` to create the domain.

The following example deletes the `/webserver` domain and all servlets contained within it:

    destroywebdomain /webserver

### Servlet Context Management

Once all domains are setup, you can create the servlet context to exist within the specified domain. Once created, you can copy servlets into each context.

Management commands for servlet contexts include the following:

accesslog | adderrorpage | createcontext
destroycontext | realm | rmerrorpage

#### accesslog

Specifies how HTTP access logging is handled for the servlet context. This records information about each incoming HTTP request. You have one of three options.

##### Syntax

    accesslog [options] <context_name>
    	[-trace | -systable | -table <table_spec>]

##### Argument Summary

Table 1-38 summarizes the `accesslog` command-line arguments:

##### Table 1-38 accesslog Command Options

Option | Description
--- | ---
`<context_name>` | The name of the servlet context.
`-trace` | Write all log entries to the .TRC text file.
`-systable` | Write all log entries to the SYS.JAVA$HTTP$LOG$ table. This is the default logging option. The owner of the service context must have permission to access this table. If not, specify the -table option with a table that the owner does have permission for.
`-table <table_spec>` | Write all log entries to the designated table. The table must contain the same layout as the SYS.JAVA$HTTP$LOG$ table.

The following example specifies that the HTTP access log messages for the `/webdomains/contexts/default` service context should be directed into the `HTTP_LOG` table in SCOTT's schema:

    accesslog -table SCOTT:HTTP_LOG /webdomains/contexts/default

#### adderrorpage

When a specific error code is returned, you can specify a URL that the client is directed to. This is useful for displaying error messages to the client.

##### Syntax

    adderrorpage -error <errcode> -virtualpath <errorpath> <context_name>

#####

##### Argument Summary

Table 1-39 summarizes the `adderrorpage` command-line arguments:

Table 1-39 adderrorpage Command Arguments

Arguments | Description
--- | ---
`<context_name>` | The directory path and name of the servlet context.
`-error <errcode>` | The error code that identifies the error page.
`-virtualpath <errorpath>` | The error page, which is a servlet virtual path that this error code is associated with. This is a URI that can map to a servlet, which will be served up, or can map to a static HTML page. The web server serves up whatever the URI maps to.

The following example associates the error 401 with the servlet identified within the -`virtualpath` option. This code is valid for the default context.

    adderrorpage -error 401 -virtualpath /SCOTT/Errors/Err401 \

    	/webdomains/context/default

#### createcontext

Creates a servlet context within the specified domain, which was created by the createwebdomain command.

##### Syntax

    createcontext [options] <domain_name> <context_name>

    	-virtualpath <path>

    	[-recreate]

    	[-properties <prop_groups>]

    	[-docroot <location>]

    	[-stateless]

##### Argument Summary

Table 1-40 summarizes the `createcontext` command-line arguments:

##### Table 1-40 createcontext Command Options

Option | Description
--- | ---
`<domain_name>` | The directory and name for the domain where the servlet context is to be created. This domain must already exist. You create the domain through the createwebdomain command.
`<context_name>` | The user-defined name for the servlet context to be used within the domain.
`-virtualpath <path>` | Bind the newly created servlet context to this virtual path.
`-recreate` | If a context with this name already exists, delete it before adding an empty context with this name. This destroys any servlets currently associated with this context.
`-properties <prop_groups>` | List of property groups to use as the defaults for this service. Specify the name-value pairs in the same way as in the setgroup command.
`-docroot <location>` | All of the servle static pages are located in this directory in the server machine's filesystem.
`-stateless` | All servlets in this context are stateless. Contexts declared to be stateless can only contain servlets that are stateless and never try to access the HTTPSession object.

The following example creates a servlet context within the domain "`ScottRoot`" of the name "`ScottContext`". All of the servlets should be loaded into the "`/private/scott/html`" directory. To access the servlets in this directory, use the virtual path of "`/SCOTT`".

    createcontext -virtualpath /SCOTT -docroot /private/scott/html

    	/ScottRoot ScottContext

#### destroycontext

Removes the servlet context, its information, and all contained servlets from the domain.

##### Syntax

    destroycontext <context_name>

##### Argument Summary

Table 1-41 summarizes the `destroycontext` command-line arguments:

##### Table 1-41 destroycontext Command Options

Option | Description
--- | ---
`<context_name>` | The servlet context name, which was used on the createcontext command.

The following example remove the "`ScottContext`" servlet context. In addition, all servlets contained in the server's filesystem directory "`/private/scott/html`" are all deleted, and the virtual path "`/SCOTT`" is removed.

    destroycontext ScottContext

#### rmerrorpage

Remove the error code associated with the servlet context. This only removes the error code: it does not remove the servlet associated with the error code.

##### Syntax

    rmerrorpage -error <errcode> <context_name>

##### Argument Summary

Table 1-42 summarizes the `rmerrorpage` command-line arguments:

##### Table 1-42 rmerrorpage Command Options

Option | Description
--- | ---
`<context_name>` | The name of the servlet context.
`-error <errcode>` | The error code that the error page is associated with. Deletes both the error code and the page that it is associated with.

The following command removes the previously defined error code 401 from the default servlet context. The servlet associated with this code may still exist.

    rmerrorpage -error 401 /webdomains/context/default

### Servlet Management

Once you have created the correct directory structure to contain your servlet, you can copy these into the server's filesystem. Then, you must publish these servlets in order for the client to invoke them.

#### publishservlet

Publish the servlet within the named servlet context.

##### Syntax

    publishservlet [options] <context_name> <servlet_name> <class_name>

    	[-virtualpath <path>]

    	[-stateless]

    	[-reuse]

    	[-properties props]

##### Argument Summary

Table 1-43 summarizes the `publishservlet` command-line arguments:

##### Table 1-43 publishservlet Command Options

Option | Description
--- | ---
`<context_name>` | The name of the servlet context.
`<servlet_name>` | The name assigned to this servlet in the named_servlets directory to be published within this context. This name is used to refer to the class published with this command.
`<class_name>` | The name of the class implementing the HttpServlet interface.
`-virtualpath <path>` | Bind this servlet to this virtual path.
`-stateless` | This servlet is stateless and can not access the HTTPSession object.
-reuse | Add the virtual path to an existing servlet without republishing the servlet.
`-properties <prop_groups>` | List of property groups to use as the defaults for this service. Specify the name-value pairs in the same way as in the setgroup command.

The following command publishes the default context for the `HelloWorld` example that was loaded in SCOTT's schema:

    publishservlet -virtualpath /hello /websdomains/contexts/default \

    	helloServlet SCOTT:HelloWorld

#### unpublishservlet

Removes the servlet from the context as well as any existing virtual path for the servlet.

##### Syntax

    unpublishservlet <context_name> <servlet_name>

##### Argument Summary

Table 1-44 summarizes the un`publishservlet` command-line arguments:

##### Table 1-44 unpublishservlet Command Options

Option | Description
--- | ---
`<context_name>` | The name of the servlet context.
`<servlet_name>` | The name of the servlet to be published within this context.

The following example unpublishes the `HelloWorld` servlet:

    unpublishservlet /websdomains/contexts/default helloServlet

### JavaServer Pages Management

Commands for publishing JavaServer Pages.These commands assume that the JSP definition is available as a resource on the server.

#### publishjsp

Translation, compilation, hotloading (if enabled), and publishing all occur automatically with the `publishjsp` command. This tool translates and publishes the JavaServer Pages in the designated servlet context. This command compiles the JavaServer Page into a servlet, which is stored in `jspresource`, and maintains the dependency between the `jspresource` and the generated class.

Run `publishjsp` after you have loaded a `.jsp` (or `.sqljsp`) file into Oracle8i as a resource schema object.

##### Syntax

    publishjsp [options] <jsp_resource>

    	-virtualpath <path>

    	-schema <schema>

    	-context <context>

    	[-stateless]

    	[-servletName <servlet_name>]

    	[-packageName <pkg_name>]

    	[-hotload]

    	[-verbose]

    	[-resolver <resolver>]

    	[-extend <class>]

    	[-implement <interface>]

##### Argument Summary

Table 1-45 summarizes the `publishjsp` command-line arguments:

##### Table 1-45 publishjsp Command Options

Option | Description
--- | ---
`<jsp_resource>` | The file name.jsp (or name.sqljsp for a SQLJ JSP page) is the JSP page resource schema object that you loaded with loadjava and is the only required parameter, along with any relevant schema path information.
`-virtualpath <path>` | Specify an alternative servlet path for the JSP page; otherwise, the servlet path is simply the specified .`jsp` file name itself along with any specified schema path. By default, `path/name.jsp` becomes the servlet path.
`-stateless` | The JSP page is to be stateless--the JSP page should not have access to the HttpSession object during execution. This flag is used for mod_ose optimization.
`-schema <schema>` | Specify the schema where the JSP page resource schema object is located, if it is not in the same schema you logged in to through `sess_sh`. This schema must be accessible from your `sess_sh` login schema. The `publishjsp` command does not offer a way to specify passwords.
`-servletName <servlet_name>` | Specify an alternative servlet name (in OSE named_servlets) for the JSP page. By default, the servlet name is the base name of the .`jsp` file along with any path you specified.
`-packageName <pkg_name>` | Specify a package name for the generated page implementation class. By default, it is the path specification for the .`jsp` file when you run `publishjsp`. This option affects where schema objects are placed in the schema, but does not affect the servlet path of the JSP page.
`-context <context>` | Specify a servlet context in the Oracle Servlet Engine. The context path of this servlet context becomes part of the URL used to invoke the page. The OSE default context, `/webdomains/contexts/default`, is "/".
`-hotload` | Enable and perform hotloading. See the discussion on hotload following this table for more information.
`-verbose` | Report the translation steps during execution.
`-resolver <resolver>` | Specify an alternative Java class resolver. See the resolver discussion in the "loadjava" for more information.
`-extend <class>` | Specify a Java class that the generated page implementation class extends.
`-implement <interface>` | Specify a Java interface that the generated page implementation class implements.

#### Argument Details

hotload

Enable this flag to enable and perform hotloading. This results in the following steps being performed by the `publishjsp` command:

1. Static output is written to a resource schema object instead of to the page implementation class schema object.

2. A `main`() method and a hotloading method are implemented in the generated page implementation class to allow hotloading.

3. The `main`() method is executed to perform hotloading.

4. To use -hotload, you must have permission for the JServer hotloader. This can be granted as follows (from SQL*Plus, for the SCOTT schema, for example):

       dbms_java.grant_permission('SCOTT',

       	'SYS:oracle.aurora.security.JServerPermission', 'HotLoader', null);

The following example publishes the `Foo.jsp` into the default servlet context path of "/" and the default servlet path of "`dir1/Foo.jsp`".

    publishjsp -schema SCOTT dir1/Foo.jsp

After this command, `Foo.jsp` can be invoked as follows:

    http://host[:port]/dir1/Foo.jsp

Access it dynamically from another JSP page in the application, suppose a page published as `dir1/Bar.jsp`, as follows (using page-relative syntax and then application-relative syntax):

    <jsp:include page="Foo.jsp" flush="true" />

#### unpublishjsp

Removes a JavaServer Page from the JNDI namespace. This does not remove the page implementation class schema object from the database. You do not need to specify a servlet name unless you specified one when you ran `publishjsp`. Generally, the only required input is the servlet path, which is also known as the "virtual path".

##### Syntax

    unpublishjsp [options] <servlet_path>

    	[-servlet <servlet_name>]

    	[-context <context>]

    	[-showVersion]

    	[-usage]

    	[-verbose]

##### Argument Summary

Table 1-46 summarizes the un`publishjsp` command-line arguments:

##### Table 1-46 unpublishjsp Command Options

Option | Description
--- | ---
`<servlet_path>` | Specify the servlet path for the JSP page.
`-servlet <servlet_name>` | Specify the servlet name for the JSP page. By default, the servlet name is the base name of the .`jsp` file along with any path you specified.
`-context <context>` | Specify a servlet context in the Oracle Servlet Engine. The OSE default context path is "/".
`-showVersion` | Display the OracleJSP version number
`-usage` | Display a option list
`-verbose` | Report the translation steps as it executes

The following example unpublishes the page that was published in the `publishjsp` section:

    unpublishjsp dir1/Foo.jsp

### Export Commands

Exports the structure of a web domain and its configuration file for the mod8i proxy.

The export utility works in two stages:

1. Generates, in XML format, the structure of a webdomain or contexts within a domain.

2. Optionally, apply transformations to the XML to produce configuration files specific to a the mod8i proxy.

#### exportwebdomain

This command creates the configuration files required for Apache's mod8i and for others. The default output is in an XML format.

##### Syntax

    exportwebdomain [options] <domain_name>

    	[-context <context>]

    	[-netservice <name>]

    	[-format <fmt>]

    	[-nodefault]

    	[-nodocs]

##### Argument Summary

Table 1-47 summarizes the `exportwebdomain` command-line arguments:

##### Table 1-47 exportwebdomain Command Options

Option | Description
--- | ---
`<domain_name>` | The name of the web domain that you want converted.
`-context <context>` | The name of the context to support. If not specified, all contexts within the domain are exported.
`-netservice <name>` | The name of the service defined in the Net8 initialization file (tnsnames.ora file).
`-format <fmt>` | The XSLT transformation defined in <`fmt>.xml` is used in the transformation of the domain. Use -`format` `apache` for mod_OSE configuration. Use `-format` `iis` for Microsoft Internet Service configuation. The <`fmt>.xm`l files must be loaded as resources in the server under "`oracle/aurora/mts/http/admin/formats`".
`-nodefault` | Do not map the default context, unless indicated by the -context option.
`-nodocs` | Do not forward URLs mapped into doc_root to the Servlet engine. This assumes that such static pages will be served directly by the external webserver.

The following example exports the configuration that exists within the `/webdomain` domain to the "`/tmp/ApacheConfig`" file. The format is defined in the `Apache.xml` file and the Net8 connect string service name is `apache_connect`.

    exportwebdomain -format Apache -netservice apache_connect \

    	/webdomain & > /tmp/ApacheConfig

### Security Management

In HTTP Security, access to a protected resource is composed of two parts, authentication and authorization. Authentication validates submitted credentials, which establishes that a user is known and validated by the system. Authorization determines whether an authorized user is allowed to perform the requested action.

There are four stages involved in establishing these security measures:

1. Declare the known principals of a service

2. Declare resources as being protected, and how they are to be protected

3. Declare the permissions of principals within the servlet context

4. Declare a security servlet for a servlet context

Without any one of these steps, security will either be non-existant or it will not allow any access to protected resources. These steps ensure that enough information has been declared, so that HTTP Security can successfully protect web resources.

#### Declaring Principals

Principal declarations are held in a "realm". A realm is made up of users and groups. The more generic term for either a user or a group is principal. When either entity can be used in a situation, the term principal should be used. Realm definitions exist within the scope of a web service. That is, all servlet contexts within a web service can use the same pools of principals for security.

- Principals have names by which they are identified within the system. Typically, this identification takes the form of a passphrase, but it is not always limited to this construct. Principals will have permissions declared for them, and may inherit any permissions that exist for groups of which they may be a member.

- Users have all of the same properties as principals

- Groups have all of the same properties as principals, as well as the property that other principals can be declared as being a member of a group. Thus, they inherit any permissions that exist for that group.

- Realms define sets of principals. There may be multiple realms within a single web service. The realm and its implementation are core to all of HTTP Security. A realm is the source of the following:

  - the valid set of principals

  - the types of principals that are handed to the server

  Since the realm is the source of all principals, it plays a key role in what types of credentials are to be used to identify principals, aiding the principals in managing the credentials themselves or can defer to whatever entity that does have them, and establishing the relationships among all principals within it.

By default, there are three implementations of realms for HTTP Security. They are identified by their types:

- JNDI--Stores all information in JNDI entries in the namespace

- DBUSER--Defers to local user and role definitions within the database itself

- RDBMS--Stores all principals and their relationships in database tables

These type names are shortcuts to use when declaring which realm class name to use in the JNDI entry that will be used to instantiate the realm.

#### Predefined Realms

The DBUSER realm derives all principal definitions from the users and roles defined within the database itself. No principal management is allowed through any of the security commands for this type of realm. The database, not the security tools, manages principal creation, deletion, and role membership. Since all instances of DBUSER realms utilize the same source for principal definition, all instances will essentially be equivalent. When referring to principals with a DBUSER realm, no case translations are performed. When the database entity was created, unless the case was explicitly expressed, the name will be all uppercase. For example SYS and PUBLIC must always be referred to in all uppercase. If a user were created, as follows, the username would exactly be '`joe`'.

    create user "joe" identified by welcome;

This is especially important when it comes to supplying usernames and passwords from the browser.

#### Realm Management Overview

To create a RDBMS realm:

    realm publish -w /myService -add testRealm -type RDBMS

Note: For JNDI and DBUSER, use those titles as the type argument.

To remove a realm:

    realm publish -w /myService -remove testRealm

Note: It is by design of the system and its use of JNDI that realm declarations reside in the JNDI namespace. Deploying customized realms requires customizing the namespace entry.

To publish a custom realm:

    realm publish -w /myService -add testRealm -classname foo.bar.MyRealm

#### Managing Principals Overview

Not all realms support the editing of principals. For example, DBUSER type realms do not support any principal manipulation.

To create a user:

    realm user -w /myService -realm testRealm1 -add user1 -p upswd1

To create a group:

    realm group -w /myService -realm testRealm1 -add group1 -p gpswd1

Note: In either of the above commands, if the password is left blank, the principal name is used instead.

To delete a user:

    realm user -w /myService -realm testRealm1 -remove user1

To delete a group:

    realm group -w /myService -realm testRealm1 -remove group1

To list users of a realm:

    realm user -w /myService -realm testRealm1

To list groups of a realm:

    realm group -w /myService -realm testRealm1

To add a principal to a group:

    realm parent -w /myService -realm testRealm -group group1 -add user1

To remove a principal from a group:

    realm parent -w /myService -realm testRealm -group group1 -remove user1

To list principals within a group:

    realm parent -w /myService -realm testRealm -group group1

To query which groups a principal is member:

    realm parent -w /myService -realm testRealm -q user1

Note: All realms do not support querying the principal group members.

#### Resource Protection Overview

In Aurora HTTP Security, resource protection is local to the servlet context. To declare a resource as protected, two pieces of information must be supplied. That information is embodied in a protection scheme. A scheme is of the form:

    <authType>:<realmName>

Currently, there are only two valid authentication types, although these can be extended through JNDI namespace entries:

- Basic--typical base64 encoding, which is not secure

- Digest--both parties keep the password to themselves and pass highly encrypted codes, which are salted with situation specific values, such as timestamp, URL being requested, a secret key, and IP of the requester.

  Note: Form based and SSL are currently not supported, though they may appear in a later update and can be plugged in through namespace entries.

You can declare resources to not be protected, which is useful when the servlet context root is to be protected. The problem is that when the root is protected, so are the error pages since they are part of the tree. In order to prompt for authentication, an error page is handed out. If that error page is protected, cycles develop and the desired behavior is not observed. Instead, explicitly declare the error pages as unprotected by using a protection scheme of <`NONE`>.

The path that describes what should be protected is local to the servlet context. Internally, that path is "normalized" to enable stable, predictable patterns for matching. This may cause the internal representation to differ from the original path used to create the protection scheme. HTTP Security uses the longest, most exact match possible when trying to apply the protection rules.

Protecting paths to resources with protection schemes:

    realm map -s /myService/contexts/myContext -a /doc/index.html \

    	-scheme basic:testRealm1
    realm map -s /myService/contexts/myContext -a /doc -scheme basic:testRealm2
    realm map -s /myService/contexts/myContext -a /doc/* -scheme basic:testRealm3

With the above declarations, here is how paths would be matched to realms:

    /doc/index.html -> testRealm1
    /doc -> testRealm2
    /doc/ -> testRealm2
    /doc/index -> testRealm3
    /doc/foo -> testRealm3

To remove the protection of a path:

    realm map -s /myService/contexts/myContext -r /doc/index.html

To list all protected paths within a servlet context:

    realm map -s /myService/contexts/myContext

To explicitly declare a path not to be protected:

    realm map -s /myService/contexts/myContext -a /system/* -scheme <NONE>

To list all protected paths within a servlet context:

    realm map -s /myService/contexts/myContext

#### Declaring Permissions

Permissions are the most involved of all HTTP Security declarations. They tie web service scoped entities with servlet context scoped entities and they reside in the servlet context.

A permission declaration consists of several pieces:

- web service root

- realm within specified web service

- servlet context within specified web service

- principal within specified realm

- path to which the permission is to apply

- whether or not the permission being granted or denied

- HTTP actions being assigned

Given all of the pieces that are being tied into one permission declaration, it is easy to see why these are the most complicated declarations. HTTP Security permissions concern only those HTTP actions that are valid for HTTP requests, as follows:

- GET

- POST

- PUT

- DELETE

- HEAD

- TRACE

- OPTIONS

To declare a granted permission on /foo/index.html for user1 for GET and POST:

    realm perm -w /myService -realm testRealm1 -s /myService/contexts/myContext \

    	-n user1 -u /foo/index.html + get,post

To declare a denied permission on `/foo/*` for `user1` for `PUT` and `DELETE`:

    realm perm -w /myService -realm testRealm1 -s /myService/contexts/myContext \

    	-n user1 -u /foo/* - put,delete

To remove granted permissions on `/foo/index.html` for `user1`:

    realm perm -w /myService -realm testRealm1 -s /myService/contexts/myContext \

    	-n user1 -u /foo/index.html +

To list all permissions for a user:

    realm perm -w /myService -realm testRealm1 -s /myService/contexts/myContext \

    	-n user1

#### Declaring A Security Servlet

All HTTP Security is declared through JNDI namespace entries. This is also true for the servlet that does the enforcing of security. In the servlet context, if there is a `PrivilegedServlet` named `httpSecurity`, that servlet is added as the first pre-filter for all requests within that servlet context.

As with all JNDI namespace entries so far in HTTP Security, if customization is desired, the namespace entry can specify any custom servlet, if it implements the `PrivilegedServlet` interface. If this servlet is customized, it can handle security any way it chooses, since its main responsibility is to do one of the following for (`HttpRequest.PrivilegedAccess, HttpRequest, HttpResponse`):

- Raise an `AccessControlException` during its service if there is any security violation

- Allow the the request

Once authentication and authorization have taken place, it is also the responsibility of the servlet to set specific authenticated principal values on the request itself. This is the user information that can be retrieved from the request by any executing servlet.

To create a security servlet:

    realm secure -s /myService/contexts/myContext

Removing the security servlet removes all security enforcement in a servlet context. If the entry is missing, the webserver continues execution with no security enforcement.

To remove a security servlet:

    rm /myService/contexts/myContext/httpSecurity

Note: The servlet is not published in `namedServlets`, but within the `servletContext` itself.

### realm

The realm command suite, listed below, manages all realm constituents.

list | echo | secure
map | publish | user
group | parent | perm

#### list

Lists the realms declared for the given web service.

The syntax is as follows:

    realm list -w <webServiceRoot>

where the `<``webServiceRoot``>` is the web service to list.

    realm list -w /webservice

#### echo

Can be used to suppress the results of subsequent realm commands.

The syntax is as follows:

    realm echo [0 | 1]

- 0: Do not print any results of subsequent operations

- 1: Print results of subsequent operations. This is the default.

      realm echo 0

#### secure

Used to setup the default security servlet for a given servlet context.

The syntax is as follows:

    realm secure -s <servletContextPath>

where `servletContextPath` is the servlet context to operate upon.

#### map

Used to map paths local to the given servlet context to protection schemes. This is what declares a resource to be protected.

The syntax is as follows:

    realm map -s servletContextPath [-(a[dd]|r[emove]) <path> -scheme auth:realm]

##### Table 1-48 map Option Description

Option | Description
--- | ---
`-s servletContextPath` | The servlet context to operate upon. If nothing else is supplied, this will list all URL-Scheme mappings for the given servlet context.
`-add | -a <path>` | The path for which a mapping will be added, or edited if the mapping already exists.
`-remove | -r <path>` | The path for which a mapping will be removed.
`-scheme auth:realm` | The protection scheme to use for the given mapping.

#### publish

User to publish and remove various types of realms within a given web service. If the realm already exists, information about that pre-existing realm is output.

The syntax is as follows:

    realm publish -w <webserviceRoot> [-(a[dd]|r[emove]) <realmName>

    	[-type <realmType>]]

##### Table 1-49 publish Option Summary

Option | Description
--- | ---
`-w <webserviceRoot>` | The web service to operate upon.
`-add | -a <realmName>` | The name to use for creating the realm within the web service.
`-remove | -r <realmName>` | The name of the realm to remove from the web service.
`-type <realmType>` | Specifies the type of realm to publish. One of RDBMS, DBUSER, JNDI. If not specified, the default value is RDBMS.

#### user

Used to query what users exist within a realm, add users to a realm, remove users from a realm, edit the passwords of existing users.

The syntax is as follows:

    realm user -w <webserviceRoot> -realm <realmName>

    	[-(a[dd]|r[emove]) <userName> [-p <user> <password>]]

##### Table 1-50 user Option Summary

Option | Description
--- | ---
`-w <webserviceRoot>` | The web service to operate upon.
`-realm <realmName>` | The name of the realm to operate upon. If no other arguments are supplied, the names of all users within the given realm are output.
`-add | -a <userName>` | The name of the user to create within the realm.
`-remove | -r <userName>` | The name of the user to remove from the realm.
`-p <password>` | The password to be associated with the user. If not supplied, the user name is used instead. If the user already exists, the user's password is reset to this value.

#### group

Used to query what groups exist within a realm, add groups to a realm, remove groups from a realm, edit the passwords of existing groups.

The syntax is as follows:

    realm group -w <webserviceRoot> -realm <realmName>

    	[-(a[dd]|r[emove]) <groupName> [-p <group> <password>]]

##### Table 1-51 group Option Summary

Option | Description
--- | ---
`-w <webserviceRoot>` | The web service to operate upon.
`-realm <realmName>` | The name of the realm to operate upon. If no other arguments are supplied, the names of all users within the given realm are output.
`-add | -a <groupName>` | The name of the group to create within the realm.
`-remove | -r <groupName>` | The name of the group to remove from the realm.
`-p <password>` | The password to be associated with the group. If not supplied, the group name is used instead. If the group already exists, the group's password is reset to this value.

#### parent

Used to query and manage principal-group relationships.

The syntax is as follows:

    realm parent -w webserviceRoot -realm realmName [-g[roup] groupName

    	[-(a[dd]|r[emove]) principalName]] [-q[uery] principalName

##### Table 1-52 parent Option Summary

Option | Description
--- | ---
`-w webserviceRoot` | The web service to operate upon.
`-realm realmName` | The name of the realm to operate upon.
`-group groupName` | The group to operate upon. If no other arguments are supplied, all members of this group are output, if the given realm supports such an action.
`-add principalName` | The name of the principal to add to this group. Some realms may not support this action or may disallow this operation if it detects a circularity in the group-principal membership chain.
`-remove principalName` | The name of the principal to remove from the group. Some realms may not support this action.
`-query principalName` | Print the names of all groups that have this principal as a member. Some realms may not support this action.

#### perm

Used to query and manage permissions for principals.

The syntax is as follows:

    realm perm -w webserviceRoot -realm realmName -s servletContextPath

    	-n[ame] principalName [-p[ath] path (+|-) permList]

##### Table 1-53 perm Option Summary

Option | Description
--- | ---
`-w webserviceRoot` | The web service to operate upon.
`-realm realmName` | The name of the realm to operate upon.
`-s servletContextPath` | The servlet context to operate upon.
`-name principalName` | The name of the principal for which permission operations will be performed. If no other arguments are supplied, then print out all permissions for this principal.
`-path path` | The path to be used when applying the permission.
`+ permList` | The list of HTTP actions to grant to the user. If permList is not given, then clear all granted permissions for the user. This is not an additive operation, any existing granted permissions for the user are completely over-written by the new list.
`- permList` | The list of HTTP actions to deny to the user. If permList is not given, then clear all denied permissions for the user. This is not an additive operation, any existing denied permissions for the user are completely over-written by the new list.

Note: The `permList` is a comma separated list of HTTP actions with no spaces. For Example: `get,post,trace`

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index