3
Wireless Edition Services

This document describes how to create and manage the services of the Oracle9i Application Server Wireless Edition using the Serivce Designer. Each section of this document presents a different topic. These sections include:

• Section 3.1, "Overview"

• Section 3.2, "Using the Service Designer"

• Section 3.3, "Creating a Master Service"

• Section 3.4, "Creating a Location-Based Service"

• Section 3.5, "Modifying a Master Service"

• Section 3.6, "Deleting a Master Service"

• Section 3.7, "Creating a Folder"

• Section 3.8, "Deleting a Folder"

• Section 3.9, "Creating a Service Alias"

3.1 Overview

Services enable end users to access the functionality of the Wireless Edition adapters. Services represent the link between the content source and the delivery target. They tie a specific adapter to the logical devices in the Wireless Edition repository.

Services also define how users access the adapter. They can restrict or grant user access to the adapter's parameters. Services can set default values for a parameter, they can enable users to set a default, or they can hide the parameter from users altogether.

The following repository objects encapsulate and manage the Wireless Edition services:

• Master services

• Aliases

• Folders (or service trees)

Master Services

Master services provide the actual implementation of the service. They specify the adapter used for the service and any service-specific parameters. By mapping an adapter to device transformers, master services link the Wireless Edition content sources to the delivery platforms. Each master service is based on one adapter. A master service creates its own instance of the adapter it uses. Therefore, several services can use the same type of adapter, and each can pass its own service-specific argument values.

The Wireless Edition end users typically invoke a master service by clicking on a menu item from their device. The information returned by the master service can be text, such as a movie review, or an application, such as an airline booking system. While a user request usually invokes a master service, a scheduled job can also invoke a master service.

Location-Based Sevices

The Wireless Edition enables developers to assign a location to a service, making the service location-based. The Wireless Edition supports two types of location-based services, location-based services that are visible to users only at certain locations and services whose content depends upon the physical location of the user. For example, Wireless Edition users located in San Francsico would see content related to San Francisco, such as lists of restaurants or business located in San Francisco. The Wireless Edition supports content-specific location-based services through customized adapter implementation and location-aware runtime support. For more information on creating location-based services that are visible only at specific locations, see Section 3.4.1 and Section 4.4, "Creating Location-Based Master Services and Folders" in Chapter 4, "Using the Region Modeling Tool". For information on creating location-based services that display content specific to the user's location, see Section 4.5, "Creating Location-Based Services with Location-Specific Content" in Chapter 4, "Using the Region Modeling Tool".

Aliases

An alias is a pointer to a master service, folder, bookmark, or to another alias. Aliases are useful for distributing access to a master service among many users and groups. End users can access a master service only if the master service, or an alias to the master service, appears in a service tree they own or that a group they are a member of owns. Aliases can set parameter values that override values set at the master service.

Folders

Folders group services and make them available to end users. Every user has a "home" folder. This folder contains the services, ususally referenced by an alias, that the user can access. A user can also access any service in a folder owned by the group to which the user belongs.

You can manage service objects (master services, aliases, and folders) using the Service Designer. The Service Designer provides a tree view of the Wireless Edition repository. The repository tree includes a Master Services folder and a Service Trees folder for managing services. You can create service objects in either folder. In most cases, however, you should place folders and master services in the Master Services root folder, and user- and group-owned folders and aliases in the Service Trees root folder.

3.2 Using the Service Designer

The Service Designer is a visual interface for implementing and managing the objects in the Wireless Edition. The Service Designer enables you to create and modify Wireless Edition objects, including adapters, transformers, and services.

Figure 3-1 The Service Designer

Text description of the illustration srv_svd1.gif

The Service Designer provides a tree view of the Wireless Edition repository. The tree shows Wireless Edition object classes, such as adapters and transformers, as folders or branch nodes. It shows instances of those classes, such as the WML 1.1 transformer, as objects, or leaf nodes.

Note: For performance reasons, the default tree view in the Service Designer does not display more than 100 objects of any type. This, however, can be configured in the ptgsd.properties file.

3.2.1 Starting the Service Designer

To start the Wireless Edition Service Designer:

1. From the Start menu, point to the Oracle for Windows NT menu item.

2. Click Wireless Edition, then Service Designer. The Log In dialog appears. Complete the Log In dialog as follows:
   1. Enter your user name (for example, Administrator)

   2. Enter your password (for example, manager)

   3. In the location field, specify the URI (Uniform Resource Identifier) of the repository that you want to develop. You can connect to the Wireless Edition server using RMI. The value you enter in the Location field determines the connection mode.

Note: You cannot connect directly to the Wireless Edition repository using in-process connection. You should use an RMI connection.

3.2.1.1 RMI Connection

To connect to the repository through the Wireless Edition server, the RMI listener must be running on the Wireless Edition server. By default, the RMI listener is started when you start the Wireless Edition server.

In the Location field of the Log In dialog, enter the URI of the Wireless Edition server in any of the following formats:

• rmi://hostname:port/servername

• rmi://hostname:port

• rmi://hostname

• rmi://:port/servername

• rmi://:port

• //hostname:port/servername

• //hostname:port

• //hostname

• //:port/servername

• //:port

• hostname:port/servername

• hostname:port

• hostname

• :port/servername

• :port

The default port number and server name are:

• Port: 2008

• Server name: PanamaServer

You can modify these defaults in the oracle.panama.core.admin.Rmi.properties file. The System.properties file identifies the default RMI listener used as follows:

locator.request.daemon.classes=oracle.panama.core.rmi.server.ServerImpl 

3.2.2 Creating Objects

You can create an object in the Service Designer as follows:

1. In the repository tree, highlight the master service folder.

Note: Before using the Service Designer to create a master service, you must first use the Web Integration Server to publish the service interface to the repository tree.

2. Right-click the class or folder. A pop-up menu appears with menu items for creating objects.

3. Click the appropriate menu item for creating the new object.

The Service Designer then presents a form, or a sequence of forms, that lets you configure the object. You can navigate through the forms by clicking the Next or Previous button. When you have finished configuring the master service, click the Finish button.

3.2.3 Modifying Objects

When you highlight an object in the repository tree, the right panel displays the object's properties. If an object has more than one property panel, you can navigate between panels by clicking the tabs at the top of the panel.

You can modify an object by making changes directly to the properties in the panel. To save your changes, click the Apply button. This saves the changes you have made to any of the object's panels, not just the current panel.

To cancel the changes you have made to an object since last saving, click the Revert button. This restores the object to its prior state. If you make changes to an object, but click another object in the repository before clicking Apply, the changes to the object do not take effect.

3.2.4 Deleting Objects

To remove an object from the repository:

1. Highlight the object in the tree view and right-click.

2. In the pop-up menu, select the menu item for deleting the object.

3. Confirm the action.

You cannot delete an adapter used by a master service. If you delete a master service that is referenced by aliases, Service Designer deletes the aliases as well.

3.2.5 Flagged Objects

Flagged objects appear in red type in the repository tree. The Wireless Edition flags objects that are specified as not valid or not visible. Specifying an object as not valid or not visible prevents its use. You may choose to disable an object, for example, while it is under development or testing.

Figure 3-2 Flagged Objects in the Repository Tree

Text description of the illustration srv_srvt.gif

3.2.6 Refreshing the Repository View

The Service Designer caches object information. If multiple Service Designer users work in the same repository concurrently, the object view for each user may not be up-to-date with the state of the repository. To retrieve the latest state of the repository, click the refresh icon on the toolbar.

3.2.7 Object Identifiers

Each object in the Wireless Edition repository is identified by a unique object ID. You can see the object ID for an object by moving the mouse over the object. The object ID helps you to identify the object when you access the repository with another tool, such as the Wireless Edition XML Editor.

3.3 Creating a Master Service

The Service Designer provides you with two methods of creating a master service in the Wireless Edition repository: you can use the Service Designer itself as described in Section 3.2.2, "Creating Objects", or through the Master Service Creation Wizard. Using the Wizard, you can successfully create a master service by following a series of steps. The Wizard provides you with a separate screen for each step, presenting the creation of a master service as a sequence. When you compete this sequence, you complete a master service. This document describes devotes a section for each step of the master service creation sequence. These sections include:

• Section 3.3.1, "Step 1: Selecting or Creating a Service Folder"

• Section 3.3.2, "Step 2: Setting the Master Service Properties"

• Section 3.3.3, "Step 3: Selecting an Adapter"

• Section 3.3.4, "Step 4: Setting the Init Parameters"

• Section 3.3.5, "Step 5: Setting the Input Parameters"

• Section 3.3.6, "Step 6: Setting the Output Parameters"

• Section 3.3.7, "Step 7: Creating the Result Transformer (Optional)"

• Section 3.3.8, "Step 8: Setting the Device Transformer (Optional)"

The Cancel, Help, Back, and Next buttons appear at the bottom of each of the Service Creation Wizards screens. The Back and Next buttons navigate you through the service creation sequence. Clicking the Next button takes you to the next screen, clicking the Back button takes you to the previous screen. Selecting the Cancel button closes the Master Service Creation Wizard and sets all conditions back to their original state.

After you select the Master Service Creation Wizard option from the Tools menu of the Service Designer, the Welcome screen appears. Click Next to move to the Select Service Folder screen.

3.3.1 Step 1: Selecting or Creating a Service Folder

To select a service folder, click the radio button for Select a Service Folder. Click the desired folder from the tree view and then click Next.

Creating a New Service Folder

If you wish to create a new service folder, click the Create a Service Folder radio button and then click Next.

Figure 3-3 The Select Folder Screen

Text description of the illustration srv_ssf1.gif

The Create New Folder screen appears, which prompts you to select a parent folder and then create a new service folder as a subfolder of that parent folder.

Figure 3-4 The Create New Folder Screen

Text description of the illustration srv_cnf2.gif

The Create New Service Folder screen enables you to configure the new service folder by entering values for the following parameters:

Table 3-1 Parameters for the Create New Service Folder Screen

Parameter	Value
Name	The name of the service folder. The service folder name must be a unique name in the parent folder.
Valid	Select the Valid check box to enable the service folder.
Visible	Select the Visible check box to make the service folder accessible to users.
SeqNo	The integer value that you enter in this field lets you alter the order in which services and folders appear on output devices. By default, these appear in order by sequence number, then by name. You can enter values in the sequence fields to rearrange the order in which the services and folders appear.
Browse	Clicking this button invokes the Region Modeling Tool. The Region Modeling tool enables you to assign a region to a service folder, making the folder location-based.
AreaID	The integer value retrieved by the browse function allows you to specify whether a service can be made visible based on a user's physical location. This enables you to implement a location-specific service. This is an optional value. To use this parameter, you implement the requestBegin()method in the ParmHook (request manager) interface. requestBegin() is called every time that the Wireless Edition receives a user request. You can place logic in this method that invokes an external position system. requestBegin() then passes the result in the request object. When the Wireless Edition invokes the service, it calls isRuntimeVisible(), passing it the user's position. You can test the position against the Area ID configured for the master service in isRuntimeVisible() to determine whether to make the service available.
Description	An optional description of the service folder.

Click Next after you have entered the desired values. The Selecting Folder screen reappears with the Select a Service Folder radio button selected (the default setting). Select the folder you created from the hiearchy and then click Next. The Setting Service Properties screen appears.

Note: The Master Service Creation Wizard prevents you from proceding if you enter an invalid value.

Figure 3-5 The Setting Service Properties Screen

Text description of the illustration srv_ssp1.gif

3.3.2 Step 2: Setting the Master Service Properties

The Setting Service Properties screen enables you to configure properties for the master service by entering values for the following parameters:

Table 3-2 Configuration Properties for the Master Service

Parameter	Value
Name	The name of the master service.
Valid	Select the Valid check box to enable the master service.
Visible	Select the Visible check box to make the master service accessible to users.
SeqNo	The integer value that you enter in this field lets you alter the order in which services and folders appear on output devices. By default, these appear in order by sequence number, then by name. You can enter values in the sequence fields to rearrange the order in which the services and folders appear.
Browse	Clicking this button invokes the Region Modeling Tool. The Region Modeling tool enables you to assign a region to a service folder, making the folder location-based.
AreaID	The integer value retrieved by the browse function allows you to specify whether a service can be made visible based on a user's physical location. This enables you to implement a location-based service. This is an optional value. To use this parameter, you implement the requestBegin()method in the ParmHook (request manager) interface. requestBegin() is called every time that the Wireless Edition receives a user request. You can place logic in this method that invokes an external position system. requestBegin() then passes the result in the request object. When the Wireless Edition invokes the service, it calls isRuntimeVisible(), passing it the user's position. You can test the position against the Area ID configured for the master service in isRuntimeVisible() to determine whether to make the service available.
Cost	The cost-per-service access. If you set a value for this parameter, and configure the System.properties file to enable transaction logging, the Wireless Edition writes billing information to a transaction log. This is an optional value.
Description	An optional description of the master service.

After you have entered the desired values, click Next. The Adapter Selection screen appears.

Figure 3-6 The Selecting Adapter Screen

Text description of the illustration srv_sad1.gif

3.3.3 Step 3: Selecting an Adapter

The Adapter Selection screen displays the adapters available in the Wireless Edition repository. Click the desired adapter (for example, the SQLAdapter) and then click Next. The Initial Parameters screen appears.

3.3.4 Step 4: Setting the Init Parameters

The Init Parameters screen contains the init parameters for the adapter you chose in Step 3. Enter the values for these parameters in the adjacent fields and then click Next. The Input Parameters screen appears.

3.3.5 Step 5: Setting the Input Parameters

The Input Parameters Screen displays the input parameters for the adapter you selected in Step 3. The Master Service Creation Wizard queries the adapter definition to determine the parameters that appear in this screen. For this example, the Input Parameters screen displays the parameters for the Provisioning adapter. Every Wireless Edition parameter has the following attributes:

Table 3-3 Attributes of the Wireless Edition Adapters

Parameter	Value
Name	The name of the input parameter. The Wireless Edition Service Creation Wizard sets the name of the input parameter by querying the adapter definition.
Caption	The caption is the label that the Wireless Edition uses for the parameter when prompting for user input.
Comment	In the case of master services based on the Web Integration adapter, the Wireless Edition automatically populates this cell with the name of the WIDL service that uses the parameter. For services based on other adapters, you can use this column to document the parameter. The comment is only used internally.
User Customizable	Specifies whether the end user can set a value for this parameter at the Personalization Portal. You can make most input parameters customizable by the user. In particular, you should set this option for parameters that may be difficult for a user to enter from a mobile device. This includes email addresses and personal identification numbers.
Format	This mask sets the expected data entry mode for the user device. For example, if you expect the user to enter numbers for the parameter, you use the format code N. (This works only with WML 1.1-compliant devices.) The default format is *M. Other formats include: A, for entry of uppercase letters or punctuation. a, for entry of lowercase letters or punctuation. N, for entry of numbers. X, for entry of uppercase letters. x, for entry of lowercase letters. For a complete list of formats, see the Wireless Application Protocol Wireless Markup Language Specification, Version 1.1.
Mandatory	Select this check box if this parameter must have a value. Remove the selection for optional parameters.
Value	For most parameters, this value represents the default value for the parameter. If you specify a default value, the Wireless Edition does not prompt the user for a value. Default values can be overridden by a value specified by a service alias or, if the parameter is visible to the user, by the user at the Personalization Portal. The PAsection parameter is used by the Web Integration adapter. For PAsection, this value is the name of the WIDL service that the Web service should use. You can select the names from a drop-down selection list. If you do not specify a value for PAsection, the Wireless Edition service includes all WIDL services in the WIDL interface.

From this screen, you can add or delete the input parameters for the adapter. To add an input parameter, highlight the parameter and click the Add button. To delete an input parameter, select the input parameter and click the Delete button. Clicking Reset sets the input parameters back to their original state. After you have finished adding or deleting the input parameters for the adapter, click Next. The Output Parameters screen appears.

3.3.6 Step 6: Setting the Output Parameters

The Output Parameters screen enables you to add the output parameters for the adapter. The output parameters displayed below are for the Provisioning adapter, the adapter selected in Step 3. The Master Service Creation Wizard queries the adapter definition to determine the parameters that appear in this screen. The output parameters have the following attributes:

Table 3-4 Output Parameters for the Wireless Edition Adapters

Parameter	Value
Name	The name of the output parameter. The Master Service Creation Wizard sets the name of the output parameter by querying the adapter definition.
Caption	The caption is the label that Wireless Edition uses for the parameter when prompting for user input.
Comment	In the case of master services based on the Web Integration adapter, Wireless Edition automatically populates this cell with the name of the WIDL service that uses the parameter. For services based on other adapters, you can use this column to document the parameter. The comment is only used internally.
User Customizable	Specifies whether the end user can set a value for this parameter at the Personalization Portal. You can make most output parameters customizable by the user. In particular, you should set this option for parameters that may be difficult for a user to enter from a mobile device. This includes email addresses and personal identification numbers.
Format	This mask sets the expected data entry mode for the user device. For example, if you expect the user to enter numbers for the parameter, you use the format code N. (This works only with WML 1.1-compliant devices.) The default format is *M. Other formats include: A, for entry of uppercase letters or punctuation a, for entry of lowercase letters or punctuation N, for entry of numbers. X, for entry of uppercase letters. x, for entry of lowercase letters. For a complete list of formats, see the Wireless Application Protocol Wireless Markup Language Specification, Version 1.1.
Mandatory	Select this check box if this parameter must have a value. Remove the selection for optional parameters.
Value	For most parameters, this value represents the default value for the parameter. If you specify a default value, the Wireless Edition does not prompt the user for a value. Default values can be overridden by a value specified by a service alias or, if the parameter is visible to the user, by the user at the Personalization Portal. The PAsection parameter is used by the Web Integration adapter. For PAsection, this value is the name of the WIDL service that the Web service should use. You can select the names from a drop-down selection list. If you do not specify a value for PAsection, the Wireless Edition service includes all WIDL services in the WIDL interface.

To add an output parameter, highlight the output parameter and click the Add button. To delete an output parameter, select the output parameter and click the Delete button. Clicking Reset sets the output parameters back to their original state.

After you have finished adding or deleting the output parameters for the adapter, click Next. The Confirmation screen appears if the Wireless Edition has not found a PASection in the master service you have created. Review the values listed on the Confirmation screen. If they are correct, click the Finish button. You have completed creating a master service.

If your master service contains a PASection, the Create Result Transformer screen appears.

3.3.7 Step 7: Creating the Result Transformer (Optional)

After you have set the output parameters for the adapter, the Wireless Edition checks if the input parameters include PASection, the value used by the WIDL adapter to identify the service that is the entry point in the chained service sequence. If the Master Service Creation Wizard finds a PASection input adapter, it invokes the Create Result Transformer screen. The tabs in the Result Transformer panel represent different PASections.

To edit a PASection:

1. Click the tab that represents the PASection you wish to edit. Each panel contains a text editor for entering the XSLT style sheet. You can also import an XLST style sheet by clicking the import button.

2. Click Next after you have completed editing the XLST style sheet. The Device Transformer Screen appears. Leave this screen blank if you do not wish to create a result transformer and click Next until you reach the Confirmation screen.

3. If the values appear correct, click Finish to complete the creation of the master service.

3.3.8 Step 8: Setting the Device Transformer (Optional)

The Device Transformer Screen lists the logical devices in the repository. This screen enables you to specify the custom transformer used by the master service for a logical device. A custom transformer enables you to optimize the presentation of service content for a particular device. Since the transformer is specialized for a particular device and master service, you can associate a custom transformer with only one master service and one logical device.

To select a logical device:

1. Select the device for the master service you have created in Steps 1 through 6.

2. Click Next. The confirmation screen appears with a display of the parameters of the master service you have created.

3. Review the values listed on the Confirmation Screen. If they are correct, click Finish to complete the creation of a master service.

3.4 Creating a Location-Based Service

You use both the Service Designer and the Region Modeling Tool to create services that are visible to users only at specific locations.

In the Service Designer, you access the Region Modeling tool by selecting the Location Dependent check box in the either the General tab (used for modifying a folder or service in the Wireless Edition repository tree), or the Create New Services or the Create New Folders forms (invoked by right-clicking the Wireless Edition repository) and then by clicking the Browse button.

Note: Location independent services are services, such as email, which are always visible to the user at any location. These services are created by not selecting the Location Dependent check box.

In the Master Service Creation Wizard, you access the Region Modeling Tool by selecting the Browse button in the Creating New Folder and Setting Service Properties screens. For more information on using the Region Modeling Tool, see Chapter 4, "Using the Region Modeling Tool". For a further description of creating a location-based service, see Section 9.6, "Creating Location-Based Services" in Chapter 9, "Walkthroughs".

Note: You must be connected to the spatial database to return objects using the Region Modeling Tool.

3.4.1 Using the Service Designer to Create Location-Based Services

To make an existing folder or service location-based:

1. In the Wireless Edition repository tree, click the folder or service to which you wish to assign a region. The General tab appears.

2. In the General tab, click the Location Dependent check box. The Browse button appears.

3. Click the Browse Button. The Region Modeling Tool appears.

4. Right-click the region or regions that you wish to assign to the service or folder. Click Select.

   Note: You can select multiple regions using <CTRL> + click.

5. The General tab reappears, showing the Area ID of the selected region.

To create a location-based folder or service from the Service Designer:

1. In the Wireless Edition repository tree, right-click the folder or service to which you wish to assign a region.

2. In the Create New Folders or Create New Services screens, click the Location Dependent check box. The Browse button appears.

3. Click the Browse Button. The Region Modeling Tool appears.

4. Right-click the region or regions that you wish to assign to the service or folder. Click Select.

   Note: You can select multiple regions using <CTRL> + click.

5. The Create New Folders or Create New Services screen reappears, showing the Area ID of the selected region.

3.4.2 Using the Master Service Creation Wizard to Create Location-Based Services

To access the Region Modeling Tool from either the Create the Master Service Creation Wizard:

1. In either the Creating New Folder and Setting Service Properties screens, click the Browse button. The Region Modeling Tool appears.

2. In the left frame, select the region node to which you wish to assign a service. For example, from the SDR hierarchy, expand the North America node to the California node, and then expand to the San Francisco node.

3. Right click the region or regions (for example, San Francisco).

   Note: You can select multiple regions using <CTRL> + click.

4. Click Select. The Creating Folder screen reappears, showing the Area ID of the selected node (for example, 8686, the Area ID of San Francisco). A location has been assigned to the service folder.

3.5 Modifying a Master Service

To modify a master service using the Service Designer, click the master service that you want to change. The object's property tabs appear in the right-hand panel of the Service Designer. You can enter new values directly in the parameter fields, then click Apply to save your changes.

Master services have the following property panels:

• General

• Init Parameters

• Input Parameters

• Output Parameters

• Result Transformer

• Device Transformer

3.5.1 General Panel

The General panel contains parameters that identify and describe the master service. It includes fields for the service name, the adapter on which the service is based, and the cost of the service. Typically, you set the properties listed in this panel when you first created the master service.

3.5.2 Init Parameters Panel

The Init Parameters panel shows the initialization parameters for the adapter. These parameters vary depending on the adapter implementation. The Service Designer generates the fields in this panel from the adapter definition for the master service. When the Wireless Edition first invokes the adapter, it passes the values you set in this panel to the adapter.

The following sections describe the initialization panels for master services based on the adapters provided by the Wireless Edition.

3.5.2.1 Web Integration Init Parameters

The Web Integration adapter retrieves and adapts Web content. The Web Integration adapter works with Web Interface Definition Language (WIDL) files to map source content to Wireless Edition XML. Typically, the source format for the Web Integration adapter is HTML, but developers can also use the adapter to retrieve content in other formats, such as XML.

For a master service based on the Web Integration adapter, the Init Parameters panel appears as follows:

The Init Parameters panel contains the following parameters:

Table 3-5 Init Parameters of the Web Integration Adapter

Parameter	Value
WebIntegrationServer	The machine name and listening port of the Web Integration Server. If the Web Integration Server and the Wireless Edition server reside on the same machine, use localhost:port. This field is required. The server you specify in this field must be running for the Service Designer to return the adapter parameters.
Interface	The WIDL interface name. This interface must be published to the Web Integration Server. You can publish the interface using the Web Integration Developer. You cannot currently use the WIDL_FILE parameter to identify a WIDL service.
WIDL_FILE	Do not enter a value for this parameter.

3.5.2.2 SQL Adapter Init Parameters

Given a URL, the stripper adapter dynamically retrieves and converts the content of the URL target. Unlike the Web Integration adapter, which uses a predefined mapping of the source content, the stripper adapter dynamically processes the markup tags in the content. Currently, the stripper adapter either removes the original markup tags or leaves them intact. Developers can extend the stripper adapter, however, so that it processes the tags in another way.

For a master service based on the SQL adapter, the Init Parameters panel includes the following parameters:

Table 3-6 Init Parameters for the SQL Adapter

Parameter	Value
The Statement	The actual SQL statement that invokes the query, PL/SQL procedure, or stored procedure. Note: The SQL statement should be entered without a semicolon. You can use input variables in the SQL statement. You must indicate a variable in the statement by prefixing the variable with a colon. For example, you can specify an input variable in a PL/SQL statement as follows: begin mypackage.foo(:expr); end; Where :expr is the name of the variable. You must define the parameter manually in the input panel.
Type of Statement	The type of SQL statement used by the master service. Allowable values: QUERY: for a select statement. This type of statement returns a Simple Result document. You can use output filtering with QUERY statements. For information on filtering output, see the Oracle9i Application Server Wireless Edition Developer's Guide. PLSQL: to use a PL/SQL procedure. This type of statement returns results to a database buffer. CALL: to run a stored procedure (SQL92 syntax only). This returns either a Simple Result or an Adapter Result element.
Password	The password of the database user.
Username	The name of the database user.
JDBC Driver	The type of JDBC driver used to access the SQL data source.
JDBC Connect String	The database connect string for the database to access. For example, to access an Oracle database using the thin driver, use the connect string: jdbc:oracle:thin:@domain:port:SID

3.5.2.3 URL Adapter Init Parameters

The URL adapter enables integration with existing Java, JSP, or XML applications. The URL adapter supports parameterization and cookie management, thus providing an easy way to call Wireless Edition services from remote applications and make them wirelessly available. The URL adapter is well suited for developers wishing to build a wireless Web site or internet application using only Java servlets and Java Server Pages (JSPs).

Note: The target attributes in the SimpeResult XML documents retrieved by the URL adapter must be URL-encoded.

There are no Init parameters for this adapter.

3.5.2.4 Servlet Adapter Init Parameters

The Servlet adapter enables developers to integrate other applications that are already Java servlets, providing a convenient way to call them as Wireless Edition services and make them wirelessly available.

For a master service based on the servlet adapter, the Init Parameters panel appears as follows:

Figure 3-7 The Init Parameters Panel for the Servlet Adapter

Text description of the illustration srv_insa.gif

The panel contains the following parameters:

Table 3-7 Init Parameters for the Servlet Adapter

Parameter	Value
className	The complete class name of the Java servlet file. For example: oracle.panama.adapter.servlet.TestServlet.
debugLevel	The debug level. Possible values are: 0, for none; 1, for notifications; and 2 for trace.

3.5.2.5 Mail Adapter Init Parameters

The Mail adapter is based on the JavaSoft's Java Mail API and provides mail services to both POP3 and IMAP4 mail servers. It provides basic authentication and mail session management. The Mail adapter enables users to browse, create, delete, reply, and forward mail and folders from their wireless devices. For more information on the Mail adapter, see Appendix A, "The Mail Adapter".

The Mail adapter has no init parameters. See Section 3.5.3.2 for the input parameters of the Mail adapter.

3.5.2.6 Directory Adapter Init Parameters

The Directory adapter provides directory service and is based on the JavaSoft Java Naming Directory Interface (JNDI) 1.2 specification. The Directory adapter also enables you to create hyperlinks.

The Init Parameters panel for the Directory Adapter includes the following parameters:

Table 3-8 Init Parameters for the Directory Adapter

Parameter	Value
Host Name	The name or IP address of the machine on which the Directory server runs. All directory queries are directed to the directory server running on this machine. If no host name is specified, the address defaults as localhost.
Port number	This defaults to port 389.
User Name	Name of the database user.
Password	Password of the database user.
Query Strings	The LDAP query strings that a provider of the service should specify in order to provide the end user with a menu of the query list.
HotLink String	This is an optional entry. The HotLink strings that may be used to qualify an output attribute so that the attribute will be displayed as a hyperlink in the end user's browser screen.
ResultType	The value for ResultType is SimpleResult.

3.5.3 Input Parameters Panel

The Input Parameters panel displays the input parameters for the adapter. The Service Designer queries the adapter definition to determine the parameters that appear in this panel. The master service passes the input parameter values to the adapter's invoke method every time the adapter executes.

Some parameters rely on user input for values. The values for other parameters, such as name of the WIDL service in the WIDL interface (PAsection), are set by the master service or master service alias. PAsection is an internal parameter, not exposed to the end user. In addition to PAsection, the Wireless Edition provides these input parameters:

Table 3-9 Input Parameters

Variable	Value
PAservicepath	The relative path to a Wireless Edition service, /UsersFolders/joe/myChain, for example.
PAdebug	The debugging option. If true (set to 1), the Wireless Edition produces verbose output to the log files. In this case, in addition to notifications and warnings, the Wireless Edition writes the results of adapter invocations to the log file. This enables you to examine service content in its internal, XML format, which can help you to create result transformers and solve service and transformer problems.
PAsection	The WIDL adapter uses this value to identify the service that serves as the entry point in the chained service sequence.
PAuserid	The user name.
PApassword	The user password.
PAsid	The Wireless Edition session identifier.

You can configure your parameters in the Service Designer. Every Wireless Edition parameter has the following attributes:

Table 3-10 Input Parameters Attributes

Parameter	Value
Name	The name of the input parameter. The Service Designer sets the name of the input parameter by querying the adapter definition.
Caption	The caption is the label that the Wireless Edition uses for the parameter when prompting for user input.
Comment	In the case of master services based on the Web Integration adapter, the Wireless Edition automatically populates this cell with the name of the WIDL service that uses the parameter. For services based on other adapters, you can use this column to document the parameter. The comment is only used internally.
User Customizable	Specifies whether the end user can set a value for this parameter at the Personalization Portal. You can make most input parameters customizable by the user. In particular, you should set this option for parameters that may be difficult for a user to enter from a mobile device. This includes email addresses and personal identification numbers.
Format	This mask sets the expected data entry mode for the user device. For example, if you expect the user to enter numbers for the parameter, you use the format code N. This works only with WML 1.1-compliant devices. The default format is *M. Other formats include: A, for entry of uppercase letters or punctuation a, for entry of lowercase letters or punctuation N, for entry of numbers. X, for entry of uppercase letters. x, for entry of lowercase letters. For a complete list of formats, see the Wireless Application Protocol Wireless Markup Language Specification, Version 1.1.
Mandatory	Select this check box if this parameter must have a value. Remove the selection for optional parameters.
Value	For most parameters, this value represents the default value for the parameter. If you specify a default value, the Wireless Edition does not prompt the user for a value. Default values can be overridden by a value specified by a service alias or, if the parameter is visible to the user, by the user at the Personalization Portal. The PAsection parameter is used by the Web Integration adapter. For PAsection, this value is the name of the WIDL service that the Web service should use. You can select the names from a drop-down selection list. If you do not specify a value for PAsection, the Wireless Edition service includes all WIDL services in the WIDL interface.

3.5.3.1 Web Integration Input Parameters

The following figure shows a sample Inputs panel for a Web service.

Figure 3-8 The Input Parameters Panel for the Web integration Adapter

Text description of the illustration srv_ipwb.gif

The master service determines the parameters to display in the panel by querying the adapter. Every input parameter defined in the WIDL interface appears in the Inputs panel, including parameters for other WIDL services within the WIDL interface.

In addition to the custom input parameters that you create, Web Integration services provide these parameters:

• OutputType

• PAsection

• InputEncoding

The OutputType specifies the type of XML output that the adapter should return. You can specify RawResult, to return content in Adapter Result format, or SimpleResult, to return content in Simple Result format. If returning raw result format, you must create a result transformer that converts the result into Simple Result for the device transformer. The result transformer should have the same name as the value you use for the PAsection parameter; that is, it should have the same name as the WIDL service. You use RawResult for chained services.

PAsection is the name of the WIDL service that you want the master service to invoke. A WIDL interface can include more than one WIDL service. The Wireless Edition lists the WIDL service names in a selection list in the value field.

InputEncoding specifies the encoding used to encode the source document. The source document is the URL that was used to create the WIDL file for this service. See Chapter 9, "Walkthroughs" for information on creating a Web service. The default value of this parameter is UTF-8. If the language of the source document is an Asian language, you can change the default encoding to the appropriate multi-byte encoding according to the IANA standards for the particular Asian language that is used in the source document. The InputEncoding parameter enables you to specify or change the encoding. It is part of the multi-byte character support. The Oracle9i Application Server Wireless Edition Developer's Guide provides more information about multi-byte character support.

3.5.3.2 Mail Adapter Input Parameters

The Mail adapter has the following input parameters.

Table 3-11 Init Parameters for the Mail Adapter

Parameter	Value
mail_type	The mail server type. Options are IMAP and POP
Incoming_Server	The host name for the incoming server (for example, gmmail.oracle.com).
Outgoing_Server	The host name of the outgoing mail server (for example, gmsmtp01.oraclecorp.com
mail_ReturnDomain	The domain name of the user's email address. This domain must start with the @ symbol (for example, @oracle.com).
UserName	The user name of the email account.
Password	The password used to login to the email account.

3.5.3.3 SQL Master Service Input Parameters

You can configure SQL input parameters just as you can Web service parameters. You specify input parameters in the SQL statement you use to implement the service. For information on creating parameterized SQL services, see Section 3.5.2.2.

3.5.3.4 Stripper Adapter Input Parameters

For a master service based on the stripper adapter, the Inputs panel appears as follows:

Figure 3-9 The Input Parameters Panel for the Stripper Adapter

Text description of the illustration srv_ipst.gif

The panel contains the following parameters:

Table 3-12 Input Parameters for the Stripper Adapter

Parameter	Value
url	The URL of the source page. If you do not include the protocol in the URL, the Wireless Edition adds "http://" before this value with
beginTag	A string that matches the start point of the text retrieved from the URL target page. This value is optional. If not specified, the start point is the beginning of the page.
endTag	A string that matches the end point of the text retrieved from the URL target page. This value is optional. If not specified, the end point is the end of the page.
stripLevel	The strip level identifies the class used by the stripper adapter to filter the retrieved content. The Wireless Edition provides two levels: 0: Retains all markup tags in the content. 1: Removes all markup tags in the content. You can implement additional strip levels or filters. For more information, see the Oracle9i Application Server Wireless Edition Developer's Guide.
title	An optional title of the result.

3.5.3.5 URL Adapter Input Parameters

The URL adapter allows applications to invoke other URLs and pass in arguments. In addition, the URL adapter enables the following functions:

• Integration with existing Java, JSP, or XML applications.

• Parameterization and cookie management, enabling remote applications to become wirelessly available.

• Support for the GET/POST method.

The URL adapter is well suited for developers wishing to build a wireless Web site or internet application using only Java servlets and Java Server Pages (JSPs).

The panel contains the following parameter:

Table 3-13 Input Parameters for the URL Adapter

Parameter

Value

URL

The URL of the XML document that is retrieved by the URL Adapter. The XML document should conform to the SimpleResult DTD. For example, if the URL parameter is file:///d:/SimpleResultExample1.xml, then the adapter gets the file d:/SimpleResultExample1.xml from the hard drive on the local machine. If the URL parameter is http://ptg1.oracle.com/SimpleResultExamle2.xml, then the adapter gets the file SimpleResultExamle2.xml from the host ptg1.oracle.com.

3.5.3.6 Servlet Adapter Input Parameters

For a service that is based on the Servlet adapter, the Input Parameters panel appears as follows:

Figure 3-10 The Input Parameters Panel for the Servlet Adapter

Text description of the illustration srv_ipsa.gif

Table 3-14 Input Parameters for the Servlet Adapter

Parameter	Value
requestMethod	The value of this parameter can be any of the following: GET, HEAD, POST, PUT, DELETE, OPTIONS, or TRACE. Depending on the value of this parameter, the appropriate method of the servlet gets called when the adapter is invoked. For example, if the value of requestMethod is GET, then the doGet method of the servlet is called.

3.5.4 Output Parameters Panel

The output parameters panel allows you to set captions for service output parameters.

3.5.5 Result Transformer Panel

The Result Transformer panel specifies a transformer that the Wireless Edition uses to convert Adapter Result content. The Wireless Edition provides two content formats, Adapter Result and Simple Result. Adapter Result is intended to be an intermediary format for passing raw data between services. Device transformers, which convert service content for the target format, cannot convert Adapter Result format. A result transformer must therefore convert the content to Simple Format before it can be processed by a device transformer.

To create a result transformer:

1. Click Add.

2. Enter the name of the result transformer in the name field. You must use the same name for the result transformer as you used for the WIDL service to which it applies. This is the value of the PAsection input parameter.

3. Click Edit. The XSL Editor window appears. The XSL Editor is a simple text editor you can use to build your result transformer. You can cut and paste from other environments into the XSL Editor.

4. When finished, click OK.

3.5.6 Device Transformer Panel

The Device Transformer panel lists the logical devices in the repository. You can specify a custom transformer to be used with the master service for a logical device. A custom transformer enables you to optimize the presentation of service content for a particular device. Since the transformer is specialized for a particular device and master service, you can associate a custom transformer with only one master service and one logical device.

3.6 Deleting a Master Service

You can delete a master service in the Service Designer as follows:

1. Select the master service that you want to delete.

2. Right-click and select Delete.

3. Confirm the action.

When you delete a master service, the Service Designer flags any aliases to the master service.

3.7 Creating a Folder

You can create folders in either the Master Services folder or the Service Trees folder of the Wireless Edition repository tree. To create a folder, you use the Create New Folder form.

To invoke the form:

1. Select the root folder under which you want to place the folder.

2. Right click.

3. Select Create New Folder.

The Create New Folder form appears as follows:

Figure 3-11 The Create New Folder Form

Text description of the illustration srv_cnfa.gif

The panel includes the following parameters:

Table 3-15 Parameters for the Create New Folder Form

Parameter	Value
Name	The folder name must be a unique name in the parent folder.
Valid	Select the Valid check box to enable the folder.
Visible	Select the Visible check box to make the folder accessible to users.
Owner	The user or group that owns the folder. Only the owner can modify the folder.
Location Dependent	Selecting this check box invokes the Browse button, which gives you access to the Region Modeling Tool.
Browse	Clicking this button gives you access to the Region Modeling Tool. You use the Region Modeling Tool to assign a region to the service.
Sequence	This integer value lets you alter the order in which services and folders appear on output devices. By default, these appear in order by sequence number, then name. You can enter values in the sequence fields to rearrange the order in which the services and folder appear. By default, the Wireless Edition sorts services and folders in ascending order by sequence number, then by name. You can change this behavior by altering the order.services property in the System.properties file. You can specify sorting by sequence number, name, or date last written, in either ascending or descending order.
Area Id	An integer value that allows you to specify whether a folder is visible based on a user's physical location. This enables you to implement location-specific services. This is an optional value.
Description	An optional description of the folder.

3.8 Deleting a Folder

You can delete a folder in the Service Designer as follows:

1. Select the folder that you want to delete.

2. Right-click and select Delete.

3. Confirm the action.

3.8.1 Service Trees

A service tree is a folder you use to organize and distribute access to services. It can contain master services, service aliases, or other folders.

Folders make services accessible to users. When you create a new user, you also create a service tree for that user. Any service that you place in a user's service tree (or user's home), is accessible to the user.

Similarly, when you create a group, you specify the service trees that belong to the group. Any member of the group can access the services in that group's service trees. While a user can have only one private service tree, groups can have many service trees. Different groups can share the same service tree.

If you do not specify an owner when you create a service tree, the tree is public. If you specify an owner, the service tree is private. End users can access any public service tree, but they can only access their own private service trees. They have complete control of their service trees from the Personalization Portal; they can copy services between service trees, rename services, and create folders.

The Wireless Edition does not provide dependency tracking for a private service (a service in a private service tree). If the target service of the private service is no longer valid, an error occurs when a user attempts to submit a request for that service. The Wireless Edition then advises the user to delete the service from the private service tree.

3.9 Creating a Service Alias

A service alias is a link to a master service, folder, or other alias. Service aliases help you to distribute service access to multiple users or groups. They also enable you to specialize master services, since default parameter values specified by an alias override values set at the master service. This characteristic provides several benefits. One benefit is that it enables you to localize services. For example, suppose you create a service that delivers restaurant information for a city. The adapter takes a single parameter, a location, and returns a list of restaurants in the area. While the master service can specify a more general location, such as the city, you can create aliases that provide a more specific parameter, such as a district within the city. You can then distribute the aliases, as appropriate, to user groups that you assemble based on the users' locations of residence.

To create a service alias:

1. Highlight and right-click any Service Tree subfolder in the Wireless Edition Repository tree.

2. Click Create New Alias.

The first form in the sequence appears as follows:

Figure 3-12 Create New Alias Form (First Form)

Text description of the illustration srv_cnaf.gif

The panel includes the following parameters:

Table 3-16 Parameters for the Create New Alias Form

Parameter	Value
Name	The service alias name. This must be a unique name within the parent folder.
Service	The master service referenced by the service alias. To select a master service, click Browse and choose a master service from the Browse Services window.
Valid	Select the Valid check box to enable the alias.
Visible	Select the Visible check box to make the alias accessible to users.
Owner	The user or group that owns the alias. Only the owner can modify the alias. If you are creating an alias in a user's home folder, you can make the owner that user. This enables the user to modify the service--by renaming it, for example--at the personalization portal.
Sequence	This integer value lets you alter the order in which services and folders appear on output devices. By default, these appear in order by sequence number, then name. You can enter values in the sequence fields to rearrange the order in which the services and folders appear. By default, the Wireless Edition sorts services and folders in ascending order by sequence number, then by name. You can change this behavior by altering the order.services property in the System.properties file. You can specify sorting by sequence number, name, or date last written, in either ascending or descending order.
Description	An optional description of the alias.

Complete the properties in the form and click Finish to create the alias in the repository. You do not need to complete the second form in the sequence. You can configure the runtime parameters for the alias by modifying the alias properties, just as you would for the master service on which the alias is based. For more information on specifying runtime parameters, see Section 3.5.3.