Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle WebCenter
11g Release 1 (11.1.1)

Part Number E10148-02
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

11 Preparing Your Application for Oracle WebCenter Web 2.0 Services

This chapter describes how to prepare your application to consume Oracle WebCenter Web 2.0 services. It contains the following sections:


For important basic information about WebCenter applications, such as how to create an application, how to create customizable pages, and how to implement security, see Chapter 3, "Preparing Your Development Environment."

For conceptual information about WebCenter Web 2.0 services, see Section 1.1.4, "Introduction to Oracle WebCenter Web 2.0 Services."

11.1 Preparing Your WebCenter Application to Consume Services

This section describes the steps you must take to prepare your application to use Oracle WebCenter Web 2.0 services. It contains the following subsections:

11.1.1 How to Prepare Your Application to Consume Services

You can configure any application to include a WebCenter Web 2.0 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 needs to know the identity of users, then your application must provide some level of security with user authentication. 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 24, "Securing Your WebCenter Application."

Once 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 pane and double-click its name. You will see the default task flow grants, as shown in Figure 11-1. You can further configure these grants in this view.

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

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

11.1.2 Setting Up an External Application Connection

When a WebCenter Web 2.0 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 Web 2.0 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 Web 2.0 service, see Chapter 14, "Integrating the Documents Service," Chapter 15, "Integrating the Instant Messaging and Presence Service," Chapter 17, "Integrating the Mail Service," and Chapter 19, "Integrating the RSS Service." For more information about external applications in general, see Section 24.2, "Working with External Applications."

11.1.3 Automated Task Flow Grants

Table 11-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 Web 2.0 service is consumed.

Table 11-1 Automated Task Flow Grants

Service Grant Actions Name (Target)
















































External Application





Instant Messaging and Presence























Page Editor




















Recent Activities









































In addition to the services in Table 11-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/.*.

11.2 Extending Your Application with Custom Components

This section introduces the Resource Action Handling Framework and describes how to register a resource viewer. It contains the following subsections:

11.2.1 Introducing the Resource Action Handling Framework

Custom components are just like out-of-the-box WebCenter Web 2.0 services in that they manage and own resources. As such, they must make declarations that enable their resources to be accessible to the WebCenter Web 2.0 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 services invoke resource viewers using the Resource Action Handling framework:

  • Search

  • Tags

  • Links

  • Recent Activities

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

  • Announcements

  • Discussions

  • Documents (Resource URL rewriter to point to GET handler)

  • Events

  • Mail

  • Notes

  • Page (Resource URL rewriter to point to page URL)

  • Tags - Tag Center

11.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.


When you add a Search, Tags, or Recent Activities task flow to your application, that service creates a sample service-definition.xml file. This file enables developers to declare their resource viewers as well as their implementations of interfaces for interacting with the Links and Search services; for example, the QueryManager interface implementation.

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 ADF Task Flow dialog, change File Name to resource-viewer.xml. The Task Flow ID should automatically update to resource-viewer (Figure 11-2).

    Figure 11-2 Create ADF Task Flow Dialog for Resource Viewer

    Description of Figure 11-2 follows
    Description of "Figure 11-2 Create ADF 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, make sure 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 11-1 provides a very simple resource viewer. You could create a much more complex viewer.

    Example 11-1 Simple Resource Viewer

    <jsp:root xmlns:jsp="" version="2.0"
      <af:outputText value="Rendering #{pageFlowScope.resourceId}"
  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 will find 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 ADF 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 11-2 Specifying a Task Flow ID in a resource-view Declaration

    <resource-view taskFlowId="/somepath/somefile.xml#someId"

    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 11-3 Specifying a URL Rewriter Class Name (1)

    <resource-view urlRewriterClass="oracle.webcenter.framework.internal.resource.IdentityResourceUrlRewriter"


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

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


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

    <resource-view urlRewriterClass="oracle.webcenter.framework.internal.resource.MyResourceUrlRewriter"
        <parameter name="myParam" value="myValue"/>

    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 services, like the Page service, can have no resource viewer but may allow dubbing their resource IDs as page view IDs (Example 11-6).

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

    <resource-view authorizerClass=""/>

    The resource authorizer interface makes use of 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 11-7).

    Example 11-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 11-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.
        * Used to describe a resource that does not exist.
        * Should be used when the user does not have view access on the resource.

    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 11-9 Resource URL Rewriter Method

    public String rewriteUrl(String id);
  19. Your service should look similar to the one shown in Example 11-10.

    Example 11-10 Sample Service Definition for Resource View

      <service-definition id="mycompany.myproduct.myapp.mycomponent"
      <resource-view taskFlowId="/somepath/somefile.xml#someId"
      <name>My Custom Component</name>
      <description>My Custom Component's Description</description>
  20. Save the service-definition.xml file.

11.3 Configuring General Settings for Your Services

Optionally, you can enable users to set the time zone, the date and time format, the language (locale), and the accessibility mode for the services you add to your application. You can provide these capabilities through the WebCenter General Settings Service. This service contains values that you can modify either directly from the JSF page(s) in your WebCenter application or indirectly, through an API. The WebCenter General Settings Service covers five areas:

To use the service directly from your application, you can use Expression Language in your JSF pages to access the generalSettings managed Bean. When you add generalSettings as the value attribute of an ADF component, for example af:activeOutputText, you can open the Expression Builder, then navigate to JSF Managed Beans > generalSettings to view the preference values for the bean.

Figure 11-3 Expression Builder for the generalSettings JSF Managed Bean

Description of Figure 11-3 follows
Description of "Figure 11-3 Expression Builder for the generalSettings JSF Managed Bean"

Table 11-2 describes the seven different preference values for the General Settings service.

Table 11-2 General Settings Managed Bean Preference Values and Descriptions

General Settings Preference Value Description


Displays the current date in the user's selected locale.


Displays the current date and time in the user's selected locale.


Displays the current time in the user's selected locale.


Displays the preferred accessibility mode (default, inaccessible, or screenReader).


Java date style to be used in dateStyle attributes when displaying dates and times.


Java time style to be used in timeStyle attributes when displaying dates and times.


Java timezone to be used in timeZone attributes when displaying dates and times.

For example, to display the current date and time in the user's selected locale, time zone, and format, add the following to your page:

Example 11-11 Code for Displaying Current Date and Time in User's Locale

<af:outputText value="#{generalSettings.formattedCurrentDateTime}"/>

Or, to display a specific date and time:

Example 11-12 Code for Displaying Specified Date and Time

<af:outputText value="#{row.dateTimeValue}">
    <af:convertDateTime type="both"
                        locale="#{facesContext.externalContext.requestLocale}" />

To take advantage of the preferred accessibility mode, you must add an EL (Expression Language) expression to the application's trinidad-config.xml file to set the accessibility mode, for example:

Example 11-13 Setting the Accessibility Mode in trinidad-config.xml


You can also 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 seven preference values as described in Table 11-2.

Any WebCenter Web 2.0 service that displays a date and time uses the settings configured in the General Settings service. For more information on using the General Settings Service API to build a General Settings User Interface, see the Javadoc for oracle.webcenter.generalsettings.