5 Interface Topics

This chapter provides useful information for writing an SPI implementation. It contains the following sections:

• Section 5.1, "NodeOpsV1 SPI Interface Topics"

• Section 5.2, "ObjectClassOpsV1 SPI Interface Topics"

• Section 5.3, "SearchOpsV1 SPI Interface Topics"

• Section 5.4, "Indexing Content"

• Section 5.5, "SPI Testing Topics"

5.1 NodeOpsV1 SPI Interface Topics

The following FAQs provides useful information when implementing the NodeOpsV1 interface. It contains the following questions, answers, and examples:

• Section 5.1.1, "What Types of Operations are Supported by the NodeOpsV1 SPI Interface?"

• Section 5.1.2, "What Type of Hierarchical Paths are Passed To and From the SPI layer?"

• Section 5.1.3, "How Should the SPI Implementation Create Node Data Objects to be Returned?"

• Section 5.1.4, "How Should the SPI Implementation Create Property Data Objects to be Returned"

• Section 5.1.5, "What Should the SPI Implementation Do when Node Metadata is not Available?"

• Section 5.1.6, "How are the Node ID and Property ID related?"

• Section 5.1.7, "What Node Names are Valid?"

• Section 5.1.8, "Example – Creating a Node with no ObjectClass"

• Section 5.1.9, "Example – Creating a Node with an ObjectClass and Property Values"

5.1.1 What Types of Operations are Supported by the NodeOpsV1 SPI Interface?

The NodeOpsV1 interface supports all the operations on nodes, properties, and values:

• Creating nodes.

• Retrieving nodes by ID or Path.

• Reading groups of nodes by hierarchy positions and by link property location.

• Updating nodes.

• Deleting nodes.

• Copying nodes.

• Moving nodes.

• Retrieving node properties.

• Retrieving node binary values.

5.1.2 What Type of Hierarchical Paths are Passed To and From the SPI layer?

The paths used in the SPI layer must start with a path delimiter (/) and extend based on the repository path. For example, /foo/bar/bas. The repository name is not part of the path unlike a VCR federated path. For example, /MyRepository/foo/bar/bas is not a valid SPI path, but it is a valid VCR path.

5.1.3 How Should the SPI Implementation Create Node Data Objects to be Returned?

The SPI implementation can directly instantiate the Node via a constructor such as:

new Node( Calendar createdDate, String createdBy, boolean hasChildren, ID id, String modifiedBy, Calendar modifiedDate, ObjectClass objectClass, ID parentId, String path, Property[] properties )

The Node ID needs a non-null UUID set; however, the Node ID does not need the repositoryName set, as the VCR takes care of this function.

Previous versions of WebLogic Portal had a concept of "node type." Starting with WebLogic Portal 10.2, SPI implementations should use the node type of Node.CONTENT when a node type is necessary.

If the node has an ObjectClass, you can create a Property on the Node for any PropertyDefinition in the ObjectClass.

To optimize performance, the SPI implementation can optionally pass null for the Property[] properties. This allows the properties to be lazy-loaded by the VCR when needed. Additionally, the SPI implementation can optionally use a null ObjectClass and call setObjectClassId() to set the ObjectClass identifier. This allows the objectClass to be lazy-loaded by the VCR when needed.

You can use these approaches on a per-method basis. In general, use these approaches for methods that may return a large collection of nodes. For methods returning a single node, it is generally not advisable to lazy-load the properties.

5.1.4 How Should the SPI Implementation Create Property Data Objects to be Returned

The SPI implementation can directly instantiate each Property via a constructor such as:

new Property( ID id, String name, int type, Value[] values )

The Property ID needs a non-null UUID set; it does not need the repositoryName set, as the VCR takes care of the repository name.

5.1.5 What Should the SPI Implementation Do when Node Metadata is not Available?

The SPI implementation requirements, when metadata (created by, modified date, and so on) is not available, depends on what data the VCR clients use. For maximum flexibility with clients, it is best for the SPI implementation to return constant values rather than null. For example, the SPI could return system as the "created by" or "modified by" String, or return a constant Date as the created date or modified date.

5.1.6 How are the Node ID and Property ID related?

The Property ID is a finer granularity than the Node ID; it represents data within a node. The exact relationship depends on the back-end system and how it represents and can access node and property data.

The Node UUID must uniquely identify the node within an implicit repository. You use the Node UUID retrieve all the properties (and values) for a given node.

The Property UUID must uniquely identify a single property on a single node within an implicit repository. You use the Property UUID to retrieve a single property on a node.

The Node UUID is not always supplied when the properties are retrieved. For example, with NodeOpsV1.getPropertyBytes( ID propertyId ) the Property UUID needs to be able to "stand alone" and work on its own. One option for linking the IDs together is to have the Property ID contain the Node ID. For example, if the Node UUID is "41431", the Property UUID could be "41431/stringProperty".

5.1.7 What Node Names are Valid?

In general, the node name must be a non-empty string, must not contain forward or backslashes, and the last token in a node's hierarchical path must be the node name. For detailed information, see the Oracle Fusion Middleware Java API Reference for Oracle WebLogic Portal.

5.1.8 Example – Creating a Node with no ObjectClass

Example 5-1 shows an example of how to create a node without an ObjectClass.

Example 5-1 Creating a Node with no ObjectClass

ID id = new ID(uid);
ID parentId = new ID(parentUid);
Node node =  new Node(createDate, createdBy, false, id, createdBy,
   createDate, null /* no ObjectClass */, parentId, path, null);

5.1.9 Example – Creating a Node with an ObjectClass and Property Values

Example 5-2 shows an example of how to create a node with an ObjectClass and property values.

Example 5-2 Creating a Node with an ObjectClass and Property Values

ID id = new ID(uid);
ID parentId = new ID(parentUid);
Property [] props = getPropertiesToUse();
Node node =  new Node(createDate, createdBy, false, id, createdBy, createDate, null /* lazy-load ObjectClass */, parentId, path, props);
ID ocId = new ID(objectClassUid);
node.setObjectClassId(ocId);   //lazy-load ObjectClass

5.2 ObjectClassOpsV1 SPI Interface Topics

This section contains information about implementing ObjectClassOpsV1. It contains the following sections:

• Section 5.2.1, "What are the Supported Operation Types?"

• Section 5.2.2, "How Should the SPI Implementation Create ObjectClass Objects?"

5.2.1 What are the Supported Operation Types?

The ObjectClassOpsV1 interface supports all the operations on ObjectClasses, PropertyDefinitions, and PropertyChoices, which are:

• Creating objectClasses and propertyDefinitions.

• Retrieving an objectCass by ID or name.

• Retrieving a propertyDefinition by ID.

• Retrieving all propertyDefinitions by objectClass ID.

• Updating an objectClass or property definition.

• Deleting objectClasses and propertyDefinitions.

• Renaming an objectClass.

• Retrieving some or all objectClasses.

• Retrieving property choice binary values.

To support type inheritance, objectClasses support a hierarchical structure. ObjectClasses have a Name and an ID that are used for identification. They also have a path. When type inheritance is used, the ObjectClass path indicates its relationship to other ObjectClasses.

5.2.2 How Should the SPI Implementation Create ObjectClass Objects?

The SPI implementation can directly instantiate each ObjectClass using a constructor such as:

new ObjectClass( ID id, String name, PropertyDefinition
   primaryPropertyDefinition, PropertyDefinition[] propertyDefinitions,
   boolean hasPropertyDefinitions );

The hasPropertyDefinitions flag indicates whether PropertyDefinitions exist for this type in the external system and supports lazy-loading of propertyDefinitions. For example, propertyDefinitions may exist in the external system, but not be returned in the ObjectClass.

To enhance performance, the SPI implementation can optionally pass null for the PropertyDefinition[] propertyDefinitions. This allows the propertyDefinitions to be lazy-loaded by the VCR when needed.

5.3 SearchOpsV1 SPI Interface Topics

The SearchOpsV1 interface supports node search and indexing operations. The following operations are supported:

• Searching for nodes matching criteria, either metadata search or full-text search.

• Manually indexing or re-indexing a node tree by path.

• Manually indexing or re-indexing all nodes with a specified ObjectClass.

The SearchOpsV1 interface supports the following search criteria:

• System metadata – The JavaBean properties on the Node, such as name, ObjectClass name, created by, and so on.

• User metadata – The ObjectClass properties.

5.4 Indexing Content

Content indexing allows for fast lookups, especially for full-text searches. For example, when nodes are created, data can be indexed into a full-text search engine for fast retrieval.

This section contains the following topics:

• Section 5.4.1, "How Is Content Indexed?"

• Section 5.4.2, "How Can an Event Listener Perform Content Indexing?"

5.4.1 How Is Content Indexed?

You can index content in two ways:

• Synchronously, during node creation. To do this, use the SPI implementation of NodeOpsV1.create methods or use a synchronous event listener that is registered to listen to node create events.

• Asynchronously, after node creation. To do this, use an asynchronous event listener that is registered to listen to node create events controlled via an external timer or mechanism.

  Use the index_cm_data script to re-index by path or content type.

The synchronous approach makes node creation slower, but supports immediate searches for the data. The asynchronous approaches make node creation faster, but the data is not available immediately.

Note:

If you use event listeners, you can temporarily disable content indexing, then create a group of nodes, re-enable content indexing, and then manually re-index the relevant data tree with the index_cm_data script.

5.4.2 How Can an Event Listener Perform Content Indexing?

The event listener must implement the interface com.bea.p13n.events.EventListener. You can register the event listener via a META-INF/p13n-config.xml file with an entry such as:

<?xml version="1.0" encoding="UTF-8"?>
<p13n-config xmlns="http://www.bea.com/ns/p13n/90/p13n-config">
   <event-service>
      <listener>com.xxx.ContentExporterListener</listener>
   </event-service>
</p13n-config>

The event listener should listen for the event type ContentEventHelper.CONTENT_EVENT_BATCH_TYPE. The event listener's handleEvent( Event) method is called as content items are created, updated, or deleted. This method receives events of type ContentEventBatch, which contains a group of events that have fired.

5.5 SPI Testing Topics

This section contains informations to aid in testing an SPI implementation. It contains the following topics:

• Section 5.5.1, "How to Configure a Repository for SPI Parameter and Response Data Checking"

• Section 5.5.2, "How to Monitor Repository and Ticket Method Invocations and Performance"

• Section 5.5.3, "How to Monitor SPI Operation Interface Method Invocations and Performance"

5.5.1 How to Configure a Repository for SPI Parameter and Response Data Checking

During testing, you can configure a repository to perform SPI parameter and response data checking. The vcrValidation and repositoryValidation repository configuration settings enable additional runtime checks on the data passed to and from the SPI. These settings catch some of the common errors. By default, both settings are false (disabled) to maximize performance.

To enable VCR validation, add these settings to your repository configuration:

Property name: 'vcrValidation'
Property value: 'true' (default is false)
Property name: 'repositoryValidation'
Property value: 'true' (default is false)

Alternatively, you can place this code snippet in your MTA-INF/content-config.xml file in the appropriate section for your repository configuration:

<repository-property>
   <name>vcrValidation</name>
   <value>true</value>
</repository-property>
<repository-property>
   <name>repositoryValidation</name>
   <value>true</value>
</repository-property>

5.5.2 How to Monitor Repository and Ticket Method Invocations and Performance

To debug repository and ticket operations, add debug lines to your debug.properties file:

spi.com.bea.content.manager.internal.RepositoryHelper: ON
spi.com.bea.content.manager.internal.RepositoryManagerImpl: ON
To collect timing information, add:
timing.com.bea.content.manager.internal.RepositoryHelper: ON
timing.com.bea.content.manager.internal.RepositoryManagerImpl: ON

5.5.3 How to Monitor SPI Operation Interface Method Invocations and Performance

To enable SPI invocation, add a debug line to your debug.properties file:

spi.com.bea.content.manager.internal.delegate: ON

To enable SPI method timing, add a debug line to your debug.properties file:

timing.com.bea.content.manager.internal.delegate: ON