8
Utilities

Utilities describes the XML utilities used for management and deployment. Each section of this document presents a different topic. These sections include:

• Section 8.1, "System Password Encryption/Decryption"

• Section 8.2, "LoadXml"

• Section 8.3, "Upload and Download Utilities"

• Section 8.4, "Xslt"

• Section 8.5, "CopyObjects"

8.1 System Password Encryption/Decryption

The Wireless Edition database password for the repository is stored in clear text in the System.properties file by default. The password can be encrypted by running the following tool to modify the db.connect.string:

encryptPassword.sh WE_HOME/server/classes/oracle/panama/core/admin

Then set the following property in the System.properties file:

passwordEncrypted=true

8.1.1 Extensibility

The SystemPasswordEncryptionHook.class identifies the encryption algorithm. To provide extensibility, the class can be used to invoke a user's algorithm in place of the default algorithm.

The default setting is:

locator.SystemPasswordEncryptionHook.class=
     oracle.panama.rt.common.SystemPasswordEncryption

To use an alternate encryption algorithm, implement the following interface:

public interface SystemPasswordEncryptionHook {
  /** Encrypts the text
    * @param text the text to be encrypted
    * @return the encrypted text
    */
public String encrypt(String text);

  /** Decrypts the encrypted text
    * @param encryptedText the encrypted text
    * @return the decrypted text
    */
	public String decrypt(String encryptedText);
}

This allows you to replace the default algorithm, for example:

locator.SystemPasswordEncryptionHook.class=
     oracle.panama.MyEncryption

8.2 LoadXml

The LoadXML utility allows you to download and upload Wireless Edition repository objects as XML files.

LoadXml reads from stdin and writes to stdout. All logging and error messages are written to stderr. The XML in the file you import with LoadXml must conform to the Repository XML.

The upload function performs the following:

1. Checks for the objects in the repository by logical unique name.

2. Loads all dependencies.

3. If the objects exist in the repository, LoadXml updates the objects.

4. If the objects do not exist, LoadXml creates them.

5. After each object type is successfully loaded, LoadXml performs a commit. The commit includes all referenced objects (dependencies).

In the unload XML result, all objects have an attribute called _objectId; this is the system unique object key. You must look up objects by unique name attribute and not the object key. If you start the program without giving an option, all options are listed.

LoadXML imports and exports the repository identified by the database connect string in the System.properties file. In the development environment, this file is located in the WE_HOME/server/classes/oracle/panama/core/admin directory.

Wireless Edition does not validate the XML file you import into the repository with LoadXml. To avoid errors, work in an XML file that you have exported from the repository. This gives you a "known good" Repository XML framework for adding, removing, and modifying individual elements.

Syntax

oracle.panama.core.util.LoadXml [-l username/password] [-x[adgnstu] [expr]] [-c#
[-p]] [-r rmi://rmi-host:port/server_name]

Options

The LoadXml utility accepts the following options:

Table 8-1 LoadXml Utility

Option	Description
-l usr/pwd	Log on to Wireless Edition using a user name and password. If no administrator is defined in the system, the program allows any user to log on. Otherwise, the user must be an administrator to log on.
-x	Unload all repository data to stdout. The data can be filtered by adding these options to the -x option.
-a	Adapter filter.
-d	Logical device filter.
-g	Group filter.
-n	Agent filter.
-s	Service filter.
-t	Transformer filter.
-u	User filter.
expr	Name expression filter. This option can include wildcards, such as: [*%?_].
-c#	Upload repository data read from stdin. The argument # is a number that, if set, causes a commit after the specified number of objects are uploaded. An argument of 0 causes a commit after a complete load of the XML data.
-p	This option activates provisioning of user data when uploading. This mode is only used with the -c option. The provisioning upload handles the provisioning DTD, and makes it possible to create, enable, disable, and remove users in the repository. This mode always creates new users. If the createUserRoot attribute is set to YES, LoadXml creates a root folder for each user. The provisioning upload uses streaming to load users, and therefore does not resolve dependencies.
-r	This option ensures that the repository and object cache for a running instance of Wireless Edition are current. The following is sample syntax: -r rmi://stpc250.us.oracle.com:2008/PanamaServer -c0 < bootstrap.xml rmi-host is the machine on which the RMI registry is running. port is the port at which the registry is listening. server-name is the name of the Wireless Edition instance. port and server-name can be found in the Rmi.properties file.

Unload Example

In this example, XML data is written to standard output.

java oracle.panama.core.util.LoadXml -l adm/adm -x > outputfile.xml

Upload Example

In this example, XML data is read from standard input. It must contain all referenced objects.

prompt$ java oracle.panama.core.util.LoadXml -l adm/adm -c0 < inputfile.xml 

8.3 Upload and Download Utilities

You can use the upload and download utilities to import and export the Wireless Edition repository as an XML file. These utilities invoke LoadXml. They are located in the WE_HOME/sample directory of your development environment. You invoke upload from a command prompt as follows:

upload.bat repository.xml

This loads the contents of the file repository.xml into the repository. It accesses the repository specified by the connect string in the client-side System.properties file.

To download a repository:

download.bat repository.xml

This places the contents of the repository in a file named repository.xml.

Note: Please make sure the -l option has been properly specified in either the upload.bat or upload.sh script file.

The xmlloader.properties file specifies the mapping between the object names and their handler Java classes. The objects are specified as fully-qualified from the root, as dot-separated names. For example, the PanamaObjects property file is specified as oracle.panama.util.XMLLoader.PGRPHandler.

The System.properties file has the following entries to determine behavior.

Table 8-2 Behaviors for the XML Loader in the Systems.property File

Entry	Behavior
xmlloader.pathExpression	Specifies the regular expression which determines the path of the objects that you intend to upload and download.
xmlloader.activityLog	Specifies the location of logging activity.
xmlloader.errorLog	Specifies the location for logging errors.
xmlloader.createUserRoot	Determines whether a root folder is to be created for each user when uploading provisioning data.
xmlloader.commitFrequency	Frequency in seconds to commit the uploaded information to the back-end repository.
xmlloader.replaceObjects	Determines whether a pre-existing objects should be overwritten.

Note: 'All the XML Loader parameters in the System.properties file are default values that are overwritten by the XML Loader API.

8.4 Xslt

The Xslt utility is a tool you can use to test stylesheets. Xslt uses the XML DOM parser and the XSL processor included with the Oracle XML processor. You can use Xslt to apply the stylesheets you create to any XML document.

Xslt, which is a command-line utility, reads from standard input and writes its results to standard output.

Synopsis

oracle.panama.util.Xslt [stylesheet]

Options

The Xslt utility takes the following option:

Table 8-3 Options for the Xslt Utility

Option	Description
stylesheet	The XSL stylesheet that the utility applies to the XML document.

Xslt Example

java oracle.panama.util.Xslt mystylesheet.xsl < myxml.xml

8.5 CopyObjects

The CopyObjects utility allows you to copy services from one Wireless Edition site to one or more other sites. You can use this utility, for example, to deploy services from a testing and development environment to production servers.

CopyObjects sends services to target servers as XML elements. It takes a folder object as a command-line argument. To copy a service, therefore, you must first place the service in a folder. When invoked, CopyObjects copies the folder and all its contents to the target Wireless Edition sites you specify at the command line.

Requirements

All source and target Wireless Edition servers must have the Wireless Edition RMI server running.

The basic configuration of adapters and transformers must be the same on the source and target servers. CopyObjects only sends services, links, and folders. It does not send configuration data.

Syntax

oracle.panama.core.util.CopyObjects [-f folder] [-s source ][targets...]

Options

The CopyObjects utility takes the following options:

Table 8-4 Options for the CopyObjects Utility

Option	Description
-f folder	The name of an existing folder in the source system.
-s source	The source Wireless Edition server. Specify the source in the format: username/password@//hostname:port/servername
targets	The target Wireless Edition servers. Specify targets in the format: username/password@//hostname:port/servername

Example

This example copies a folder and its content from a local server to production sites at m1 and m2.

java oracle.panama.core.util.CopyObjects \  
           -f /master/finance \  
           -s user/pw@//:2008/WEServer \  
              user/pw@//m1:2008/WEServer \  
              user/pw@//m2:2008/WEServer