After configuring the server, your SPML application requires a mechanism for sending SPML messages and receiving SPML responses. For Java applications, use the OpenSPML Toolkit to configure this mechanism.
For optimal performance when you are working with the Waveset Web Service Interfaces, use the OpenSPML Toolkit that is co-packaged with Waveset.
Using the openspml.jar file from the http://www.openspml.org/ web site might cause memory leaks.
The OpenSPML Toolkit provides the following components:
Java class model for SPML messages
Classes to send and receive messages on the client
Classes to receive and process requests on the server
The following table describes the most important classes provided by the toolkit. Each request type has a corresponding class. Consult the Javadoc tool distributed with the toolkit for complete information.
Table 1–3 Classes Provided by the OpenSPML Toolkit
Class |
Description |
---|---|
AddRequest |
Constructs a message to request creation of a new object. You define the object type by passing an objectclass attribute. Other passed attributes must adhere to the schema associated with the object class. SPML does not yet define standard schemas, but you can configure Waveset to support almost all schemas. |
BatchRequest |
Constructs a message that can contain more than one SPML request. |
CancelRequest |
Constructs a message to cancel a request that was formerly executed asynchronously. |
DeleteRequest |
Constructs a message to request the deletion of an object. |
ModifyRequest |
Constructs a message to request modification of an object. Include only those attributes that you want to modify in the request. Attributes omitted from the request will retain their current values. |
SchemaRequest |
Constructs a message to request information about SPML object classes supported by the server. |
SearchRequest |
Constructs a message to request object attributes that match certain criteria. |
SpmlClient |
Presents a simple interface for sending and receiving SPML messages. |
SpmlResponse |
Includes the base class for objects representing response messages sent back from the server. Each request class has a corresponding response class, for example, AddResponse and ModifyResponse. |
StatusRequest |
Constructs a message to request the status of a request that was formerly executed asynchronously. |
The Service Provider REF Kit contains an SpmlUsage.java file that demonstrates how to use the Service Provider SPML interface. This REF Kit also contains an ant script that compiles the SpmlUsage class.
Usage:
java [ -Dtrace=true ] com.sun.idm.idmx.example.SpmlUsage [ URL ]
where URL points to the Service Provider SPML interface. The URL defaults to
http://host:port/idm/spespml
where
host is the machine on which you are running Waveset Service Provider.
port is the number of the TCP port on which the server is listening.
You can enable trace for Service Provider to print Service Provider SPML messages to standard output.
The following table describes the different ExtendedRequest classes that you can use to send messages to and receive messages from the client.
Table 1–4 ExtendedRequest Classes for Sending and Receiving Messages
ExtendedRequest Class |
Description |
---|---|
changeUserPassword |
Constructs a message to request a user password change. |
deleteUser |
Constructs a message to request a user deletion. |
disableUser |
Constructs a message to request the disabling of a user. |
enableUser |
Constructs a message to request the enabling of a user. |
launchProcess |
Constructs a message to request the launch of a process. |
listResourceobjects |
Constructs a message to request the name of a resource object in the Waveset repository, and the type of object supported by that resource. The request returns a list of names. |
reloadConfiguration |
Reloads the SPML Configuration object. |
resetUserPassword |
Constructs a message to request the reset of a user password. |
runForm |
Allows you to create custom SPML requests that return information obtained by calling the Waveset Session API. |
soapTrace |
Enables tracing. |
The server code converts each ExtendedRequest into a view operation.
The following examples illustrate the typical formats for an ExtendedRequest and its classes:
The following example shows the typical format for an ExtendedRequest.
ExtendedRequest req = new ExtendedRequest(); req.setOperationIdentifier("changeUserPassword"); req.setAttribute("accountId", "exampleuser"); req.setAttribute("password", "xyzzy"); req.setAttribute("accounts","Lighthouse,LDAP,RACF"); ExtendedResponse res = (ExtendedResponse) client.request(req); |
Most SPML ExtendedRequest requests accept the following arguments:
accountId – Identifies the Waveset user name.
accounts – Presents resource names in a comma-delimited list.
If you pass an accounts argument, the specified SPML operation only updates the specified resources. You must include the Lighthouse attribute in a non-null accounts list if you want to update the Waveset user in addition to specific resource accounts.
If you do not pass an accounts argument, the operation updates all resource accounts linked to the user, including the Waveset user account.
The following example shows the typical format for a deleteUser request (View -> Deprovision view).
If you customize this request, there might be side effects.
ExtendedRequest req = new ExtendedRequest(); req.setOperationIdentifier("deleteUser"); req.setAttribute("accountId","exampleuser"); req.setAttribute("accounts","Lighthouse,LDAP,RACF"); ExtendedResponse res = (ExtendedResponse) client.request(req); |
The following example shows the typical format for a disableUser request (View -> Disable view).
ExtendedRequest req = new ExtendedRequest(); req.setOperationIdentifier("disableUser"); req.setAttribute("accountId","exampleuser"); req.setAttribute("accounts","Lighthouse,LDAP,RACF"); ExtendedResponse res = (ExtendedResponse) client.request(req); |
The following example shows the typical format for an enableUser request (View -> Enable view).
ExtendedRequest req = new ExtendedRequest(); req.setOperationIdentifier("enableUser"); req.setAttribute("accountId","exampleuser"); req.setAttribute("accounts","Lighthouse,LDAP,RACF"); ExtendedResponse res = (ExtendedResponse) client.request(req); |
The following example shows the typical format for a launchProcess request (View -> Process view).
ExtendedRequest req = new ExtendedRequest(); req.setOperationIdentifier("launchProcess"); req.setAttribute("process", "my custom process"); req.setAttribute("taskName", "my task instance"); ExtendedResponse res = (ExtendedResponse) client.request(req); |
where:
launchProcess – Starts the custom processes.
process – Name of the TaskDefinition object in the Waveset repository to start.
taskName – Name of the task needed to start the workflow.
The task instance object holds the runtime state of the process.
The remaining attributes are arbitrary and they are passed into the task.
The following example shows the typical format for a listResourceObjects request.
ExtendedRequest req = new ExtendedRequest(); req.setOperationIdentifier("listResourceObjects"); req.setAttribute("resource", "LDAP"); req.setAttribute("type", "group"); ExtendedResponse res = (ExtendedResponse) client.request(req); |
where:
resource – Specifies the name of a resource object in the Waveset repository.
type – Specifies the object type supported by that resource.
The following example shows the typical format for a reloadConfiguration request.
ExtendedRequest req = new ExtendedRequest(); req.setOperationIdentifier("reloadConfiguration"); ExtendedResponse res = (ExtendedResponse) client.request(req); |
The following example shows the typical format for a resetUserPassword request (View -> Reset User Password view).
ExtendedRequest req = new ExtendedRequest(); req.setOperationIdentifier("resetUserPassword"); req.setAttribute("accountId","exampleuser"); req.setAttribute("accounts","Lighthouse,LDAP,RACF"); ExtendedResponse res = (ExtendedResponse) client.request(req); |
The following example shows the typical format for a runForm request.
ExtendedRequest req = new ExtendedRequest(); req.setOperationIdentifier("runForm"); req.setAttribute("form", "SPML Get Object Names"); ExtendedResponse res = (ExtendedResponse) client.request(req); |
where form is the name of a configuration object containing a form.
The following example shows the typical format for a soapTrace request.
ExtendedRequest req = new ExtendedRequest(); req.setOperationIdentifier("soapTrace"); ExtendedResponse res = (ExtendedResponse) client.request(req); |
The following example shows a form that is used to run queries and return a list of the Role, Resource, and Organization names accessible to the current user.
<Configuration name='SPML Get Object Names'> <Extension> <Form> <Field name='roles'> <Derivation> <invoke class='com.waveset.ui.FormUtil'> <ref>display.session</ref> <s>Role</s> </invoke> </Derivation> </Field> <Field name='resources'> <Derivation> <invoke class='com.waveset.ui.FormUtil'> <ref>display.session</ref> <s>Resource</s> </invoke> </Derivation> </Field> <Field name='organizations'> <Derivation> <invoke class='com.waveset.ui.FormUtil'> <ref>display.session</ref> <s>ObjectGroup</s> </invoke> </Derivation> </Field> </Form> </Extension> </Configuration> |
You use the runForm request to create custom SPML requests that return information obtained by calling the Waveset Session API. For example, when configuring a user interface for editing user accounts, you might want to provide a selector that displays the names of the organizations, roles, resources, and policies that can be assigned to a user.
You can configure the SPML interface to expose these objects as SPML object classes and use searchRequest to query for their names. However, this configuration requires four searchRequest requests to gather the information. To reduce the number of SPML requests, encode the queries in a form by using a single runForm request to perform the queries and return the combined results.
SPML includes options for turning on trace output so you can log Waveset SPML traffic and diagnose problems.
For more information about tracing SPML, see Chapter 5, Tracing and Troubleshooting, in Oracle Waveset 8.1.1 System Administrator’s Guide.