com.objy.db.app
Interface ClusterStrategy

All Known Implementing Classes:

DefaultClusterStrategy

public interface ClusterStrategy

Defines behavior shared by all clustering strategies.

A clustering strategy is an object that selects the storage location for an object that is clustered implicitly. An object is clustered implicitly by Objectivity for Java or explicitly by a direct call to the session's requestCluster method when it is made persistent for any of the following reasons:

• The object is made a named root.
• The object is given a scope name.
• A relationship is formed from an already persistent object to the object.
• The object is added to a persistent collection.
• The object is referenced from a persistent field of a persistent object that is being written to the database.
• An application makes a direct call to the session's requestCluster method.

Every session has an associated clustering strategy. When an object is clustered implicitly, the session's clustering strategy assigns it a storage location. If the object being clustered is a basic object, the clustering strategy assigns it a location in a particular container. If the object being clustered is a container, the clustering strategy assigns it a location in a particular database.

Explicit clustering bypasses the session's clustering strategy. A basic object or container can be clustered explicitly with a direct call to the cluster method of a database, a persistent container, or a persistent basic object. In addition, a container can be clustered explicitly with a call to the addContainer method of a database.

The class DefaultClusterStrategy implements a clustering strategy that all sessions use by default.

Defining a Clustering Strategy

To create a customized clustering strategy for your application, define your own class that implements this interface. Your implementation of the requestCluster method should use the information passed in its parameters to select a clustering object. The clustering object can be any one of the following:

• A persistent basic object with which to cluster the object.
• A persistent container with which to cluster the object.
• A database in which to cluster the object.

Your method should then call the clustering object's cluster method, passing as a parameter the object to be clustered.

Working With Clustering Strategies

You can get the clustering strategy associated with a session by calling the session's getClusterStrategy method.

You can replace the current clustering strategy of a session with an instance of your own class by calling the session's setClusterStrategy method.

You can call the requestCluster method of a clustering strategy to make an object persistent, assigning it to the location selected by that clustering strategy.

If your application makes direct calls to the requestCluster method of a clustering strategy or a session, you should define at least one class that implements the ClusterReason interface. You need to pass an instance of such a class as a parameter to requestCluster.

Method Summary

void	requestCluster(Object requestObject, ClusterReason reason, Object object) Makes the specified object persistent and assigns it to the container or database selected by this clustering strategy.

Method Detail

requestCluster

public void requestCluster(Object requestObject,
                           ClusterReason reason,
                           Object object)

Makes the specified object persistent and assigns it to the container or database selected by this clustering strategy.

If object is a basic object, this method assigns it to a container; if object is a container, this method assigns it to a database.

Parameters:

requestObject - The object requesting that object be made persistent. (See Implicit Clustering.)

reason - The reason for making object persistent.

object - The object being made persistent.

Throws:

ObjyRuntimeException - If the object is already persistent.