Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle WebCenter Portal (Oracle Fusion Applications Edition)
11g Release 1 (11.1.1.6.2)

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

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

7 Preparing Your Application for WebCenter Portal Services

This chapter describes how to prepare your application to consume services in Oracle WebCenter Portal.

This chapter includes the following sections:

7.1 Understanding WebCenter Portal Services Technologies

Oracle WebCenter Portal Services enrich existing portals and Web sites with enterprise 2.0 capabilities, including social computing services, personal productivity services, online awareness and communications, content integration, and Web analytics.

See Also:

This section summarizes the key technologies available in services. This can help you determine which services to implement and the best way to customize your user interface.

This section includes the following subsections:

7.1.1 Understanding WebCenter Portal Horizontal Services

Some services in WebCenter Portal are considered horizontal services in that they interact with other services across an application.

Table 7-1 lists service integration in Oracle WebCenter Portal: Framework.

Table 7-1 Service Integration in WebCenter Portal

WebCenter Portal Services RSS Search Tags Links Comments and Likes Activity Stream Activity Graph Notifications Analytics

Activity Graph

         

X

n/a

 

X

Announcements

X

X

 

X

 

X

 

X

 

Blogs

 

X

X

X

X

X

X

X

X

Discussions

X

X

X

X

X (replies on topics)

X

X (replies)

X

 

Documents, including wikis

 

X

X

X

X

X

X

X

X

Events

 

X partial

 

X

 

X

 

X

 

Instant Messaging and Presence (IMP)

             

X

 

Lists

X

X

X

X

 

X

 

X

 

Mail

             

X

 

Notes

 

X

 

X

         

People Connections

 

X partial

X partial

 

X (Activity Stream, Message Board)

X (Message Board, Profiles, Feedback

X (Message Board)

X

X

Polls

                 

Recent Activities

X

               

Search

 

n/a

X

   

X partial

   

X

Tags

 

X

n/a

   

X

     

Notes:

Notes, space Events and Favorites are available only in WebCenter Portal: Spaces applications.

The Search service (listed in the table) uses WebCenter Portal search adapters to search each available service. However, large-scale implementations should be configured to use Oracle SES search for best performance. Oracle SES searches applications for the following resources:

  • Documents, including wikis and blogs

  • Announcements and Discussions

  • WebCenter Portal: Spaces applications only: spaces, lists, pages, and people resources in Spaces

For more information, see Chapter 45, "Integrating the Search Service."

7.1.2 Understanding WebCenter Portal APIs

This section describes the APIs available for WebCenter Portal services.

Note the following considerations when multiple customization options are available:

  • Use REST APIs to build a custom client for accessing WebCenter Portal: Spaces; for example, an iPhone application that interacts with Spaces.

  • REST APIs may provide the fastest and easiest way to customize the user interface and develop custom components. Consider using data controls or native APIs to build a custom user interface for accessing Spaces.

  • Use data controls or native APIs to build a custom portal or composite Framework application.

  • Use data controls or native APIs if you are proficient with Java, JDeveloper, and ADF. To use other languages, especially JavaScript, use REST APIs.

Table 7-2 lists services with available APIs. For services that use a 3rd-party back end, it includes available back end APIs.

Table 7-2 Supported Technologies for Services

WebCenter Portal Service Data Controls Java APIs REST APIs Back End APIs

Activity Graph

Section 46.3.1, "Using the Activity Graph Data Control"

Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal

Section 46.3.2, "Using the Activity Graph Service REST APIs"

 

Analytics

Section 47.3.1, "Using SQL Data Controls"

Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal

   

Announcements

     

Web Services with Oracle WebCenter Portal's Discussions Server (requires configuration, because WebCenter Portal is set up with custom authentication)

See the Jive Forums documentation on the Oracle Fusion Middleware documentation library (in the WebCenter Portal product area)

Comments & Likes

 

Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal

Section 42.1, "Activity Stream REST APIs"

 

Discussions

   

Section 34.3.8, "Using the Discussions Service REST APIs"

Web Services with Oracle WebCenter Portal's Discussions Server (requires configuration, because WebCenter Portal is set up with custom authentication)

See the Jive Forums documentation on the Oracle Fusion Middleware documentation library (in the WebCenter Portal product area)

Documents (with wiki and blogs)

Chapter 28, "Working with Content Data Controls"

Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal

Oracle Fusion Middleware Content Management REST Service Developer's Guide

See Oracle Fusion Middleware Remote Intradoc Client (RIDC) Java API Reference

Oracle Fusion Middleware Services Reference Guide for Oracle Universal Content Management

Events

   

Section 52.3, "Using the Events Service REST APIs"

Web Services with Microsoft Exchange

General Settings

 

Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal

   

Links

   

Section 43.3.1, "Using the Links Service REST APIs"

 

Lists

   

Section 48.4, "Using the Lists Service REST APIs"

 

Notifications

Section 49.3.2, "Using Notifications Data Controls"

Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal

   

Pagelet Producer

   

Section 63.2.2.2, "Accessing Pagelets Using REST"

 

People Connections

Section 41.1, "Using People Connections Data Controls"

Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal

Chapter 42, "People Connections Service REST APIs" (for Profile and Activity Stream)

 

Personalization

 

Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal (for developing custom Providers and Locators)

Section 67.4, "Extending Personalization"

 

Polls

Section 37.3.4, "Using the Polls Service Data Controls"

     

Resource Action Handler Framework

 

Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal

   

Search

Section 45.3.8, "Using the Search Service Data Control"

Note: Only Oracle SES search supports the search data control.

Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal

Section 45.3.7, "Using the Search Service REST APIs"

Note: Only Oracle SES search supports the search REST APIs.

Web Services and Java APIs with Oracle Secure Enterprise Search

Tags

 

Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal

Section 44.3.2, "Using the Tags Service REST APIs"

 

See Also:

Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal for more information about Expression Language APIs

7.1.3 Using WebCenter Portal Data Controls

Several services provide data controls for building a customized user interface with a Framework application or task flow. Deploying this task flow into an ADF library allows for a portable consumption of the task flow; for example, you could add it to a Spaces application Resource Catalog (Composer) to build site templates.

You do not need to integrate a service before you can use its data control to edit the user interface. An application is configured for the respective service when one of its data controls or task flows is used.

Note:

Oracle ADF architecture provides data controls for the user interface to understand the structure of your data. Metadata describes data collections, properties, methods, and types. When you drag and drop attributes, collections, and methods onto a page, JDeveloper automatically creates the bindings from the page to the associated services.

See Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework for detailed information about data controls.

To use a built-in data control:

  1. In JDeveloper, create a WebCenter Portal Framework application with any connections required for the services.

  2. In the Resource Palette, expand My Catalogs, WebCenter Portal - Services Catalog, and Data Controls.

  3. Right-click the data control and choose Add to Project.

    Figure 7-1 Data Controls in the Resource Palette

    Description of Figure 7-1 follows
    Description of "Figure 7-1 Data Controls in the Resource Palette"

  4. Drag and drop methods and properties from the data control to a ADF JSF page.

Note:

There are two other ways to add data controls to your application:

  • From the Resource Palette, choose IDE connections, and navigate to the data control. Right-click the data control, and select Add to Project.

  • From Project Properties, choose Libraries and Classpath, and click the Add Library button. With this approach, you must know the JDeveloper library that contains the data control you want.

7.2 Preparing Your Framework Application to Consume Services

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

7.2.1 How to Prepare Your Application to Consume Services

You can configure any application to include a service. When you create an application in JDeveloper, you can choose to base the application on a template. Although not a requirement, WebCenter Portal's Framework application template makes all the appropriate connection wizards and tag libraries readily visible and available in the New Gallery and Component palette. When you consume a service 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 subsections:

7.2.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 user customization and preferences.

ADF security is configured by default if you created your application using WebCenter Portal's Framework application template.

See Also:

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, or select Application - Secure - Resource Grants (Figure 7-2). The Resource Type dropdown controls the set of grants that are shown in the table. You can show only the grants for a particular permission type by selecting it from the list.

Figure 7-2 ADF Security Policies in the jazn-data.xml File

Description of Figure 7-2 follows
Description of "Figure 7-2 ADF Security Policies in the jazn-data.xml File"

7.2.1.2 Setting Up SSL-Protected Connections for Services

If you are setting up a connection in JDeveloper for a service, and the connection is being made to an SSL-protected endpoint (with a valid certificate from a trusted certificate authority) then you need prepare your environment accordingly.

Note:

This Preferences setting change is required only for connections made using Integrated WLS as the default server. If you are deploying to a Managed Server, this settings change is not required.

To set preferences for SSL-protected service connections:

  1. From the JDeveloper tool bar, select Tools > Preferences.

    The Preferences dialog displays (Figure 7-3).

    Figure 7-3 Preferences Dialog

    Description of Figure 7-3 follows
    Description of "Figure 7-3 Preferences Dialog"

  2. On the Preferences dialog, click Credentials (Figure 7-4).

    Figure 7-4 Credentials Pane

    Description of Figure 7-4 follows
    Description of "Figure 7-4 Credentials Pane"

  3. Change the value of Client Trusted Certificate Keystore to:

    <JAVA_HOME>/jre/lib/security/cacerts
    

    where <JAVA_HOME> is the location of the Java home directory.

  4. Click OK.

7.2.2 Setting Up a Database Connection

Many services require a connection to a database schema where relevant information is stored. For example, with the Links service, relationship mapping information, such as what object is linked to what other object, is stored in the database.

Table 7-3 lists the services that require a database connection.

Table 7-3 Associated Data Source

Service Data Source

Activity Graph

Activities

Activity Stream

WebCenter Portal

Analytics

Activities

Blogs

WebCenter Portal

Comments

WebCenter Portal

Documents (including wikis and blogs) that want to include Comments and Activity Stream

WebCenter Portal

Links

WebCenter Portal

Lists

WebCenter Portal

Oracle Portal Adapter

PORTAL (name of the Oracle Portal schema)

People Connections

WebCenter Portal

Polls

WebCenter Portal

Tags

WebCenter Portal


See Also:

  • Section 3.5, "Installing Database Schemas" for information about installing the schemas

  • "Deploying the Application to a WebLogic Managed Server" in Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal for data source considerations when deploying your application to a production environment

To create the database connection:

  1. In the Application Navigator, expand the Application Resources panel.

  2. Right-click Connections, then click Database.

  3. Enter the following information for your database connection:

    • Connection Name: webcenter/CustomPortal or activities/CustomPortal

      Note:

      Oracle recommends that you use these names for ease of deployment to a Framework managed server.

      • If your application contains task flows that use the WebCenter Portal schema, then name the database connection webcenter/CustomPortal.

      • If the application contains task flows that use the Activities schema, then name the database connection activities/CustomPortal.

    • Connection Type: Oracle (JDBC)

    • Username: username

    • Password: password

    • Host: host where you install the WebCenter Portal schema; for example, localhost

    • JDBC Port: port; for example, 1521

    • SID: system identifier for the database with the same JDBC; for example, ORCL

    Note:

    If the Save Password checkbox is not selected, then when deploying from JDeveloper to a managed server or the Integrated WebLogic Server, you must manually create the data source after deployment.

    For detailed information on how to create a JDBC data source for Oracle WebLogic Server, see Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

    Figure 7-5 Database Connection

    Description of Figure 7-5 follows
    Description of "Figure 7-5 Database Connection"

  4. Click OK.

  5. In the Associate to Data Source dialog, select the appropriate schema.

    • If you named the connection webcenter/CustomPortal, then select to associate this connection to the WebCenter Portal schema.

    • If you named the connection activities/CustomPortal, then select to associate this connection to the Activities schema.

    Click OK (Figure 7-6).

    Figure 7-6 Associating to Data Source from the Connection Wizard

    Description of Figure 7-6 follows
    Description of "Figure 7-6 Associating to Data Source from the Connection Wizard"

The data source association applies separately to each project in the workspace. If there is more than one WebCenter Portal project in the workspace, then the dialog displays a dropdown list allowing the user to choose which project to configure.

Note:

While you can set up the connections to back-end servers at design time in Oracle JDeveloper, you can later add, delete, or modify connections in your deployed environment using Enterprise Manager Fusion Middleware Control.

See Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal for more information.

7.2.2.1 Associating Existing Database Connections

For existing database connections, you can associate data sources by right-clicking the connection and selecting Associate to Data Source (Figure 7-7).

Figure 7-7 Associating to Data Source for Existing Connections

Description of Figure 7-7 follows
Description of "Figure 7-7 Associating to Data Source for Existing Connections"

7.2.3 Setting Up an External Application Connection

When a 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 services permit the use of an external application to connect with the service and define authentication for it:

  • Documents

  • Events

  • Instant Messaging and Presence

  • Mail

  • RSS Viewer (when using a secured RSS feed)

7.3 Extending Your Framework Application with Custom Components

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

7.3.1 Introducing the Resource Action Handling Framework

Custom components, just like out-of-the-box services, manage and own resources. As such, they must make declarations that enable their resources to be accessible to the services that invoke other services (for example, the Search, Tags, Links, and Recent Activities services). WebCenter Portal provides a Resource Action Handling framework for custom components and 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

  • Wikis and Blogs

  • 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 Portal (from, for example, mail, notifications, 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, including wikis and blogs

  • Events

  • Lists

  • Mail

  • Notes

  • Page

  • People Connections

    • Activity Stream - Main View

    • Connections

    • Feedback

    • Profile

    • Profile Gallery

    • Message Board

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

  • Tags - Tag Center

See Also:

Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal for more information on the Resource Action Handling and rewriter interfaces

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

You can declare a resource mini-view to specify a resource viewer that is used for any inline popups displayed for this service. If the mini-view is not specified, then the resource view is used for inline popups.

Note:

A sample service-definition.xml is included with Framework applications. This file enables developers to declare their resource viewers and 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 project and select New from the context menu.

  2. Under Categories, select JSF, then ADF Task Flow, and click OK.

  3. In the Create Task Flow dialog, change File Name, for example, to order-viewer.xml. The Task Flow ID should automatically update to order-viewer (Figure 7-8).

    Figure 7-8 Create Task Flow Dialog for Resource Viewer

    Description of Figure 7-8 follows
    Description of "Figure 7-8 Create Task Flow Dialog for Resource Viewer"

  4. Click OK.

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

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

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

  7. Define a JSFF file for your page fragment.

  8. Double-click the page fragment.

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

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

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

    Example 7-1 Simple Resource Viewer

    <jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
              xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
      <af:outputText value="Rendering #{pageFlowScope.resourceId}"
                     inlineStyle="font-size:5"/>
    </jsp:root>
    
  11. Add a resourceId input parameter to the task flow, and set the value to #{pageFlowScope.resourceId}.

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

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

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

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

  16. Set the taskFlowId in the <resource-view> element to /WEB-INF/order-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.

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

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

    or

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

    <resource-view urlRewriterClass="oracle.webcenter.framework.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 7-5 Specifying a URL Rewriter Class Name (3)

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

    Some services 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.resource.IdentityResourceUrlRewriter is for Search with Oracle SES. It takes the resourceId value as a URL as is.

    • oracle.webcenter.framework.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.

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

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

    <resource-view authorizerClass="some.service.id.Authorizer3"/>
    
  18. Your service should look similar to the one shown in Example 7-7.

    Example 7-7 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"/>
      <resource-type>Custom Object</resource-type>
      <object-types>
        <object-type name="customcomponent123"
                     displayName="Display Name"
                     description="Description"/>
      </object-types>
      <resource-bundle-class>mycompany.myproduct.myapp.mycomponent.resource.ComponentMessageBundle
    </resource-bundle-class>
      <name>My Custom Component</name>
      <description>My Custom Component's Description</description>
      <icon>/mycompany/myproduct/myapp/mycomponent/component.png</icon>
      </service-definition>
     ...
    </service-definitions>
    
  19. Save the service-definition.xml file.

7.3.3 Creating a Resource Authorizer Class

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 7-8).

Example 7-8 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 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 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 7-9 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,
 
   /**
    * 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 7-10 Resource URL Rewriter Method

public String rewriteUrl(String id);

7.3.4 Specifying the View Handler and Navigation Behavior

You can develop your own resource action view handler -- for example, to cause resources to display in a new tab on the current page -- and specify whether you want to use the ADF inline popup, navigate using the DefaultResourceActionHandler (which opens in the same browser window to display the resource full screen navigation) or use the PopUpResourceActionHandler (which opens a new browser popup window).

Clicking a RAH-enabled link or button in a Framework application invokes the built-in default resource action view handler. This opens the resource in a resource viewer task flow by navigating from the browser to the resource using the same browser window.

You can change this behavior in adf-config.xml by specifying either the built-in popup view handler or a custom view handler in the <resource-handler> element. Additionally, you can specify whether the default action should invoke the view handler or display as an ADF inline popup in the current window.

Example 7-11 shows the XML added to adf-config.xml to declare that MyAppResourceActionHandler should be used as the view handler and that in the first instance, the resources should be displayed using an ADF inline popup.

Example 7-11 Specifying a Custom View Handler

<wpsC:adf-service-config
xmlns="http://xmlns.oracle.com/webcenter/framework/service">
   <resource-handler
       class="com.mycompany.myapp.MyAppResourceActionHandler"
       display-as-popup="true" />
</wpsC:adf-service-config>

where the wpsC: namespace is defined as follows:

xmlns:wpsC="http://xmlns.oracle.com/webcenter/framework/service"

Along with the DefaultResourceActionHandler, the RAH framework also includes the PopUpResourceActionHandler, which invokes a new browser popup when navigating, rather than performing a full browser window navigation. This is similar to the behavior of WebCenter Portal applications in previous releases.

Example 7-12 shows how to specify the popup view handler.

Example 7-12 Specifying the PopUp View Handler

<wpsC:adf-service-config
xmlns="http://xmlns.oracle.com/webcenter/framework/service">
    <resource-handler
class="oracle.webcenter.framework.resource.view.PopUpResourceActionHandler" />
</wpsC:adf-service-config>

Applications can invoke their own resource action view handlers by creating a class implementing the ResourceActionHandler interface or by extending the AbstractResourceActionHandler base class and specifying the new view handler in the class attribute of <resource-handler> in adf-config.xml. In the following scenarios, the custom view handler class is invoked when a RAH link is clicked:

  • The ADF inline popup is not being used.

  • The Maximize button is clicked on the ADF inline popup.

See Also:

Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal for the service framework for more information about creating a custom resource action view handler; in particular, the AbstractResourceActionHandler class

In the <resource-handler> tag, the display-as-popup attribute defines the initial behavior for actioning an RAH link. This can be overridden on the RAH link itself in the resourceActionBehavior tag using the useResourcePopup attribute with the values of always, never or appDefined.

If useResourcePopup is not set, or if it is set to appDefined on the RAH link, then the display-as-popup attribute in adf-config.xml is considered. If this is set to true, then RAH invokes the ADF inline popup instead of invoking the resource action view handler. This displays a mini-resource-view of the resource in an ADF inline popup within the current page. The user can close or maximize this. If the user clicks the Maximize button, then the popup is closed and the resource action view handler is invoked.

By default, the ADF inline popup is used in Framework applications only for specific cases for some task flows where a full navigation does not make sense. For example, search results may include the resource's author. When you click this user name link, you see the popup summary profile of the author without navigating away from the search result.

These task flows have useResourcePopup set to always in their resourceActionBehavior tags. You can change this by customizing the task flow.

In deployed applications, the <resource-handler> settings in adf-config.xml can be added and updated using WLST commands. For command syntax and examples, see the sections, "setWebCenterServiceFrameworkConfig" and "getWebCenterServiceFrameworkConfig" in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

7.4 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 Portal General Settings service. This service contains values that you can access either directly from the JSF page(s) in your Framework application or indirectly through an API. The General Settings service covers the following areas:

To use the service directly from your application, use Expression Language in your JSF pages to access the generalSettings managed bean. The style is based on the java.util.Timezone, and the pattern is based on java.text.SimpleDateFormat.

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.

The General Settings service supports both pattern-based and style-based formats. If a pattern is not specified, then the style is used. By default, the patterns are not specified or null.

Figure 7-9 shows the Insert EL Expression dialog with General Settings.

Figure 7-9 Expression Builder for the generalSettings JSF Managed Bean

Description of Figure 7-9 follows
Description of "Figure 7-9 Expression Builder for the generalSettings JSF Managed Bean"

Table 7-4 describes the preference values for the General Settings service.

Table 7-4 General Settings Managed Bean Preference Values and Descriptions

General Settings Preference Value Description

formattedCurrentDate

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

formattedCurrentDateTime

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

formattedCurrentTime

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

preferredAccessibilityMode

Preferred accessibility mode (default, inaccessible, or screenReader) for use in the accessibility-mode setting in trinidad-config.xml.

preferredDateStyle

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

preferredTimeStyle

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

preferredDatePattern

Java date pattern to be used when displaying dates, and not times.The pattern must be a valid java.text.SimpleDateFormat pattern; for example: dd-MMM-yyyy. This takes precedence over preferredDateStyle.

preferredTimePattern

Java time pattern to be used when displaying times, and not dates. This takes precedence over preferredTimeStyle.

preferredDateTimePattern

Java date/time pattern to be used when displaying dates and times.

This takes precedence over preferredDateStyle and preferredTimeStyle.

userTimeZone

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

preferredSkinName

Preferred skin name to use with the skin-family setting in trinidad-config.xml.


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 7-13 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 7-14 Code for Displaying Specified Date and Time

<af:outputText value="#{row.dateTimeValue}">
    <af:convertDateTime type="both"
                        dateStyle="#{generalSettings.preferredDateStyle}"
                        timeStyle="#{generalSettings.preferredTimeStyle}"
                        timeZone="#{generalSettings.userTimeZone}"
                        locale="#{facesContext.externalContext.requestLocale}" />
                        pattern="#{generalSettings.preferredDateTimePattern}"
    </af:outputText>>

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 7-15 Setting the Accessibility Mode in trinidad-config.xml

<accessibility-mode>#{generalSettings.preferredAccessibilityMode}</accessibility-mode>

7.4.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 7-4.

Any service in WebCenter Portal 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.

7.4.2 Using General Settings to Specify the User's Locale

By default, ADF obtains the user's locale from the user's browser settings. You can change this behavior to have the user's preferred locale be set in the application using a Preferences UI.

To make the behavior change, include oracle.webcenter.generalsettings.model.filter.GeneralSettingsLocaleFilter as a servlet filter in web.xml and adfBindings. This servlet filter sets the default locale (ADF Locale) from the General Settings service Locale preference instead of from the user's browser.

Add the General Setting locale filter to web.xml with the following rules:

Define the filter. For example:

<filter>
         <description>
            WebCenter General Settings locale setting.
         </description>
         <filter-name>
            generalSettingsLocaleFilter
         </filter-name>
         <filter-class>
          
oracle.webcenter.generalsettings.model.filter.GeneralSettingsLocaleFilter
         </filter-class>
      </filter> 

Add the filter after the adfBindings filter with the same servlet-name. For example:

<filter-mapping>
         <filter-name>
            generalSettingsLocaleFilter
         </filter-name>
         <servlet-name>Faces Servlet</servlet-name>        
      </filter-mapping> 

If this filter is not set, then the locale is sourced first from the client browser locale setting, and then from the ADF locale setting.

If this filter is set, then the locale is sourced from the General Settings service. If the General Settings locale preference does not exist, then it reverts to the non-filter default behavior.