Oracle8i Java Tools Reference
Release 3 (8.1.7)

Part Number A83727-01

Library

Product

Contents

Index

Go to previous page Go to beginning of chapter Go to next page

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:

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

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.

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

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:

     
     
     
     
     
     
 

 

 

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.

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

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:

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.

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:

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

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

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

     
   

 

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

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

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 unpublishservlet 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 unpublishjsp 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>.xml 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.

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

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:

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:

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:

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):

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

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]

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  




Go to previous page
Go to beginning of chapter
Go to next page
Oracle
Copyright © 1996-2000, Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index