9
Working with Wireless Edition XML

This document describes the XML formats that Wireless Edition uses to represent service content and its internal objects. Each section of this document presents a different topic. These sections include:

9.1 Why XML?

Extensible Markup Language (XML) is a standards-based language for creating structured documents. In an XML document, markup tags describe the content of the document, rather than its visual presentation:

<account_dept>
   <employee>
      <emp_name>Scott</emp_name>
      <emp_ID>20</emp_ID>
   </employee>
   <employee>
      <emp_name>Laura</emp_name>
      <emp_ID>30</emp_ID>
   </employee>
</account_dept>

Because it isolates content from presentation, XML is an ideal language for exchanging data between diverse platforms. Transformers, in the form of XSLT stylesheets or Java classes, render the data in the format best suited to a particular platform.

9.2 Oracle XML Parser

The Wireless Edition uses the Oracle XML Parser for Java. The parser supports the W3C XML 1.0 Standard Recommendation. While the parser supports various character encoding standards, the Wireless Edition uses UTF-8 character encoding.

The parser requires a version attribute in the XSL stylesheet, while prior versions do not. If you have created your own result and/or device transformers, you have to include the XML version number in the XSL stylesheet.

For example:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

Without the version attribute, you will receive a runtime error in the Wireless Edition log file in the form of "missing version attribute from the stylesheet."

The Oracle XML Parser exposes two interfaces:

The Document Object Model (DOM) Level 1 API, as specified in the W3C Recommendation
The Simple API for XML 1.0 (SAX) interface

To improve performance and usability, the APIs reside in a single archive. The Oracle XML Parser is provided as a .jar file comprising the following four packages:

oracle.xml.parser
org.w3c.dom
org.xml.sax
org.xml.sax.helpers

9.3 Wireless Edition XML Formats

In Wireless Edition, XML serves two primary functions: to define the format of service content and to define repository objects. The content formats include the following:

Simple Result
Adapter Result

Note:

Wireless Edition XML is intended to be extensible. You can modify the DTDs that Wireless Edition provides, or create your own. This enables you to implement specialized functionality or to customize Wireless Edition object characteristics.

The Simple Result DTD defines the format of deliverable service content. Adapter Result is an intermediary format for service content.

The object formats include:

Provisioning DTD
Repository XML

The Provisioning DTD defines the structure of user objects. You can use the Provisioning DTD to transfer user information between Wireless Edition and an external provisioning system.

Repository XML is not defined by a DTD, since repository objects can have extended attributes which cannot be validated. An extended attribute can be an XML document, such as XSLT, or a Java program. Transformer and adapter objects have extended attributes.

Symbols

This document contains references for the Wireless Edition XML formats. The references list the attributes and subelements for every element in the Simple Result and Provisioning DTDs. It uses the following DTD symbols to indicate the usage of subelements.

Symbol	Meaning
+	Indicates that a subelement must appear at least once within the parent element. If the plus sign appears after a parenthetical grouping of subelements, then at least one of the listed subelements must appear within the parent element.
?	Indicates that a subelement may appear only once or not at all.

Table 9-1 DTD Symbols

Symbol Meaning

+

Indicates that a subelement must appear at least once within the parent element. If the plus sign appears after a parenthetical grouping of subelements, then at least one of the listed subelements must appear within the parent element.

?

Indicates that a subelement may appear only once or not at all.

9.4 Adapter Result Format

The Adapter Result (also called raw result) format is a simplified, user interface-independent content format. Adapter Result documents must be converted to Simple Result format prior to conversion to their final target format. This intermediary step, called preprocessing, enables you to apply a service-specific transformation to the content returned by an adapter. Result transformers convert Adapter Result documents. Adapter Result format provides an efficient means of exchanging data between chained services.

Note:

Both standard adapter services based on the Web Integration adapter, and user-designed custom adapters can use the Adapter Result format.

The Wireless Edition does not specify an Adapter Result DTD. You can define the content any way you like. While the content is not validated by Wireless Edition, it must be well-formed. The only element Wireless Edition requires in Adapter Result content is the <AdapterResult> tag. The remaining structure of the content is important only to the transformer that processes it. For example:

<AdapterResult>
   <Value name="target">
      /parm/epayment/amex
   </Value>
   <Value name="creditcard">
      Please enter your credit card no:
   </Value>
   <Value name="expdate">
      Please enter expiration date:
   </Value>
</AdapterResult>

The sample uses a single element type, the Value tag. The first Value element contains a link to another service in the Wireless Edition repository tree (using JNDI-naming format).

A result transformer converts the Adapter Result content as follows:

<SimpleResult>
   <SimpleForm link="/parm/epayment/amex">
      <SimpleFormItem name="creditcard" description="Please enter 
                        your credit card no:"/>
      <SimpleFormItem name="expdate" description="Please enter 
                        expiration date:"/>
   </SimpleForm>
</SimpleResult>

9.5 Simple Result Format

The elements in the Simple Result DTD represent the elements of an abstract user interface. These include text items, menus, forms, and tables. When converting source content to Simple Result format, adapters map the source content to the appropriate Simple Result element. Likewise, when converting the content from Simple Result format to the target format, transformers map the Simple Result elements to the appropriate elements in the target format.

Appendix A, "Simple Result DTD Reference" describes the content of the Simple Result DTD in detail.

9.6 The Wireless Edition Repository

The Wireless Edition repository holds the persistent Wireless Edition objects, such as end users, user groups, services, adapters, and transformers. Internally, Wireless Edition stores these objects as database objects in an Oracle8i database. In most cases, you create or modify repository objects using the Service Designer. However, you can also export, modify, and import the repository as an XML file, using utilities provided by Wireless Edition. To use these utilities, you must understand the XML structure of the repository, as described in this section.

Wireless Edition provides an XML editor that you can use to modify the XML definitions of objects directly in the repository. You can also modify objects in an XML file. To do so, you export the repository using LoadXml or the download utility, and edit the resulting XML file. When finished, you re-import the file into the repository, committing your changes. See Section 9.9, "XML Tools" for more information on using the XML Editor or the LoadXML utility.

Repository XML enables you to distribute populated repositories easily. It also enables you to access the repository programmatically, and to integrate Wireless Edition with other systems.

Important:

Changes made directly to the repository XML are not validated by the Service Designer. Use caution to ensure that the changes you make do not cause conflicts or errors.

9.7 Provisioning DTD

The Provisioning DTD defines the XML format for Wireless Edition users. You can use it to import users into the repository programmatically, or to import a large number of users at once. The Provisioning DTD declares only two elements:

PUSR_LIST
PUSR

PUSR_LIST Element

The Wireless Edition user list.

Note:

PUSR_LIST is a subelement of PanamaObjects, the root provisioning element.

Subelement

PUSR+

PUSR Element

The PUSR element represents a Wireless Edition user. It includes the following attributes:

externalId

A user's unique identifier in an external provisioning system. For example, this may be a telephone number or an account number. You can use this attribute to tie a Wireless Edition user to another account. This is an optional attribute.

display name

User's display name. This is an optional attribute.

enabled

Indicates whether the user is enabled. Possible values are:

true
false

password

The user's password. In exported repositories, this appears in encrypted form. For uploading, this can be either an encrypted or plain text password. If the string is greater in length than 32 characters, and all uppercase, Wireless Edition assumes that it is an encrypted password.

administrator

Indicates whether the user has administrator privileges. Possible values are:

true
false

designer

Indicates whether the user has designer privileges. Possible values are:

true
false

name

The Wireless Edition user identifier.

anonymous

Indicates whether the user is anonymous. Possible values are:

true
false

userRoot

The users home folder.

group

The name of the group to which the user belongs.

9.8 Repository XML Reference

The XML file you import into the repository must contain appropriately formatted repository objects. Since objects in the repository, such as transformers, can have extended attributes, Wireless Edition does not validate repository XML documents. Therefore, Wireless Edition does not define a repository DTD.

Your XML definition should use the following elements for repository objects.

PanamaObjects Element

The PanamaObjects element is the root element.

Subelements

PGRP_LIST

PUSR_LIST

TRAN_LIST

ADAP_LIST

AGEN_LIST

PSRV_LIST

TRAN_LIST

LDEV_LIST

PGRP_LIST Element

The Wireless Edition group list.

Subelements

PGRP

PGRP Element

The PGRP element represents a Wireless Edition user group.

Attributes

name

The name of the element. This is an optional attribute.

PUSR_LIST Element

The Wireless Edition user list.

Subelements

PUSR

PUSR Element

The PUSR element represents a Wireless Edition user.

Attributes

externalId

External identifier. This is an optional attribute.

display name

User's display name. This is an optional attribute.

enabled

Indicates whether the user is enabled. Possible values are:

true
false

password

The user's password. In exported repositories, this appears in encrypted form. For uploading, this can be either an encrypted or plain text password. If the string is greater in length than 32 characters, and all uppercase, the Wireless Edition assumes that it is an encrypted password.

administrator

Indicates whether the user has administrator privileges. Possible values are:

true
false

designer

Indicates whether the user has designer privileges. Possible values are:

true
false

name

The user name.

anonymous

Indicates whether the user is anonymous. Possible values are:

true
false

userRoot

The user's home folder.

group

The name of the group to which the user belongs.

TRAN_LIST Element

The Wireless Edition transformer list.

Subelements

XTRA

JTRA

XTRA Element

The XTRA element represents an XSLT Wireless Edition transformer.

Attributes

name

The name of the transformer.

Subelements

EXT_ATTR

EXT_ATTR Element

Extended attribute. The actual XML element that comprises the XSLT implementation.

JTRA Element

The JTRA element represents a Wireless Edition Java transformer.

name

The name of the element.

className

The complete class name including attributes.

LDEV_LIST Element

The Wireless Edition logical device list.

Subelements

LDEV

LDEV Element

The LDEV element represents a Wireless Edition logical device.

Attributes

needsURLCaching

Indicates whether the logical device needs URL caching. If true, URL-encoding request parameters are cached on the server and only small pointers are encoded within the URL that is sent to the logical device. Use this option for devices with limited memory. Possible values are:

true
false

name

The name of the logical device.

mimeType

MIME type.

encoding

Character encoding format, such as UTF-8 or ASCII.

defaultTransformer

The default transformer used by the logical device.

prolog

A string inserted in front of the output from the transformer, such as an XML document type.

softkeys

The number of softkeys (used only for phones).

ScreenRows

The number of rows on the screen (useful for breaking text in pages).

ScreenColumns

The number of columns on the screen.

ScreenWidth

The width of the screen in points.

ScreenHeight

The height of the screen in points.

ADAP_LIST Element

The Wireless Edition adapter list.

Subelements

ADAP

ADAP Element

The ADAP element represents a Wireless Edition adapter.

valid

Indicates whether the adapter is valid (accessible). Possible values are:

true
false

name

The adapter name.

className

The Java class name.

PSRV_LIST Element

The Wireless Edition service object list.

Subelements

FOLD

LINK

MAST

BOMA

FOLD Element

The FOLD element represents a Wireless Edition service folder.

Attributes

url

The location of the service folder, relative to the root URL of the service tree. This attribute is set by the Wireless Edition system. It cannot be edited.

name

The service folder name.

visible

Indicates whether the folder is visible. Possible values are:

true
false

valid

Indicates whether the folder is valid (available). Possible values are:

true
false

folder

The master folder where the service folder is located.

owner

The user name of the folder owner.

areaId

A value which determines whether a folder is visible, depending on a user's physical location.

group

The user group that is allowed to access the folder. This is an optional attribute.

LINK Element

The LINK element represents a Wireless Edition service link.

Attributes

url

The location of the service link, relative to the root URL of the service tree. This attribute is set by the Wireless Edition system. It can not be edited.

name

The service link name.

visible

Indicates whether the link is visible. Possible values are:

true
false

valid

Indicates whether the link is valid (accessible). Possible values are:

true
false

folder

The folder where the link is located.

owner

The user name of the link owner.

service

Name of the linked service.

MAST Element

The MAST element represents a Wireless Edition master service.

Attributes

url

The location of the master service, relative to the root URL of the service tree. This attribute is set by the Wireless Edition system. It can not be edited.

name

The master service name.

visible

Indicates whether the master service is visible. Possible values are:

true
false

valid

Indicates whether the master service is valid (accessible). Possible values are:

true
false

folder

The folder where the master service is located.

owner

The user name of the master service owner.

areaID

A value identifying the geographic location of the user.

cost

The amount charged for using the service.

adapter

The adapter used by the master service.

BOMA Element

The BOMA element represents a bookmark.

Attributes

url

The location of the bookmark, relative to the root URL of the service tree. This attribute is set by the Wireless Edition system. It can not be edited.

name

The bookmark name.

visible

Indicates whether the bookmark is visible. Possible values are:

true
false

valid

Indicates whether the bookmark is valid (accessible). Possible values are:

true
false

folder

The folder where the bookmark is located.

href

The URL of the external datasource.

AGEN_LIST Element

The Wireless Edition user agent list.

Subelements

AGEN

AGEN Element

The AGEN element represents a Wireless Edition user agent.

address

The address of the user agent.

name

The name of the user agent.

user

The Wireless Edition user associated with the user agent.

logicalDevice

The logical device.

uniqueName

An identifying attribute set by Wireless Edition.

9.9 XML Tools

Wireless Edition includes the LoadXml tool and upload and download utilities for working directly with the XML interface. See the Oracle9i Application Server Wireless Edition Configuration Guide for more information.

9 Working with Wireless Edition XML

9.1 Why XML?

9.2 Oracle XML Parser

9.3 Wireless Edition XML Formats

Symbols

9.4 Adapter Result Format

9.5 Simple Result Format

9.6 The Wireless Edition Repository

9.7 Provisioning DTD

PUSR_LIST Element

Subelement

PUSR Element

9.8 Repository XML Reference

PanamaObjects Element

Subelements

PGRP_LIST Element

Subelements

PGRP Element

Attributes

PUSR_LIST Element

Subelements

PUSR Element

Attributes

TRAN_LIST Element

Subelements

XTRA Element

Attributes

Subelements

EXT_ATTR Element

JTRA Element

LDEV_LIST Element

Subelements

LDEV Element

Attributes

ADAP_LIST Element

Subelements

ADAP Element

PSRV_LIST Element

Subelements

FOLD Element

Attributes

LINK Element

Attributes

MAST Element

Attributes

BOMA Element

Attributes

AGEN_LIST Element

Subelements

AGEN Element

9.9 XML Tools

9
Working with Wireless Edition XML