Oracle8i Java Tools Reference
Release 3 (8.1.7)

Part Number A83727-01
 Library Product Contents Index

## Session Namespace Tools

Each database instance running the Oracle8 i JServer software has a session namespace, which the Oracle8 i ORB uses to activate CORBA and EJB objects. A session namespace is a hierarchical collection of objects known as PublishedObjects and PublishingContexts. PublishedObjects are the leaves of the hierarchy and PublishingContexts are the nodes, analogous to UNIX file system files and directories. Each PublishedObject is associated with a class schema object that represents a CORBA or EJB implementation. To activate a CORBA or EJB object, a client refers to a PublishedObject's name. From the PublishedObject, the Oracle8 i ORB obtains the information necessary to find and launch the corresponding class schema object.

Creating a PublishedObject is known as publishing and can be done with the command-line publish tool or the interactive session shell, both of which this section describes. CORBA server developers create PublishedObjects explicitly after loading the implementation of an object with loadjava. EJB developers do not explicitly load or publish their implementations; the deployejb tool (see "deployejb") implicitly does both.

A PublishedObject has the following attributes:

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

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

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

PublishedObjects and PublishingContexts, as with their file and directory counterparts, have owners and rights (privileges). An owner can be a user name or a role name; only the owner can change the ownership or rights of a PublishedObject or PublishingContext. Table 1-4 describes session namespace rights.

##### Table 1-4 PublishingContext and PublishedObject Rights
Right  Meaning for PublishingContext  Meaning for PublishedObject

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

/

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>]
-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 \
-service sess_iiop://dlsun164:2481:orcl

##### IDL Restrictions

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

1. You store the IDL interface definition within the IFR through the Oracle8i JServer publish command. The publish command stores the interface within a flat file, AuroraIFR.idl. Normally, this file is automatically written to $ORACLE_HOME/javavm/admin. However, if this directory is not write-enabled, you can specify another fully-qualified filename within the "aurora.ifr.file" system property through the modifyprops tool, as follows: modifyprops -user SCOTT/TIGER@dbhost:5521:orcl "aurora.ifr.file" "/private/ifr/myIFRfile"  2. The -replaceIDL flag will replace any interface with the same name in the IFR, even if it was originally stored by another user. Thus, different users can overwrite another user's interface unknowingly. 3. Once you have stored the interface in the IFR, there is no method for removing it. This file will continue to grow until you delete the entire file. ### remove The remove tool removes a PublishedObject or PublishingContext from a session namespace. It does not remove the Java class schema object associated with a PublishedObject; use dropjava to do that.  Note: This tool is more extensive than the rm command. It removes the PublishedObject or PublishingContext from the namespace and any related IFR interfaces. The rm command solely removes an entity from within the directory. ##### Syntax remove <name> {-user | -u} <username> {-password | -p} <password> {-service | -s} <serviceURL> [options] [-d | -describe] [-h | -help] [-iiop] [-r | -recurse] [-role role] [-ssl] [-useServiceName] [-version | -v]  ##### Argument Summary Table 1-7 describes the remove arguments. ##### Table 1-7 remove Argument Summary Option Description <name> Name of PublishingContext or PublishedObject to be removed. -user Specifies identity with which to log into the instance named in -service. -password Specifies authenticating password for the <username> you specified with -user. -service URL identifying database whose session namespace is to be "opened" by sess_sh. The serviceURL has the form: sess_iiop://<host>:<lport>:<sid>.  <host> is the computer that hosts the target database; <lport> is the listener port that has been configured to listen for session IIOP; <sid> is the database instance identifier. Example: sess_iiop://localhost:2481:orcl  which matches the default installation on the invoker's machine. -describe Summarizes the tool's operation. -help Summarizes the tool's syntax. -iiop Connects to the target database with IIOP instead of the default session IIOP. Use this option when removing from a database server that has been configured without session IIOP. -recurse Recursively removes <name> and all subordinate PublishingContexts; required to remove a PublishingContext. -role Role to assume for the remove; no default. -ssl Connects to the database with SSL server authentication. You must have configured the database for SSL to use this option. -useServiceName If you are using a service name instead of an SID in the URL, you must specify this flag. Otherwise, the tool assumes the last string in the URL is the SID. -version Shows the tool's version. Here are examples of remove tool usage. • Remove a PublishedObject named /test/testhello: remove /test/testhello -user SCOTT -password TIGER \ -service sess_iiop://dlsun164:2481:orcl  • Remove a PublishingContext named /test/etrader: remove -r /test/etrader -user SCOTT -password TIGER \ -service sess_iiop://dlsun164:2481:orcl  ### sess_sh The sess_sh (session shell) tool is an interactive interface to a database instance's session namespace. You specify database connection arguments when you start sess_sh. It then presents you with a prompt to indicate that it is ready for commands. The sess_sh gives a session namespace much of the "look and feel" of a UNIX file system you access through a shell, such as the C shell. For example, the session shell command: ls /alpha/beta/gamma  means "List the PublishedObjects and PublishingContexts in the PublishingContext known as /alpha/beta/gamma". (NT users note: /alpha/beta/gamma, not \alpha\beta\gamma.) Indeed, many session shell command names that operate on PublishingContexts have the same names as their UNIX shell counterparts that operate on directories. For example: mkdir (create a PublishingContext) and cd (change the working PublishingContext). In addition to UNIX-style manipulation of PublishingContexts and PublishedObjects, the session shell can launch an executable, that is, a class with a static main() method. Executables must have been loaded with loadjava, but not published--publishing is for CORBA, EJB, and servlet objects only. #### Syntax sess_sh {-service | -s} <serviceURL> {-user | -u} <user> {-password | -p} <password> [options] [@<filename>] [-batch] [-c | -command <command> <args>] [-credsFile <creds>] [-describe | -d] [-h | -help] [-iiop] [-proxy <host>:<port>] [-role <rolename>] [-ssl] [-useServiceName] [-version | -v]  #### Argument Summary Table 1-8 summarizes the sess_sh command-line arguments. ##### Table 1-8 sess_sh Argument Summary Option Description -service | -s URL identifying database whose session namespace is to be "opened" by sess_sh. The serviceURL should contain one of the following: sess_iiop://<host>:<lport>:<sid> jdbc:oracle:<type>:<spec> http://<host>:<lport>  <host> is the computer that hosts the target database; <lport> is the listener port configured to listen for session IIOP or HTTP <sid> is the database instance identifier. <type> can be either oci8 or thin<spec> is the connect string, alias, or URL for the JDBC driver Examples: sess_iiop://localhost:2481:orcl jdbc:oracle:thin:@dbhost:5521:ORCL http://localhost:2481  -user | -u Specifies user's name for connecting to the database. This name case insensitive; the name will always be uppercased. -password | -p Specifies user's password for connecting to the database. This name case insensitive; the name will always be uppercased. @<filename> Specifies a script file that contains sess_sh commands to be executed. See "Scripting sess_sh Commands in the @<filename> Option" for structure of the indicated file. -batch Disables all messages printed to the screen. No help messages or prompts will be printed. Only responses to entered commands are printed. -command Executes the desired command. If you do not want to run sess_sh in interpretive mode, but only want to execute a single command, execute sess_sh with the -command option followed by a string that contains the command and the arguments. Once the command executes, sess_sh exits. The following executes the "ls -lR" command on the designated host: sess_sh -user SCOTT -password TIGER -service sess_iiop://dbserver:2481:orcl -command "ls -lR" -credsFile Supply a text file with credentials instead of a username and password for the connect. You create this file by exporting a wallet into a text version. -describe | -d Summarizes the tool's operation. -echo Prints out every command before execution. This is useful when executing script files. -help Summarizes the tool's syntax. -iiop Connects to the target database with plain IIOP instead of the default session IIOP. Use this option for a database server configured without session IIOP. -proxy Specifies the proxy host and port number. This is only required if you are using a firewall proxy to communicate with hosts outside your internal network. -role Role to pass to database; there is no default. -ssl Connect to the database with SSL server authentication. You must have configured the database for SSL and specify an SSL port to use this option. -useServiceName If you are using a service name instead of an SID in the URL, you must specify this flag. Otherwise, the tool assumes the last string in the URL is the SID. Alternatively, you can specify USE_SERVICE_NAME in the JNDI properties instead of using this option. See the "JNDI Connections and Session IIOP Service" chapter in either the Oracle8i CORBA or EJB Developer's Guides for more information. -version Shows the version. ##### Example Here is a sess_sh example. Open a session shell on the session namespace of the database orcl on listener port 2481 on host dbserver. sess_sh -user SCOTT -password TIGER -service sess_iiop://dbserver:2481:orcl  The sess_sh commands span several different types of functionality, which are grouped as follows: #### sess_sh Options ##### 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. • Give execute rights for /alpha/beta/gamma to SCOTT and NANCY. Note that the schemas are separated by a comma only. $ chmod +x SCOTT,NANCY /alpha/beta/gamma


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



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

%


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



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

1.0


#### whoami

Prints out the current user that logged into this session.

### Namespace Commands

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:

#### bind

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

##### Syntax

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

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

<JNDI_object_name>

The JNDI name that the object is bound to within the namespace. This is the name that is used to retrieve the bound object.

-context

The object to be bound is a JNDI Context or InitialContext.

-rebind

If the JNDI name already exists, replace the object that it is bound to with this object.

-class

Specify the class name of the bound object.

-factory

Specify the factory name for creating the object. JNDI uses this for creating the object.

-location

Specify the factory location if the default location is not used. This takes a JNDI URL. Refer to the JNDI specification for more information.

-string

Specify a String reference attribute for the object by the type name and value.

-binary

Specify a Binary reference attribute for the object by the type and a binary value. The given string value is converted into binary.

The following binds a CORBA IOR reference into the JNDI namespace. The object reference was stringified before the bind is executed and is substituted for the input argument $1. In addition, a binary reference attribute for the employee site number of 400 is also bound within the object. bind /test/employee -class employee.Employee -factory employee.EmployeeFactory -string EmpObjRef$1 -binary EmpNumber 400


#### bindut

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

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

##### Syntax

bindut <lookup_name> [options]
[-help | -h]
[-describe | -d]
[-version | -v]
[-rebind]
[-expprop]
[-host <hostname> -port <portnum> -sid <SID>]
[-url <db_url>]
[-g | -grant {<user> | <role>}[,{<user> | <role>}]...]
[-recursiveGrant | -rg | -rG {<user> | <role>}[,{<user> | <role>}]...]
[-user | -u <user>]
[-password | -p <password>]

##### Argument Summary

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

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

<lookup_name>

The JNDI name of the UserTransaction object

-help

Summarizes the tool's syntax.

-describe

Summarizes the tool's operation.

-version

Shows the tool's version.

-rebind

If the JNDI name for the UserTransaction object already exists, you must specify this option if you want it overwritten with this new object. Otherwise, no bind will occur for this option and an AlreadyBound exception is thrown.

-expprop

Specify this option only if host/port/sid options are specified. Designates how the transaction is propagated between objects. If an IIOP client invokes an IIOP server method, the transaction context is propagated implicitly for you. However, if your client uses JDBC or HTTP for communicating, the propagation context must be propagated explicitly. Specify this flag in the case of JDBC or HTTP communication.

-host <host> -port <port> -sid <sid>

These options specify the Oracle8i database that is acting as the two-phase commit engine. These are only necessary for any global transactions that use two-phase commit. You can either specify the two-phase commit engine location either through these options or within the -url option. The default value for -sid is ORCL.

-url <db_url>

This URL specifies the location of the Oracle8i database that is acting as the two-phase commit engine. You can specify the two-phase commit engine either through this option or by specifying each part of the URL separately within the four options mentioned above. This URL can be either JDBC Thin or sess_iiop URL.

-grant <user> | <role>

Grants read and execute rights to the sequence of <user> and <role> names. When rebinding any leaf nodes, replace the existing users/roles that have read/execute rights with the <user> and <role> names. To selectively change the rights of a UserTransaction object, use the sess_sh's chmod command. The sequence of user and role names must be a comma-separated list, containing no internal spaces.

Note: You must uppercase the schema name.

-recursiveGrant <user> | <role>

Grants read and execute permission like the -grant option to the designated object and to all contexts that the object exists within. If the context has a permission level of SYS, the grant for that context is ignored. You can specify either -grant or -recursiveGrant.

-user | -u <user>

Specifies user's name for connecting to the two-phase commit engine. This option is only required for two-phase commit scenario.

-password | -p <password>

Specifies user's password for connecting to the two-phase commit engine. This option is only required for two-phase commit scenario.

##### Example

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

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



The same command could be issued as follows:

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



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

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

bindut /test/myUT


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

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



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

#### bindds

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

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

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

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

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

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

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

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

##### Syntax

bindds <lookup_name> [options]
[-help | -h]
[-describe | -d]
[-version | -v]
[-dstype <datasource>]
[-host <hostname> -port <portnum> -sid <SID> -driver <driver_type>]
[-url <db_url>]
[-dblink <DBLINK>]
[-g | -grant {<user> | <role>}[,{<user> | <role>}]...]
[-recursiveGrant | -rg {<user> | <role>}[,{<user> | <role>}]...]
[-rebind]
[-user | -u <user>]
[-password | -p <password>]

##### Argument Summary

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

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

<lookup_name>

The JNDI name of the DataSource object

-help

Summarizes the tool's syntax.

-describe

Summarizes the tool's operation.

-version

Shows the tool's version.

-dstype <datasource>

The type of DataSource object that you are currently binding. Values can be one of the following:

• do not specify this option to bind an OracleDataSource

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

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

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

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

% bindds /test/ds1 -host dbsun.mycompany.com -port 2481
-sid ORCL -driver thin -dstype jta -dblink ds1db.oracle.com



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

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

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


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

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



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

#### getgroup

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

##### Syntax

getgroup <object_name> <group_name>

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

<object_name>

A JNDI name that is bound to an object.

<group_name>

A property group name, which was created by the setgroup command.

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

getgroup config wine

#### getproperties

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

##### Syntax

getproperties [-all] <object_name>

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

-all

Display all properties information including the reference information, such as the class, factory, and factory location.

<object_name>

A JNDI name that is bound to an object.

#### publish

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

#### removegroupentry

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

##### Syntax

removegroupentry <object_name> <group_name> <prop_name>

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

<object_name>

A JNDI name that is bound to an object.

<group_name>

A property group name, which was created by the setgroup command.

<prop_name>

The property name assigned to the group/object.

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

removegroupentry config wine type

#### setgroup

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

##### Syntax

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

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

<object_name>

A JNDI name that is bound to an object.

<group_name>

The property group name to be used for categorizing the given properties.

<prop_name>

The property name that has already been created with the setproperties command.

<prop_value>

The value for the property

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

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


#### setproperties

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

##### Syntax

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

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

<object_name>

A JNDI name that is bound to an object.

<prop_name>

The name of the property.

<prop_value>

The current value for the property.

The following example sets three properties for the config object:

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


### Dynamic Listener Endpoint Configuration Commands

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

#### regep

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

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


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

-verbose

Report the translation steps during execution.

-resolver <resolver>

-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

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',



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.

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

• Users have all of the same properties as principals

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

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

• the valid set of principals

• the types of principals that are handed to the server

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

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

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

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

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

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

#### Predefined Realms

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

create user "joe" identified by welcome;



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

#### Realm Management Overview

To create a RDBMS realm:

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



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

To remove a realm:

realm publish -w /myService -remove testRealm



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

To publish a custom realm:

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


#### Managing Principals Overview

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

To create a user:

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



To create a group:

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



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

To delete a user:

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



To delete a group:

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



To list users of a realm:

realm user -w /myService -realm testRealm1



To list groups of a realm:

realm group -w /myService -realm testRealm1



To add a principal to a group:

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



To remove a principal from a group:

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



To list principals within a group:

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



To query which groups a principal is member:

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



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

#### Resource Protection Overview

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

<authType>:<realmName>



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

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

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

Protecting paths to resources with protection schemes:

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



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

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



To remove the protection of a path:

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



To list all protected paths within a servlet context:

realm map -s /myService/contexts/myContext



To explicitly declare a path not to be protected:

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



To list all protected paths within a servlet context:

realm map -s /myService/contexts/myContext


#### Declaring Permissions

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

A permission declaration consists of several pieces:

• web service root

• realm within specified web service

• servlet context within specified web service

• principal within specified realm

• path to which the permission is to apply

• whether or not the permission being granted or denied

• HTTP actions being assigned

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

• GET

• POST

• PUT

• DELETE

• TRACE

• OPTIONS

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

realm perm -w /myService -realm testRealm1 -s /myService/contexts/myContext \
-n user1 -u /foo/index.html + get,post



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

realm perm -w /myService -realm testRealm1 -s /myService/contexts/myContext \
-n user1 -u /foo/* - put,delete



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

realm perm -w /myService -realm testRealm1 -s /myService/contexts/myContext \
-n user1 -u /foo/index.html +



To list all permissions for a user:

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


#### Declaring A Security Servlet

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

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

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

• Allow the the request

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

To create a security servlet:

realm secure -s /myService/contexts/myContext



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

To remove a security servlet:

rm /myService/contexts/myContext/httpSecurity



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

### realm

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

#### list

Lists the realms declared for the given web service.

The syntax is as follows:

realm list -w <webServiceRoot>



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

realm list -w /webservice


#### echo

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

The syntax is as follows:

realm echo [0 | 1]


• 0: Do not print any results of subsequent operations

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

realm echo 0


#### secure

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

The syntax is as follows:

realm secure -s <servletContextPath>



where servletContextPath is the servlet context to operate upon.

#### map

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

The syntax is as follows:

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


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

-s servletContextPath

The servlet context to operate upon. If nothing else is supplied, this will list all URL-Scheme mappings for the given servlet context.

-add | -a <path>

The path for which a mapping will be added, or edited if the mapping already exists.

-remove | -r <path>

The path for which a mapping will be removed.

-scheme auth:realm

The protection scheme to use for the given mapping.

#### publish

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

The syntax is as follows:

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


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

-w <webserviceRoot>

The web service to operate upon.

-add | -a <realmName>

The name to use for creating the realm within the web service.

-remove | -r <realmName>

The name of the realm to remove from the web service.

-type <realmType>

Specifies the type of realm to publish. One of RDBMS, DBUSER, JNDI. If not specified, the default value is RDBMS.

#### user

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

The syntax is as follows:

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


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

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