Core Capabilities (Oracle Waveset 8.1.1 Web Services)

Oracle Waveset 8.1.1 Web Services

`Core` Capabilities

Waveset supports the Core capabilities described in the following table.

Table 2–2 Core Capabilities


Capability	Description	Caveats
`AddRequest`	Adds a specified PSO to the system.	Waveset officially supports only a single target.
`DeleteRequest`	Deletes a specified PSO from the system.	Waveset officially supports only a single target.
`ListTargetsRequest`	Lists the targets that are available through Waveset.	Waveset officially supports a single target. Waveset does not require you to use `ListTargets` as the first call in a conversation. However, it does allow `operationalAttributes` on this request to specify a username/password pair for establishing a session with the server. (You can also use `Waveset.properties`.) In general, it is more efficient to log in and use the session token. Waveset provides a class called `SessionAwareSpml2Client` for this purpose.
`LookupRequest`	Finds and returns the attributes of the named PSO.	None
`ModifyRequest`	Modifies specified PSO attributes.	Due to a discrepancy between the main SPML 2.0 specification and the DSML Profile specification, Waveset does not support `select`, `component`, and so forth. Instead Waveset uses DSML Modification Mode and elements according to the DSML Profile.

Note –

General caveats include the following:

You can provide username and password values for the ListTargetsRequest request. These values are used as credentials to establish a session, which is identified by the session token value returned in theListTargetsRequest response. This session is the context for all following requests that include that session token value as an operational attribute.

Another way to set up the session is to provide values for the soap.username and soap.password attributes in Waveset.properties. In this case, no session token is required.
Waveset supports only the DSML Profile.

AddRequest and ListTargetsRequest examples follow.

Core Capability Examples

This section provides several Java, XML, and JSP examples.

The following examples adds a user with several attributes. The first example returns all data, while the second returns only the identifier.

Example 2–1 Example `AddRequest`

// ReturnData.EVERYTHING example
SessionAwareSpml2Client client = new SessionAwareSpml2Client("http://example.com:8080/
idm/servlet/openspml2");
ListTargetsResponse loginInfo = client.login("Configurator", "configurator");

AddRequest req = new AddRequest();
req.setReturnData(ReturnData.EVERYTHING);
Extensible attrs = new Extensible();
attrs.addOpenContentElement(new DSMLAttr("objectclass", "spml2Person"));
attrs.addOpenContentElement(new DSMLAttr("accountId", "sempiricus"));
attrs.addOpenContentElement(new DSMLAttr("credentials", "password"));
attrs.addOpenContentElement(new DSMLAttr("firstname", "Sextus"));
attrs.addOpenContentElement(new DSMLAttr("lastname", "Empiricus"));
req.setData(attrs);

AddResponse res = (AddResponse) client.request(req);
if (res.getStatus().equals(StatusCode.SUCCESS)) {
    System.out.println("Received positive add response.");
}

PSO pso = res.getPso();
System.out.println("PSO ID: " + pso.getPsoID().getID());
Extensible psoData = pso.getData();
for (OpenContentElement oce : psoData.getOpenContentElements()) {
    if (oce instanceof DSMLAttr) {
        DSMLAttr attr = (DSMLAttr) oce;
        System.out.println(attr.getName() + ": " + attr.getValues()[0].getValue());
    }
}

// ReturnData.IDENTIFIER example
SessionAwareSpml2Client client = new SessionAwareSpml2Client("http://example.com:8080/
idm/servlet/openspml2");
ListTargetsResponse loginInfo = client.login("Configurator", "configurator");

AddRequest req = new AddRequest();
req.setReturnData(ReturnData.IDENTIFIER);
Extensible attrs = new Extensible();
attrs.addOpenContentElement(new DSMLAttr("objectclass", "spml2Person"));
attrs.addOpenContentElement(new DSMLAttr("accountId", "catullus"));
attrs.addOpenContentElement(new DSMLAttr("credentials", "password"));
attrs.addOpenContentElement(new DSMLAttr("firstname", "Gaius"));
attrs.addOpenContentElement(new DSMLAttr("lastname", "Catullus"));
req.setData(attrs);

AddResponse res = (AddResponse) client.request(req);
if (res.getStatus().equals(StatusCode.SUCCESS)) {
    System.out.println("Received positive add response.");
}

PSO pso = res.getPso();
System.out.println("PSO ID: " + pso.getPsoID().getID());
Extensible psoData = pso.getData();
if (psoData == null) {
    System.out.println("PSO contains no data, as expected.");
}

The following example shows an account lookup.

Example 2–2 Example `LookupRequest`

// Lookup example
SessionAwareSpml2Client client = new 
     SessionAwareSpml2Client("http://example.com:8080/idm/servlet/openspml2");
ListTargetsResponse loginInfo = client.login("Configurator", "configurator");

PSOIdentifier psoId = new PSOIdentifier("maurelius", null, null);

LookupRequest req = new LookupRequest();
req.setPsoID(psoId);
req.setExecutionMode(ExecutionMode.SYNCHRONOUS);

try {
    LookupResponse res = (LookupResponse) client.request(req);
    if (res.getStatus().equals(StatusCode.SUCCESS)) {
        System.out.println("Performed account lookup.");
    }
    PSO pso = res.getPso();
} catch (Spml2ExceptionWithResponse e) {
    System.out.println("Lookup failed: " + e.getMessage());
    LookupResponse res = (LookupResponse) e.getResponse();
}

The following example changes the lastname parameter to Antoninus.

Example 2–3 Example `ModifyRequest`

SessionAwareSpml2Client client = new 
     SessionAwareSpml2Client("http://example.com:8080/idm/servlet/openspml2");
ListTargetsResponse loginInfo = client.login("Configurator", "configurator");

PSOIdentifier psoId = new PSOIdentifier("maurelius", null, null);

ModifyRequest req = new ModifyRequest();
req.setPsoID(psoId);
Modification modification = new Modification();
modification.addOpenContentElement(new DSMLModification("lastname", "Antoninus", 
                                                        ModificationMode.REPLACE));
req.addModification(modification);

ModifyResponse res = (ModifyResponse) client.request(req);
if (res.getStatus().equals(StatusCode.SUCCESS)) {
    System.out.println("Modified account.");
}

The following example shows the SPML 2.0 request that was sent.

Example 2–4 Example Request XML

<addRequest xmlns='urn:oasis:names:tc:SPML:2:0' requestID='rid-spmlv2' 
executionMode='synchronous'>
  <openspml:operationalNameValuePair xmlns:openspml='urn:org:openspml:v2:util:xml
    name='session' value='AAALPgAAYD0A...'/>
  <data>
    <dsml:attr xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' name='accountId'>
      <dsml:value>exampleSpml2Person</dsml:value>
    </dsml:attr>
    <dsml:attr xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' name='objectclass'>
      <dsml:value>spml2Person</dsml:value>
    </dsml:attr>
    <dsml:attr xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' name='credentials'>
      <dsml:value>pwdpwd</dsml:value>
    </dsml:attr>
  </data>
</addRequest>

This example shows the body of the SPML response that was returned to the client.

Example 2–5 Example Response XML

<addResponse xmlns='urn:oasis:names:tc:SPML:2:0' status='success' 
requestID='rid-spmlv2'>
  <openspml:operationalNameValuePair xmlns:openspml='urn:org:openspml:v2:util:xml'
    name='session' value='AAALPgAAYD0A...'/>
  <pso>
    <psoID ID='anSpml2Person'/>
    <data>
      <dsml:attr xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' name='accountId'>
        <dsml:value>anSpml2Person</dsml:value>
      </dsml:attr>
      <dsml:attr xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' name='objectclass'>
        <dsml:value>spml2Person</dsml:value>
      </dsml:attr>
      <dsml:attr xmlns:dsml='urn:oasis:names:tc:DSML:2:0:core' name='credentials'>
        <dsml:value>pwdpwd</dsml:value>
      </dsml:attr>
    </data>
  </pso>
</addResponse>

Example 2–6 Example JSP

The following example consists of a .jsp file that invokes an AddRequest through Waveset’s SessionAwareSpml2Client class.

<%@page contentType="text/html"%>
<%@page import="org.openspml.v2.client.*,
                com.sun.idm.rpc.spml2.SessionAwareSpml2Client"%>
<%@page import="org.openspml.v2.profiles.dsml.*"%>
<%@page import="org.openspml.v2.profiles.*"%>
<%@page import="org.openspml.v2.util.xml.*"%>
<%@page import="org.openspml.v2.msg.*"%>
<%@page import="org.openspml.v2.msg.spml.*"%>
<%@page import="org.openspml.v2.util.*"%>

<%
final String url = "http://host:port/idm/servlet/openspml2";
%>

<html>
<head><title>SPML2 Test</title></head>
<body>
<%

 // need a client.
 SessionAwareSpml2Client client = new SessionAwareSpml2Client( url );

 // login
 client.login("configurator", "password");

 // AddRequest
 String rid = "rid-spmlv2"; // The RequestId is not strictly required.

 Extensible data = new Extensible();
 data.addOpenContentElement(new DSMLAttr("accountId", user));
 data.addOpenContentElement(new DSMLAttr("objectclass", "spml2Person"));
 data.addOpenContentElement(new DSMLAttr("credentials", password));

 AddRequest add = new AddRequest(rid, // String requestId,
                ExecutionMode.SYNCHRONOUS, // ExecutionMode executionMode,
                null, // PSOIdentifier type,
                null, // PSOIdentifier containerID,
                data, // Extensible data,
                null, // CapabilityData[] capabilityData,
                null,  // String targetId,
                null  // ReturnData returnData
            );

    // Submit the request
    Response res = client.request( add );
%>
<%= res.toString()%>
</body>
</html>

`ListTargetsRequest` Examples

The examples in this section illustrate the ListsTargetsRequest capabilities that are available using Waveset.

Example 2–7 Example Client Code

The following example shows how a .jsp file invokes a ListTargetsRequest through Waveset’s SessionAwareSpml2Client class.

<%@page contentType="text/html"%>
<%@page import="org.openspml.v2.client.*,
                com.sun.idm.rpc.spml2.SessionAwareSpml2Client"%>
<%@page import="org.openspml.v2.profiles.dsml.*"%>
<%@page import="org.openspml.v2.profiles.*"%>
<%@page import="org.openspml.v2.util.xml.*"%>
<%@page import="org.openspml.v2.msg.*"%>
<%@page import="org.openspml.v2.msg.spml.*"%>
<%@page import="org.openspml.v2.util.*"%>
<%
final String url = "http://host:port/idm/servlet/openspml2";
%>
<html>
<head><title>SPML2 Test</title></head>
<body>
<%
 // need a client.
 SessionAwareSpml2Client client = new SessionAwareSpml2Client( url );
 // login (sends a ListTargetsRequest)
 Response res = client.login("configurator", "password");
%>
<%= res.toString()%>

// logout
client.logout();
</body>
</html>

Example 2–8 Example Request XML

This next example shows the body of the SPML request that is sent for login.

<listTargetsRequest xmlns='urn:oasis:names:tc:SPML:2:0' requestID='rid[7013]' 
    executionMode='synchronous'>
  <openspml:operationalNameValuePair xmlns:openspml='urn:org:openspml:v2:util:xml'
    name='accountId' value='configurator'/>
  <openspml:operationalNameValuePair xmlns:openspml='urn:org:openspml:v2:util:xml'
    name='password' value='password'/>
</listTargetsRequest>

This example shows the body of the SPML response that is received by or returned to the client.

Example 2–9 Example Response XML

   <openspml:operationalNameValuePair 
xmlns:openspml="urn:org:openspml:v2:util:xml" name="session" value="AAAM+wAAaC..."/>
   <target targetID="spml2-DSML-Target" profile="urn:oasis:names:tc:SPML:2:0:DSML">
      <schema>
         <spmldsml:schema xmlns:spmldsml="urn:oasis:names:tc:SPML:2:0:DSML">
            <spmldsml:objectClassDefinition name="spml2Person">
               <spmldsml:memberAttributes>
                  <spmldsml:attributeDefinitionReference required="true" 
name="objectclass"/>
                  <spmldsml:attributeDefinitionReference required="true" 
name="accountId"/>
                  <spmldsml:attributeDefinitionReference required="true" 
name="credentials"/>
                  <spmldsml:attributeDefinitionReference name="firstname"/>
                  <spmldsml:attributeDefinitionReference name="lastname"/>
                  <spmldsml:attributeDefinitionReference name="emailAddress"/>
               </spmldsml:memberAttributes>
            </spmldsml:objectClassDefinition>
            <spmldsml:attributeDefinition name="objectclass"/>
            <spmldsml:attributeDefinition description="Account Id" name="accountId"/>
            <spmldsml:attributeDefinition description="Credentials, e.g. password" 
name="credentials"/>
            <spmldsml:attributeDefinition description="First Name" name="firstname"/>
            <spmldsml:attributeDefinition description="Last Name" name="lastname"/>
            <spmldsml:attributeDefinition description="Email Address" 
name="emailAddress"/>
         </spmldsml:schema>
         <supportedSchemaEntity entityName="spml2Person"/>
      </schema>
      <capabilities>
         <capability namespaceURI="urn:oasis:names:tc:SPML:2:0:async"/>
         <capability namespaceURI="urn:oasis:names:tc:SPML:2:0:batch"/>
         <capability namespaceURI="urn:oasis:names:tc:SPML:2:0:bulk"/>
         <capability namespaceURI="urn:oasis:names:tc:SPML:2:0:password"/>
         <capability namespaceURI="urn:oasis:names:tc:SPML:2:0:suspend"/>
         <capability namespaceURI="urn:oasis:names:tc:SPML:2:0:search"/>
      </capabilities>
   </target>
</listTargetsResponse>