4 Preparing Your Application for Oracle WebCenter Services

4.1.1 How to Prepare Your Application to Consume Services

You can configure any application to include a WebCenter service. When you create an application in JDeveloper, you can choose to base the application on a template. Although not a requirement, the WebCenter Application template makes all the appropriate WebCenter connection wizards and tag libraries readily visible and available in the New Gallery and Component palette. When you consume a WebCenter services task flow or component, the necessary libraries are automatically added to the project.Depending upon the service you plan to consume, your application must meet certain prerequisites. For example, if the service must know the identity of users, then your application must provide some level of security with user authentication.

This section includes the following sub-sections:

• Section 4.1.1.1, "Implementing Security for Services"

• Section 4.1.1.2, "Setting Up SSL-Protected Connections for Services"

4.1.1.1 Implementing Security for Services

Some services must know the identity of the user (for example, the Search service needs the user's identity for saving searches). For these services, you must at least configure your application to authenticate users such that they have distinct identities for the purposes of personalization and user preferences.

For details on how to implement a basic security solution for your WebCenter custom application, see Section 3.5.1, "How to Configure ADF Security." For details on how to implement a complete security solution for your custom application, see Chapter 37, "Securing Your WebCenter Application."

After you configure ADF security for your application, you can open the jazn-data.xml file and modify your sample user's privileges for each task flow. To open the ADF Security Policies Editor, locate the file in the Application Resources panel and double-click its name. You see the default task flow grants, as shown in Figure 4-1. You can further configure these grants in this view.

Figure 4-1 ADF Security Policies in the jazn-data.xml file

Description of "Figure 4-1 ADF Security Policies in the jazn-data.xml file"

4.1.2 Setting Up an External Application Connection

When a WebCenter service interacts with an application that handles its own authentication, you can associate that application with an external application definition to allow for credential provisioning.

The following WebCenter services permit the use of an external application to connect with the service and define authentication for it:

• Documents

• Instant Messaging and Presence

• Mail

• RSS Viewer (when using a secured RSS feed)

For more information about setting up the external application for a WebCenter service, see Chapter 14, "Integrating the Documents Service," Chapter 18, "Integrating the Instant Messaging and Presence Service," Chapter 19, "Integrating the Mail Service," and Chapter 15, "Integrating the RSS Service." For more information about external applications in general, see Section 37.2, "Working with External Applications."

4.1.3 Automated Task Flow Grants

Table 4-1 lists the grants that are given when a task flow from the corresponding service is consumed. Common grants are granted whenever any Oracle WebCenter service is consumed.

In addition to the services in Table 4-1, grants are also given when the External Application - Change Password task flow is applied when creating an external application in Oracle JDeveloper. Specifically, the TaskflowPermission is given and placed in /oracle/adfinternal/extapp/view/fragments/.*.

4.2.1 Introducing the Resource Action Handling Framework

Custom components are just like out-of-the-box WebCenter services in that they manage and own resources. As such, they must make declarations that enable their resources to be accessible to the WebCenter services that invoke other services (that is, the Search, Tags, Links, and Recent Activities services). WebCenter provides a Resource Action Handling framework for services that expose resources to be viewed, searched, and tagged.

For example, the Resource Action Handling framework enables the Search service to look up and follow the mechanism to render a resource for any given service. Other facilities of the Resource Action Handling framework allow for authorization of resources to be declared and enforced when access is made.

The following resources invoke resource viewers using the Resource Action Handling framework:

• Search

• Tags

• Links

• Recent Activities

• People Connections

  • Activity Stream (invoking itself)

  • Connections (invoking itself)

  • Feedback (invoking itself)

  • Profile (invoking Tags, Tagged Items, and itself)

  • Message Board (invoking itself)

• External links pointing into WebCenter (from, for example, mail, documents, RSS feeds, or REST XML)

The following resources own task flows that can be invoked by the Resource Action Handling framework.

• Announcements

• Discussions

• Documents (URL rewriter points to the GET handler)

• Events

• Group Spaces (URL rewriter that maps to /webcenter/spaces/Space1Name)

• Mail

• Notes

• Page

• People Connections

  • Activity Stream - Main View

  • Connections

  • Feedback

  • Profile

  • Profile Gallery

  • Message Board

• Tags - Tag Center

4.2.2 Registering a Resource Viewer

You must register a resource viewer to enable custom resources to be rendered using Search or Tags, or to make the resources linkable to and from each other.

In the service-definition.xml file, you can define a resource viewer for any service to render that service's resources. The viewer can be a task flow or a URL rewriter acting on the resource ID.

For example, suppose a discussion forum message is found through the Search service. Clicking the result link launches the resource viewer that was declared for the Discussions service (by looking up the service-definition.xml of the Discussions service). By default, the target is rendered in a dialog.

To register a custom resource viewer:

1. In the Application Navigator, right-click the Page Flows node for the ViewController project and select New from the context menu.

2. Under Categories, select JSF, then ADF Task Flow.

3. Click OK.

4. In the Create Task Flow dialog, change File Name to resource-viewer.xml. The Task Flow ID should automatically update to resource-viewer (Figure 4-4).

   Figure 4-4 Create Task Flow Dialog for Resource Viewer

   
   Description of "Figure 4-4 Create Task Flow Dialog for Resource Viewer"
   
   

5. Click OK.

   Ensure that the resource-viewer.xml file is created under ..\public_html\WEB-INF.

6. From the Component Palette, ensure that ADF Task Flow is selected and drag View onto the task flow to create a page fragment.

7. Rename the page fragment to resource-viewer, and click in an open area of the canvas to accept the change.

8. Define a JSFF file for your page fragment.

9. Double-click the page fragment.

10. Click OK in the Create New JSF Page Fragment dialog.

11. Go to the Source view in the editor and paste an af:outputText tag inside of the jsp:root element.

    Example 4-1 provides a very simple resource viewer. You could create a much more complex viewer.

    Example 4-1 Simple Resource Viewer

    <jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0"
              xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
      <af:outputText value="Rendering #{pageFlowScope.resourceId}"
                     inlineStyle="font-size:5"/>
    </jsp:root>
    

12. Add a resourceId input parameter to the task flow, and set the value to #{pageFlowScope.resourceId}.

13. After the task flow is defined, you must register it in the service-definition.xml file. In the Application Navigator, expand Application Resources, Descriptors and ADF META-INF.

14. Double-click service-definition.xml to open it in the editor.

15. In the file, you see a service definition that has been commented out. Uncomment it by removing the <!-- and --> tags around it.

16. Set the id attribute to the service identifier.

    For example, the service identifier used when defining the Tagging Button could be mycompany.myproduct.myapp.mycomponent.

17. Set the taskFlowId to /WEB-INF/resource-viewer.xml#resource-viewer.

    This identifier is the task flow path and file name concatenated with the task flow identifier declared in the Create Task Flow dialog. You can omit the remaining tags.

18. The <resource-view> declaration has a class specification for the resource authorizer. This provides various ways to specify the resource view and determine which tagged objects are visible (and searchable) to users.

    Example 4-2 Specifying a Task Flow ID in a resource-view Declaration

    <resource-view taskFlowId="/somepath/somefile.xml#someId"
                   authorizerClass="some.service.id.Authorizer1"/>
    

    The Search, Tags, and Discussions services use this type of declaration. Instead of having a view ID (JSPX page), the service supplies a task flow to render the resource.

    • The attribute taskFlowId signifies that the renderer is a task flow.

    • A task flow is used to render the resource specified by the resource ID.

    • The task flow honors a resourceId input parameter and uses that to render the resource.

    Example 4-3 Specifying a URL Rewriter Class Name (1)

    <resource-view urlRewriterClass="oracle.webcenter.framework.internal.resource.IdentityResourceUrlRewriter"
                   authorizerClass="some.service.id.Authorizer5"/>
    

    or

    Example 4-4 Specifying a URL Rewriter Class Name (2)

    <resource-view urlRewriterClass="oracle.webcenter.framework.internal.resource.MessageFormatResourceUrlRewriter"
                   authorizerClass="some.service.id.Authorizer4">
      <parameters>
        <!-- This starts from the context root which would be /webcenter -->
        <parameter name="message" value="/content/conn/UCM/path/{0}"/>
      </parameters>
    </resource-view>
    

    or

    Example 4-5 Specifying a URL Rewriter Class Name (3)

    <resource-view urlRewriterClass="oracle.webcenter.framework.internal.resource.MyResourceUrlRewriter"
                   authorizerClass="some.service.id.Authorizer6">
      <parameters>
        <parameter name="myParam" value="myValue"/>
      </parameters>
    </resource-view>
    

    Services, such as Oracle SES and Documents, use a URL rewriter to treat the resource ID as a URL and rewrite the URL in an appropriate fashion. A URL rewriter changes the resource ID into a URL that can be launched with a goLink. Two ResourceUrlRewriters are provided:

    • oracle.webcenter.framework.internal.resource.IdentityResourceUrlRewriter is for Oracle SES. It takes the resourceId value as a URL as is.

    • oracle.webcenter.framework.internal.resource.MessageFormatResourceUrlRewriter is for Documents. It takes in a message parameter (in the service-definition). The message parameter contains a {0}, which is replaced with the value of the resourceId. The urlExternal parameter applies to all URL rewriters. This parameter's value determines whether the JSPX that consumes a resource action handler link should open a new window.

    The default behavior is to launch a new window dialog with that URL.

    Some resources, like pages and wikis, can have no resource viewer but may allow dubbing their resource IDs as page view IDs (Example 4-6).

    Example 4-6 No Resource Viewer (Resource ID as Page View ID)

    <resource-view authorizerClass="some.service.id.Authorizer3"/>
    

    The resource authorizer interface uses Java interfaces and classes to return useful information about service resources. For example, the oracle.webcenter.framework.resource.ResourceAuthorizer interface contains a method that returns the status (available or not available) for a unique resource ID (Example 4-7).

    Example 4-7 Method for Returning Status Against a Unique Resource ID

    /*
     * Check if the passed in resourceIds are viewable by the current user.
     *
     * @param resourceId - the resourceId that we want to check
     * @return - a <code>ResourceInfo</code> with a ResourceStatus
     * of RESOURCE_IS_AVAILABLE if the passed in resourceId
     * is viewable by current user, otherwise returns
     * <code>RESOURCE_IS_NOT_AVAILABLE</code>.
     */
    ResourceInfo getResourceInfo(String resourceId, Scope scope);
     
    /*
     * Check if the passed in resourceIds are viewable by the current user.
     *
     * @param resourceIds - the resourceIds that we want to check
     * @return - a List of <code>ResourceInfo</code> with a ResourceStatus
     * of RESOURCE_IS_AVAILABLE if the passed in resourceId
     * is viewable by current user, otherwise returns
     * <code>RESOURCE_IS_NOT_AVAILABLE</code>.
     */
    List<ResourceInfo> getResourceInfo(List<String> resourceIds, Scope scope);
    

    The oracle.webcenter.framework.resource.ResourceInfo interface exposes the following method:

    public ResourceStatus getResourceStatus();
    

    The oracle.webcenter.framework.resource.ResourceInfo.ResourceStatus enumeration includes the following possible values:

    Example 4-8 Possible ResourceStatus Values

    /**
     * Used to describe a related object's status.
     *
     * Certain operations may be performed by relationship service depending
     * on what object status it receives from the service.  For example,
     * if it receives {@link #RESOURCE_DOES_NOT_EXIST} it may remove all
     * relationships associated with this object from the relationship schema
     * so future calls are not wasted on this object.
     */
     public enum ResourceStatus
     {
       /**
        * Used to describe a resource that is available.
        */
       RESOURCE_IS_AVAILABLE,
     
       /**
        * Used to describe a resource that does not exist.
        */
       RESOURCE_DOES_NOT_EXIST,
     
       /**
        * Should be used when the user does not have view access on the resource.
        */
       USER_DOES_NOT_HAVE_ACCESS;
     }
    

    The only method in the oracle.webcenter.framework.resource.ResourceUrlRewriter interface writes the URL, after a unique identifier is passed in. This URL can be an absolute URL or it can be one relative to the faces context root of the owning application.

    Example 4-9 Resource URL Rewriter Method

    public String rewriteUrl(String id);
    

19. Your service should look similar to the one shown in Example 4-10.

    Example 4-10 Sample Service Definition for Resource View

    <service-definitions>
      <service-definition id="mycompany.myproduct.myapp.mycomponent"
                          version="11.1.1.0.0">
      <resource-view taskFlowId="/somepath/somefile.xml#someId"
    authorizerClass="mycompany.myproduct.myapp.mycomponent.ResourceAuthorizer"/>
      <name>My Custom Component</name>
      <description>My Custom Component's Description</description>
      <icon>/mycompany/myproduct/myapp/mycomponent/component.png</icon>
      </service-definition>
     ...
    </service-definitions>
    

20. Save the service-definition.xml file.

4.3.1 Building a Preferences User Interface

You can build a user interface using the General Settings API to enable users to either accept the default settings or apply their desired settings. The API contains the same preference values described in Table 4-2.

Any WebCenter service that displays a date and time uses the settings configured in the General Settings service. For information on using the General Settings Service API to build a preferences user interface, see the Javadoc for oracle.webcenter.generalsettings. Specifically, the oracle.webcenter.generalsettings.model package contains APIs to get and set preference values for each of the settings. Use these APIs to build a custom user interface to allow users to view and set their preferred values.

For more information, see Oracle Fusion Middleware Java API Reference for Oracle WebCenter.