1 Introduction to Content Management SPI

This chapter introduces the Oracle WebLogic Portal Content Management (CM) Service Provider Interface (SPI) by way of an FAQ. It contains the following sections:

Section 1.1, "Content Management SPI FAQ"
Section 1.2, "Architecture Overview of an SPI Implementation"

1.1 Content Management SPI FAQ

The following questions and answers provide an overview of the Content Management SPI.

1.1.1 What is the CM SPI?

SPI is an open extension point in the WebLogic Portal Content Management Virtual Content Repository (VCR). It supports integrating data from an external system into the WebLogic Portal VCR.

SPI implementations can be "plugged into" the VCR to enable data access and modification in external stores of given type. This gives you the ability to use WebLogic Portal Interaction Management, display templates, CM APIs, content search, WebLogic Portal Administration Tools, and other WebLogic Portal VCR features with the external data. For example, you could create SPI implementations for accessing SharePoint, file system, RSS, or database data.

The SPI is a group of CM interfaces supplied with WebLogic Portal. For example, there is a Repository interface, a Ticket interface, and various optional operations interfaces, such as NodeOps, ObjectClassOps, and SearchOps. Some of these interfaces are required, others are optional.

An SPI implementation is a group of classes that implements the SPI to support persisting and/or storing data externally. The SPI is not tied to any particular architecture, protocol, or data source. This means that it is applicable to a wide range of implementations, including database-centric, file-system based, and network protocol-based systems. Some SPI implementations may delegate to a remote server, while other implementations run in same JVM as WebLogic Server.

For example, you could create an SPI to access external syndicated feeds (RSS) and present the feed data as VCR nodes and properties. The CM tags and display template features of WebLogic Portal could be used to access and present the data.

The SPI is designed to support incremental SPI implementations. For example, you could start with a simple read-only SPI implementation, and then later add search and read-write capabilities.

1.1.2 Why Write an SPI?

The main reason to write an SPI is to expose data via the VCR.

Creating an SPI implementation enables the WebLogic Portal features built on the CM VCR to be used with external system data. For example, content selectors, placeholders, WebDAV, display templates, CM tags, syndicated feeds, and the WebLogic Portal Administration tools may all run against external system data exposed by an SPI implementation. The exact capabilities available from the VCR depend on which features the SPI implements.

The optional interface, optional method approach allows an SPI Implementation to be quickly created and gracefully upgraded over time to support additional capabilities.

1.1.3 What are the Structures and Data Types that can be Exposed?

The CM SPI supports exposing hierarchical data via a structured (typed) mechanism. If data can be represented in a folder structure (including just a single folder level), it can be exposed via the CM SPI.

Each node in the hierarchy has an implicit name (the name of the hierarchy position) and unique ID. A node without a type has only a name and an ID. You can refer to a node either by its unique hierarchical path from the repository root, such as /foo/bar/bas, or by direct access with its unique (opaque) ID.

If the node has an associated type (ObjectClass), the node can have additional metadata. The allowable metadata depends on the type (ObjectClass) definition. For example, suppose there is an ObjectClass named City, with a numerical property "population" and a binary property "image". A node "Denver" of type City can then have a "population" value as well as an "image" value, in addition to its name and ID.

1.1.4 What is the Difference Between an SPI Implementation and a Repository?

An SPI implementation is a way to interact with an external system of a given type. For example, you could create one SPI implementation to access Documentum data, another SPI to access file system data, and a third to access data stored in a database.

The VCR may have multiple named instances (repositories) of the same SPI implementation running against different external data sources. For example, one "FileSystem" Repository may represent data rooted in one directory tree and another "FileSystem" Repository may represent data rooted in another directory tree, but both may use the file system SPI implementation classes, and be deployed in the same enterprise application.

A repository has an associated RepositoryConfig object that contains a name, an SPI implementation class name, and associated property configuration data.

1.1.5 Who Uses the SPI?

The CM VCR uses an SPI implementation on behalf of clients, such as WebLogic Portal Administration tools.

Client code does not directly use the SPI implementation; all access occurs indirectly via the VCR. WebLogic Portal administrators register SPI implementations with the VCR by creating or updating a repository configuration, which lets the VCR know about an SPI implementation and its associated configuration. In order to service VCR clients, the VCR uses the repository configuration information to connect to the SPI implementation, which then connects to the external system for accessing and modifying data.

1.1.6 How is an SPI Implementation Packaged and Made Available to the VCR?

The SPI implementation classes are placed in one or more JARs. You can then place the JARs in the system or application class path. A WebLogic Portal administrator creates a repository configuration to register and configure a Repository instance of a particular SPI implementation using (for example) the WebLogic Portal Administration tools. The administrator specifies various configuration settings, including the repository name, the SPI Repository implementation class, a user name and password (optional), and other properties.

1.1.7 Where Does the SPI Implementation Run?

The SPI implementation classes are loaded into the WebLogic Server's enterprise application classloader and run inside the WebLogic Portal server. The same SPI implementation may be loaded multiple times into different applications in the same server.

The same SPI implementation may be loaded multiple times, into the same application with different repository names and configurations.

Note:

Because they are loaded into the WebLogic Server, they can also be clustered.

1.2 Architecture Overview of an SPI Implementation

Figure 1-1 shows an architectural diagram of Content Management VCR-SPI implementation.

Figure 1-1 Content Management VCR-SPI Architecture

Description of "Figure 1-1 Content Management VCR-SPI Architecture"

1.2.1 What components are involved in the SPI?

Several interfaces in the com.bea.content.spi.flexpi package must be implemented by the SPI, such as Repository and Ticket. These interfaces must have implementations for the SPI to be loaded and provide a means for calling the SPI and for authenticating a user.

Additionally, some optional interfaces can be fully or partially implemented to support various types of functionality. For example, to support Node operations, you can implement the com.bea.content.spi.flexspi.ticket.NodeOpsV1 interface. Within this interface, you could implement all the methods except those related to link properties.

Other components involved in SPI include SPI data, such as Id, Node, ObjectClass, PropertyDefinition, QueryCriteria, and QueryResult, that are passed through the SPI interfaces. They are located in either in com.bea.content or com.bea.content.spi.flexspi.common.

1.2.2 What is the Relationship of the VCR Repository Construct and the WebLogic Portal Application?

The VCR Repository construct is enterprise-application scoped. When a repository is registered in an enterprise application with a name, an SPI Implementation class, and a set of configuration properties, it is available (via the repository name) to all users in the same enterprise application. In other words, all users in the enterprise application can access the same set of configured repositories. The particular capabilities each WebLogic Portal user can have for a given repository in the current enterprise application depend on the user's entitlements. User capability may range from none to full.

It is possible for multiple enterprise applications to duplicate a repository configuration, using the same repository name and other configuration settings, to refer to the same external system data.

1.2.3 What Authentication Models are Available?

The SPI offers several options for configuring security. You can configure the way both authorization (access to resources) and user identity are managed. For more information, see Section 4.7, "Configuring Security."

1.2.4 How Does the VCR Interact With the SPI Implementation?

After you complete configuration, the VCR needs to connect to the SPI implementation before any SPI implementation methods can be invoked.

The first time the VCR contacts the SPI implementation, the VCR usually:

Loads and instantiates the SPI class, which implements the Repository interface via Class.forName() and Class.newInstance().
Queries the Repository object for its capabilities. For more information, see Chapter 3, "SPI Capabilities and Versions."
Calls Repository.connect(…) to authenticate credentials to a repository and receive a Ticket object.
Queries the Ticket object for its capabilities.

After the initial setup is complete, future VCR access directly invokes the SPI methods.

For example, if the (optional) operation interface is supported and the capabilities also indicate the method is supported, the VCR invokes the appropriate SPI operation method. To illustrate, if the client calls INodeManger.getNodes( ContentContext, ID ), the VCR may try to call the SPI method NodeOpsV1.getNodeChildrenWithQueryCriteria( ID, int, QueryCriteria), (if the SPI implements this method).

Note:

The VCR may cache data returned by the SPI or the SPI may use its own caches.