10 Integrating with Oracle WebCenter Spaces

10.2.3.1 Verifying That WebCenter Spaces Is Up and Running

If you want to use the WebCenter SpacesAPIs, the WebCenter Spaces application must be up and running.

To verify that WebCenter Spaces is up and running:

1. Start WebCenter Spaces. The URL is:

   http://host:port/webcenter
   

   You do not need to log in.

2. Verify that the WebCenter Spaces Web service is up and running. The URL is:

   http://host:port/webcenter/SpacesWebService?WSDL
   

   You should see a page similar to the one shown in Figure 10-6. If you do not see this page, contact your Fusion Middleware administrator.

   Figure 10-6 SpacesWebService WSDL

   
   Description of "Figure 10-6 SpacesWebService WSDL"
   
   

For more information about setting up WebCenter Spaces, see the "Getting WebCenter Spaces Up and Running" chapter in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

10.2.3.2 Setting Up the Custom WebCenter Application to Use WebCenter Spaces APIs

Before you can call the WebCenter Spaces APIs in your custom WebCenter application, you must ensure that your application contains the correct libraries and that there is a connection to the WebCenter Spaces Web service.

To set up your application to use the WebCenter Spaces APIs:

1. Start JDeveloper.

2. In the Application Navigator, expand the application for which you want to provide group space functionality.

   The application should be based on the WebCenter Application template.

3. Right-click the view-controller project and choose Project Properties.

4. Select Libraries and Classpath.

5. Check that the following libraries are available in your project, adding any as necessary:

   • ADF DVT Faces Runtime

   • ADF Model Generic Runtime

   • ADF Model Runtime

   • JAX-RPC Client

   • JAX-WS Client

   • JAXB

   • Oracle JEWT

   • WebCenter Spaces Client

   • JDEV_HOME/jdeveloper/modules/oracle.adf.model_11.1.1/adfm.jar

   • JDEV_HOME/jdeveloper/modules/oracle.xdk_11.1.1/xml.jar

6. Click OK.

7. In the Application Resources panel of the Application Navigator, right-click Connections and choose New Connection > URL.

8. In the Name field, enter SpacesWebServiceEndpoint.

9. In the URL Endpoint field, enter the WebCenter Spaces Web service URL:

   http://host:port/webcenter/SpacesWebService
   

10. Click OK.

    The connection information is added to the connections.xml file in the application's META-INF directory, for example:

    C:\JDeveloper\mywork\mySpacesApplication\.adf\META-INF
    

    If the connections.xml file does not exist, it is created.

11. Open the connections.xml file and verify that the code shown in Example 10-1 appears:

    Example 10-1 WebCenter Spaces Web Service Endpoint URL Connection

    <Reference name="SpacesWebServiceEndpoint"
    className="oracle.adf.model.connection.url.HttpURLConnection">
    <Factory className="oracle.adf.model.connection.url.URLConnectionFactory"/>
    <RefAddresses>
      <XmlRefAddr addrType="SpacesWebServiceEndpoint">
        <Contents>
          <urlconnection name="SpacesWebServiceEndpoint"
          url="http://host:port/webcenter/SpacesWebService"/>
        </Contents>
      </XmlRefAddr>
    </RefAddresses>
    </Reference>
    

    If you need to set the WebCenter Spaces Web service endpoint at runtime, you can use the setGroupSpaceWebServiceEndpoint API (Example 10-2). You can write a wrapper API that takes the endpoint as a parameter and then calls setGroupSpaceWebServiceEndpoint, passing the parameter. An exception is raised if the endpoint is already set in connections.xml.

    Example 10-2 Setting the WebCenter Spaces Web Service Endpoint at Runtime

    client.setGroupSpacesWebServiceEndpoint("http://myserver.example.com/webcenter/SpacesWebService");
    

10.2.3.3 Securing the Connection Between the Application and WebCenter Spaces

Before using the WebCenter Spaces APIs in your custom WebCenter application, you must ensure that the communication between the application (the consumer) and WebCenter Spaces (the producer) is secure. This is so that the identity of the user invoking the APIs is propagated to WebCenter Spaces in a secure manner where the integrity and confidentiality of the communication is maintained.

To do this, the WebCenter Spaces APIs use a policy of SAML based token passing with message protection. Your administrator must create a Java keystore and update the credential store so that WebCenter Spaces can verify the authenticity of the security tokens received from your application. You must then register this keystore and update the credential store using JDeveloper.

For information about the steps that the administrator must perform, see "Securing WebCenter Spaces for Applications Consuming Spaces Client APIs with WS-Security" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

Before You Begin

Obtain the following from your administrator:

• Consumer keystore to use to secure the connection. This is a .jks file (for example, consumer.jks).

• Consumer public alias key stored in the keystore (for example, consumer).

• Password of the consumer public alias key (for example, mypassword1).

• Producer public alias key stored in the consumer keystore (for example, producer). This is the alias specified by the administrator when importing the trusted certificate of the producer.

• Consumer keystore password (for example, mypassword2).

To secure the connection:

1. Copy the keystore to the file system where your custom WebCenter application is running, for example:

   domain_home/config/fmwconfig
   

2. Open the jps-config.xml file and configure the keystore created by your administrator (Example 10-3).

   Example 10-3 Keystore Instance in jps.config.xml

   <!-- KeyStore Service Instance -->
       <serviceInstance name="keystore" provider="keystore.provider"
       location="./consumer.jks">
           <description>Default JPS Keystore Service</description>
           <property name="keystore.type" value="JKS"/>
               <property name="keystore.csf.map" value="oracle.wsm.security"/>
           <property name="keystore.pass.csf.key" value="keystore-csf-key"/>
           <property name="keystore.sig.csf.key" value="enc-csf-key"/>
           <property name="keystore.enc.csf.key" value="enc-csf-key"/>
       </serviceInstance>
   

   You can use Fusion Middleware Control to specify the keystore location if you prefer. For more information see "Registering the Keystores" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

3. Take a backup of cwallet.sso.

4. Open a command line prompt.

5. Navigate to the directory where JDeveloper is installed, for example:

   C:\Jdev\jdeveloper\common\bin
   

6. Run the following command:

   • In Windows: wlst.cmd

   • In Linux: ./wlst.sh

7. Run:

   connect('admin_user', 'admin_password', 'host:port')
   

   Where:

   • admin_user is the user name for the administrator of the server on which the application is running (for example, weblogic)

   • admin_password is the password for the administrator (for example, weblogicpwd1)

   • host:port is the server on which the application is running

8. Run the following commands:

   createCred(map="oracle.wsm.security", key="enc-csf-key", user="alias", password="key_password", desc="Enc Password")
   
   createCred(map="oracle.wsm.security", key="sign-csf-key", user="alias", password="key_password", desc="Enc Password")
   
   createCred(map="oracle.wsm.security", key="keystore-csf-key", user="keystore-csf-key", password="keystore_password", desc="Keystore password")
   

   Where:

   • alias is the consumer public alias key in the keystore

   • key_password is the password for the public key

   • keystore_password is the keystore password

   You can obtain this information from your administrator, as detailed in the "Before You Begin" section.

   If you need any additional help to run these commands, see the "createCred" section in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

   You can use Fusion Middleware Control to update the credential store if you prefer. For more information see the "Securing WebCenter Spaces for Applications Consuming Spaces Client APIs with WS-Security" section in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

9. Restart the server on which your application is deployed, and then your default server.

10.2.3.4 Setting Up the Group Space Client Context

Before calling any of the WebCenter Spaces APIs in your application code, a few setup steps are required.

To set up the group space client context

1. Domain-wide configuration settings are used when you call WebCenter Spaces APIs from an application deployed on WebLogic Server (WLS), unless you specifically choose to override them. To override or set security configuration parameters, use the APIs provided by the GroupSpaceWSContext class.

   In particular, you must set the SAML issuer name and the public key alias for WebCenter Spaces, which are required for data encryption. If the WebCenter Spaces Web service endpoint is not set in the connections.xml file, you can set this too.

   For example:

   GroupSpaceWSContext context = new GroupSpaceWSContext();
   
   context.setEndPoint("endPointUrl");
   context.setSamlIssuerName("samlIssuer");
   context.setRecipientKeyAlias("producer");
   
   groupSpaceWSClient = new GroupSpaceWSClient(context);
   

   Where:

   • endPointUrl is the WebCenter Spaces Web service endpoint, for example, http://server.example.com:8912/webcenter/SpacesWebService).

   • samlIssuer is the issuer URI of the SAML Authority issuing assertions for this SAML Asserting Party (for example, http://www.example.com/webcenter)

   • producer is the public key alias for WebCenter Spaces, for example, wcspaces.

     You can obtain this information from your administrator, as detailed in the "Before You Begin" section.

   For a full list of the APIs provided by the GroupSpaceWSContext class, see the Oracle Fusion Middleware WebCenter Group Spaces Java API Reference.

2. Initialize the group space client by passing the context. For example:

   GroupSpaceWSClient client = new GroupSpaceWSClient(context);
   

3. Once you have initialized the client, check everything is set up correctly by calling:

   getWebCenterSpacesURL();
   

   If the correct URL is returned, everything is set up correctly and you can start using the group space APIs.

10.2.4.1 Managing Group Spaces and Templates

Use the following WebCenter Spaces APIs to manage your group spaces:

• createGroupSpace

• setCustomAttribute

• createGroupSpaceTemplate

• deleteGroupSpace

Before you begin

Before using any of these APIs, you must complete all the steps listed in Section 10.2.3, "How to Set Up Your Custom WebCenter Application to Use the WebCenter Spaces APIs."

This section includes the following subsections

• Creating a Group Space

• Creating a Custom Attribute

• Creating a Group Space Template

• Deleting a Group Space

//create the group space
GroupSpaceWSMetadata gsMetadata = 
client.createGroupSpace("Databases", "Databases" "A community for people interested in databases", "databases, oracle", "CommunityofInterest");
//print the group space GUID to provide confirmation of creation
System.out.println("GUID: " + gsMetadata.getGuid());

//create the group space
client.createGroupSpace("Databases", "Databases", "A community for people interested in databases", null, "CommunityofInterest");
//create the custom attribute
client.setCustomAttribute("Databases", "Vendors", "List of vendors", "java.lang.String", "Oracle, IBM");

GroupSpaceWSMetadata templMetadata =
client.createGroupSpaceTemplate("DatabasesTemplate", "Databases Template", 
"A template based on the Databases group space", "Databases");
//print the template GUID to provide confirmation of creation
System.out.println("GUID: " + templMetadata.getGuid());

//delete the group space
Boolean success = client.deleteGroupSpace("Databases");
//print a message depending on the result of the deletion
if(success)
{
  System.out.println("Operation Succeeded");
}
else
{
  System.out.println(Operation Failed");
}

10.2.4.2 Managing Group Space Membership

Use the following group space APIs to manage group space membership:

• addMember

• inviteMember

• removeMember

• getRoles

Before you begin

Before using any of these APIs, you must complete all the steps listed in Section 10.2.3, "How to Set Up Your Custom WebCenter Application to Use the WebCenter Spaces APIs."

This section includes the following subsections:

• Adding Members to a Group Space

• Inviting Users to Join a Group Space

• Removing Members from a Group Space

• Retrieving Role Information

//create the list of users
List addMem = new ArrayList();
//create the GroupSpaceWSMembers objects
GroupSpaceWSMembers mem1 = new GroupSpaceWSMembers("pat", "viewer");
GroupSpaceWSMembers mem2 = new GroupSpaceWSMembers("vicki", "participant");
//add the GroupSpaceWSMembers objects to the list of users
addMem.add(mem1);
addMem.add(mem2);
//add the users to the group space
client.addMember("Databases", addMem);
//print a list of members to confirm the new members were added
GroupSpaceWSMetadata memMetData = client.getGroupSpaceMetadata("Databases");
for (GroupSpaceWSMembers mems: memMetData.getMembers())
{
  System.out.println(mems.getMember());
  System.out.println(mems.getRole());
}

//create the list of users
List inviteMem = new ArrayList();
//create the GroupSpaceWSMembers objects
GroupSpaceWSMembers mem1 = new GroupSpaceWSMembers("pat", "viewer");
GroupSpaceWSMembers mem2 = new GroupSpaceWSMembers("vicki", "participant");
//add the GroupSpaceWSMembers objects to the list of users
inviteMem.add(mem1);
inviteMem.add(mem2);
//invite the list of users to join the group space
client.inviteMember("Databases", inviteMem);

//create the list of users
List remMem = new ArrayList();
//create the GroupSpaceWSMembers objects
GroupSpaceWSMembers mem1 = new GroupSpaceWSMembers("pat");
GroupSpaceWSMembers mem2 = new GroupSpaceWSMembers("vicki");
//add the GroupSpaceWSMembers objects to the list of users
remMem.add(mem1);
remMem.add(mem2);
//remove the users from the group space
client.removeMember("Databases", remMem);
//print a list of members to confirm the members were removed
GroupSpaceWSMetadata memMetData = client.getGroupSpaceMetadata("Databases");
for (GroupSpaceWSMembers mems: memMetData.getMembers())
{
  System.out.println(mems.getMember());
  System.out.println(mems.getRole());
}

//retrieve the list of roles
List<String> roles = client.getRoles("Databases");
//print the list of roles
for (String role: roles)
{
  System.out.println(role);
}

10.2.4.3 Retrieving Group Space and Template Information

Use the following group space APIs to retrieve group space information:

• getGroupSpaces

• getPublicGroupSpaces

• getGroupSpaceMetadata

• getGroupSpaceMetadataByGuid

• getGroupSpaceTemplates

• getGroupSpaceTemplateMetadata

• getGroupSpaceTemplateMetadataByGuid

• getWebCenterSpacesURL

• getGroupSpaceURL

Before you begin

Before using any of these APIs, you must complete all the steps listed in Section 10.2.3, "How to Set Up Your Custom WebCenter Application to Use the WebCenter Spaces APIs."

This section includes the following subsections

• Retrieving a List of Group Spaces

• Retrieving a List of Public Group Spaces

• Retrieving Group Space Metadata

• Retrieving a List of Group Space Templates

• Retrieving Group Space Template Metadata

• Retrieving the WebCenter Spaces URL

• Retrieving a Group Space URL

List<String> allGroupSpaces = client.getGroupSpaces("Database");

List<String> allGroupSpaces = client.getGroupSpaces(null)

List<String> allPublicGroupSpaces = client.getPublicGroupSpaces("Database");

List<String> allPublicGroupSpaces = client.getPublicGroupSpaces(null)

getGroupSpaceMetadata("spaceName").getGuid();

//get the exact name of the group space
List<String> myGroupSpace = client.getGroupSpaces("Databases");
//check that the API returns a single result
if(myGroupSpace.size() == 1)
{
  //retrieve the metadata
  GroupSpaceWSMetadata metadata = client.getGroupSpaceMetadata(myGroupSpace);
  //get group space description
  System.out.println("Description: " + metadata.getDescription());
  //get group space keywords
  System.out.println("Keywords: " + metadata.getKeywords());
  //get the date the group space was last updated
  System.out.println("Last Updated Date: "+ metadata.getLastUpdated().toString());
}

GroupSpaceWSMetadata metadata = client.getGroupSpaceMetadataByGuid("Guid");
//get group space display name
System.out.println("Display Name: " + metadata.getDisplayName());
//get the name of the user who created the group space
System.out.println("Created By: " + metadata.getCreatedBy());
//get the date the group space was last updated
System.out.println("Last Updated Date: " + metadata.getLastUpdated().toString());

//get the exact name of the group space
List<String> myGroupSpace = client.getGroupSpaces("Databases");
//check that the API returns a single result
if(myGroupSpace.size() == 1)
{
  //retrieve the metadata
  GroupSpaceWSMetadata metadata = client.getGroupSpaceMetadata(myGroupSpace);
  //get list of custom attributes
  List<CustomMetadata.Attribute> attributes = metadata.getCustomAttributes();
  //get name, description, type, and value for each custom attribute
  for(CustomMetadata.Attribute attribute: attributes)
  {
    System.out.println("Name :" + attribute.getName());
    System.out.println("Description :" + attribute.getDescription());
    System.out.println("Type :" + attribute.getType());
    System.out.println("value.toString() :" + attribute.getValue().toString());
  }
}

//get the exact name of the group space
List<String> myGroupSpace = client.getGroupSpaces("Databases");
//check that the API returns a single result
if(myGroupSpace.size() == 1)
{
  //retrieve the metadata
  GroupSpaceWSMetadata metadata = client.getGroupSpaceMetadata(myGroupSpace);
  //get the list of members
  for(String member: metadata.getMembers())
  {
    System.out.println("Member UID: " + member);
  }
}

List<String> allGroupSpaceTemplates = client.getGroupSpaceTemplates("Interest");

List<String> allGroupSpaceTemplates = client.getGroupSpaceTemplates(null);

GroupSpaceWSMetadata metadata = client.getGroupSpaceTemplateMetadata(myGroupSpaceTemplate);
//get the exact name of the group space template
List<String> myGroupSpaceTemplate = client.getGroupSpaceTemplates("CommunityofInterest");
//check that the API returns a single result
if(myGroupSpaceTemplate.size() == 1)
{
  //retrieve the metadata -- get GUID
  System.out.println("GUID: " + metadata.getGuid());
  //get template description
  System.out.println("Description: " + metadata.getDescription());
  //get name of user who created the template
  System.out.println("Keywords: " + metadata.getCreatedBy());
}

GroupSpaceWSMetadata templGuidMetadata = client.getGroupSpaceTemplateMetadataByGuid("Guid");
System.out.println("Template Name: " + templGuidMetadata.getName());

String myWebCenterSpacesURL = client.getWebCenterSpacesURL();

String myGroupSpaceURL = client.getGroupSpaceURL("Databases");

//get the list of group spaces
List<String> spaces = client.getGroupSpaces("");
//print the list of group spaces as hyperlinks
for (String spaceName : spaces)
{
  print("<a href =""" + client.getGroupSpaceURL(spaceName) + "">" + spaceName + "</a><br>");
}

10.2.5.1 Providing Localized Error Messages

Sometimes you may find that the default error messages provided by the APIs are not specific enough for your particular application. In these cases you can provide your own error messages.

Use the getLocalizedMessage API to compose application-specific error messages.

Example 10-27 shows a servlet that includes code to create a group space. If any exceptions are raised during the creation process, a localized message is printed.

servlet1.java

doGet()
{
...
  print("<b>Output</b>");
  try
    {
      GroupSpaceWSClient client = new GroupSpaceWSClient(context);
      client.createGroupSpace("Databases", "Databases, "A community for people interested in databases", "databases, oracle", "CommunityofInterest");
      print("Successfully created group space");
    }
  catch(GroupSpaceWSException ex)
    {
      if(ex instanceof GroupSpaceNameNullException)
        print(ex.getLocalizedMessage());
      else if (ex instanceof GroupSpaceDescNullException)
        print(ex.getLocalizedMessage());
    }
...
}

10.2.5.2 Listing the Error Stack

For debugging purposes, it is often useful to see which errors ultimately led to the failure of a particular operation to discover the underlying cause of the problem. Use the printStackTrace API to list all the errors that caused a particular exception.

Example 10-28 prints the exception and all the errors leading up to it.

servlet1.java

doGet()
{
...
  print("<b>Output</b>");
  try
    {
      GroupSpaceWSClient client = new GroupSpaceWSClient(context);
      client.createGroupSpace("Databases", "Databases", "A community for people interested in databases", "databases, oracle", "CommunityofInterest");
      print("Successfully created group space");
    }
  catch(GroupSpaceWSException ex)
    {
      ex.printStackTrace();
    }
...
}