org.mmbase.module.corebuilders
Class InsRel

java.lang.Object
  org.mmbase.util.functions.FunctionProvider
      org.mmbase.module.core.MMTable
          org.mmbase.module.core.MMObjectBuilder
              org.mmbase.module.corebuilders.InsRel

All Implemented Interfaces:

EventListener, NodeEventListener, RelationEventListener

Direct Known Subclasses:

AnnotRel

public class InsRel
extends MMObjectBuilder

InsRel, the main relation object, holds relations, and methods to handle them. An insrel defines a relation between two objects.

This class can be extended to create insrels that can also hold extra values and custom methods (named relations for example).

Version:

$Id: InsRel.java 45315 2011-02-18 20:23:11Z michiel $

Author:

Daniel Ockeloen, Pierre van Rooden

Field Summary

static String	FIELD_DESTINATION Name of the field containing the destination object number
static String	FIELD_DIR Name of the field containing the directionality
static String	FIELD_DIRECTIONALITY Name of the field containing the directionality
static String	FIELD_DNUMBER Name of the field containing the destination object number
static String	FIELD_RNUMBER Name of the field containing the role (reldef) object number
static String	FIELD_ROLE Name of the field containing the role (reldef) object number
static String	FIELD_SNUMBER Name of the field containing the source object number
static String	FIELD_SOURCE Name of the field containing the source object number
static String	INSREL_BUILDER Base 'insrel' builder name
int	relnumber Hold the relnumber to use when creating a node of this builder.
static boolean	usesdir Indicates whether the relations use the 'dir' field (that is, whether the field has been defined in the xml file).

Fields inherited from class org.mmbase.module.core.MMObjectBuilder

AGE_PARAMETERS, broadCastChanges, DEFAULT_ALINEA, DEFAULT_EOL, description, descriptions, EVENT_TYPE_LOCAL, EVENT_TYPE_REMOTE, FIELD_NUMBER, FIELD_OBJECT_TYPE, FIELD_OWNER, fields, genericBlobCache, getFunctionsFunction, GUI_INDICATOR, GUI_PARAMETERS, guiFunction, infoFunction, internalVersion, nodeCache, oType, pluralNames, searchAge, singularNames, SYSTEM_OWNER, TEMPNODE_DEFAULT_SIZE, TMP_FIELD_EXISTS, TMP_FIELD_NUMBER, virtual, WRAP_PARAMETERS, wrapFunction

Fields inherited from class org.mmbase.module.core.MMTable

maxNodesFromQuery, mmb, storageConnector, tableName

Fields inherited from class org.mmbase.util.functions.FunctionProvider

functions, getFunctions

Constructor Summary

InsRel()
needed for autoload

Method Summary

void	deleteRelationCache() Deletes the Relation cache.
void	deleteRelationCache(int source) Delete a specified relation from the relationCache
Vector<MMObjectNode>	getAllRelationsVector(int source) Deprecated. use getRelationNodes(int, boolean)
Vector<MMObjectNode>	getAllRelationsVector(int source, int role) Deprecated. use getRelationNodes(int, int, boolean)
int	getGuessedNumber(String name) Search the relation definition table for the identifying number of a relation, by name.
String	getGUIIndicator(MMObjectNode node) What should a GUI display for this node.
String	getGUIIndicator(String field, MMObjectNode node) Get the display string for a given field of this node.
Enumeration<MMObjectNode>	getRelated(int source, int otype) Get MMObjectNodes of a specified type related to a specified MMObjectNode
Enumeration<MMObjectNode>	getRelated(int source, int otype, int role) Get MMObjectNodes of a specified type related to a specified MMObjectNode
Enumeration<MMObjectNode>	getRelated(int source, String nodeType) get MMObjectNodes related to a specified MMObjectNode
Enumeration<MMObjectNode>	getRelated(int source, String nodeType, String roleName) get MMObjectNodes related to a specified MMObjectNode
Enumeration<MMObjectNode>	getRelated(String sourceNode, String nodeType) get MMObjectNodes related to a specified MMObjectNode
Enumeration<MMObjectNode>	getRelated(String sourceNode, String nodeType, String roleName) get MMObjectNodes related to a specified MMObjectNode
Vector<MMObjectNode>	getRelatedVector(int source, int otype) Deprecated.
Vector<MMObjectNode>	getRelatedVector(int source, int otype, int role) Deprecated.
MMObjectNode	getRelation(int source, int destination, int role) Test whether a relation exists and returns the corresponding node.
MMObjectNode	getRelationNode(int source, int destination, int role) Test whether a relation exists and returns the corresponding node.
List<MMObjectNode>	getRelationNodes(int source) Get relation(s) for an MMObjectNode, using a specified role (reldef) as a filter.
List<MMObjectNode>	getRelationNodes(int source, boolean useDirectionality) Get all relation(s) for an MMObjectNode.
List<MMObjectNode>	getRelationNodes(int source, int role) Get relation(s) for an MMObjectNode, using a specified role (reldef) as a filter.
List<MMObjectNode>	getRelationNodes(int source, int role, boolean useDirectionality) Get all relation(s) for a MMObjectNode This function returns all relations in which the node is either a source or the destination.
Enumeration<MMObjectNode>	getRelations(int source) Get relation(s) for a MMObjectNode
Enumeration<MMObjectNode>	getRelations(int source, int role) Get relation(s) for a MMObjectNode, using a specified role (reldef) as a filter
Enumeration<MMObjectNode>	getRelations(int source, int otype, int role) Get relations for a specified MMObjectNode
Enumeration<MMObjectNode>	getRelations(int source, int otype, int role, boolean usedirectionality) Gets relations for a specified MMObjectNode
Vector<MMObjectNode>	getRelationsVector(int source) Deprecated. use getRelationNodes(int)
Vector<MMObjectNode>	getRelationsVector(int source, int role) Deprecated. use getRelationNodes(int, int, boolean)
boolean	hasRelations(int source) Checks whether any relations exist for a MMObjectNode.
boolean	init() Initializes the builder.
int	insert(String owner, int source, int destination, int role) Deprecated. Use insert(String, MMObjectNode) instead.
int	insert(String owner, MMObjectNode node) Insert a new Instance Relation.
boolean	reldefCorrect(int source, int destination, int role) Deprecated. Use TypeRel.reldefCorrect(int, int, int) instead
void	removeNode(MMObjectNode node) Remove a node from the cloud.
void	setDefaults(MMObjectNode node) Set defaults for a node.
void	setTableName(String tableName) Set tablename of the builder.

Methods inherited from class org.mmbase.module.core.MMObjectBuilder

addEventListener, addField, addLocalObserver, addRemoteObserver, broadcastChanges, checkAddTmpField, clearBlobCache, commit, create, createAlias, createAlias, createIfNotExists, delete, equals, equals, executeFunction, executeFunction, fieldLocalChanged, getAncestors, getBlobCache, getClassName, getConfigFile, getConfigResource, getDataTypeCollector, getDBState, getDBType, getDefaultTeaser, getDefaultUrl, getDescendants, getDescription, getDescription, getDescriptions, getEmptyNode, getField, getFieldNames, getFields, getFields, getFunction, getFunctionParameters, getFunctions, getGUIIndicator, getHTML, getInitParameter, getInitParameters, getInitParameters, getInternalVersion, getList, getLocaleGUIIndicator, getLocaleGUIIndicator, getMachineName, getMaintainer, getNewNode, getNewTmpNode, getNextField, getNextField, getNode, getNode, getNode, getNodeFromCache, getNodeGUIIndicator, getNumber, getObjectType, getObjectValue, getParentBuilder, getPluralName, getPluralName, getPluralNames, getRelations_main, getSearchAge, getShort, getShortedByte, getShortedInputStream, getShortedText, getSingularName, getSingularName, getSingularNames, getSmartPath, getTmpNode, getURLEncode, getValue, getVersion, getWAP, getXMLPath, hasField, hashCode, hashCode, hostname_function, insert, isExtensionOf, isNodeCached, isNull, isVirtual, loadInitParameters, newFunctionInstance, nodeLocalChanged, nodeRemoteChanged, notify, notify, preCommit, process, removeEventListener, removeField, removeLocalObserver, removeRelations, removeRemoteObserver, removeSyncNodes, replace, safeCache, sendFieldChangeSignal, setDescription, setDescriptions, setFields, setInitParameter, setMaintainer, setPluralNames, setSearchAge, setSingularNames, setUniqueValue, setUniqueValue, setValue, setValue, setVersion, setXMLPath, shutdown, testValidData, toString, toString, update, updateFields, wrap

Methods inherited from class org.mmbase.module.core.MMTable

count, count, created, getFullTableName, getMMBase, getNode, getNodes, getNodes, getNodes, getNodeType, getStorageConnector, getTableName, search, searchVector, setMMBase, size

Methods inherited from class org.mmbase.util.functions.FunctionProvider

addFunction, createParameters, getFunction, getFunctions, getFunctionValue

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

INSREL_BUILDER

public static final String INSREL_BUILDER

Base 'insrel' builder name

See Also:

Constant Field Values

FIELD_SNUMBER

public static final String FIELD_SNUMBER

Name of the field containing the source object number

See Also:

Constant Field Values

FIELD_SOURCE

public static final String FIELD_SOURCE

Name of the field containing the source object number

See Also:

Constant Field Values

FIELD_DNUMBER

public static final String FIELD_DNUMBER

Name of the field containing the destination object number

See Also:

Constant Field Values

FIELD_DESTINATION

public static final String FIELD_DESTINATION

Name of the field containing the destination object number

See Also:

Constant Field Values

FIELD_RNUMBER

public static final String FIELD_RNUMBER

Name of the field containing the role (reldef) object number

See Also:

Constant Field Values

FIELD_ROLE

public static final String FIELD_ROLE

Name of the field containing the role (reldef) object number

See Also:

Constant Field Values

FIELD_DIR

public static final String FIELD_DIR

Name of the field containing the directionality

See Also:

Constant Field Values

FIELD_DIRECTIONALITY

public static final String FIELD_DIRECTIONALITY

Name of the field containing the directionality

See Also:

Constant Field Values

usesdir

public static boolean usesdir

Indicates whether the relations use the 'dir' field (that is, whether the field has been defined in the xml file). Used for backward compatibility. The default is true - the value is set to false if any of the relation builders does not contain a dir field (a warning is issued).

relnumber

public int relnumber

Hold the relnumber to use when creating a node of this builder.

Constructor Detail

InsRel

public InsRel()

needed for autoload

Method Detail

setTableName

public void setTableName(String tableName)

Description copied from class: MMTable

Set tablename of the builder. Should be used to initialize a MMTable object before calling init().

Overrides:

setTableName in class MMTable

Parameters:

tableName - the name of the table

init

public boolean init()

Initializes the builder. Determines whether the dir field is defined (and thus whether directionality is supported). If the field cannot be found, a "Warning: No dir field. Directionality support turned off." warning message is issued.

Overrides:

init in class MMObjectBuilder

Returns:

A boolean value, always success (true), as any exceptions are caught and logged.

See Also:

usesdir

insert

public int insert(String owner,
                  int source,
                  int destination,
                  int role)

Deprecated. Use insert(String, MMObjectNode) instead.

Insert a new Instance Relation.

Parameters:

owner - Administrator

source - Identifying number of the source object

destination - Identifying number of the destination object

role - Identifying number of the relation defintition

Returns:

A integer value identifying the newly inserted relation

insert

public int insert(String owner,
                  MMObjectNode node)

Insert a new Instance Relation.

Overrides:

insert in class MMObjectBuilder

Parameters:

owner - Administrator

node - Relation node to add

Returns:

A integer value identifying the newly inserted relation

removeNode

public void removeNode(MMObjectNode node)

Remove a node from the cloud.

Overrides:

removeNode in class MMObjectBuilder

Parameters:

node - The node to remove.

getRelations

public Enumeration<MMObjectNode> getRelations(int source)

Get relation(s) for a MMObjectNode

Parameters:

source - Identifying number of the object to find the relations of.

Returns:

If succesful, an Enumeration listing the relations. If no relations exist, the method returns null.

See Also:

getRelationsVector(int)

getRelations

public Enumeration<MMObjectNode> getRelations(int source,
                                              int role)

Get relation(s) for a MMObjectNode, using a specified role (reldef) as a filter

Parameters:

source - Identifying number of the object to find the relations of.

role - The number of the relation definition (role) to filter on

Returns:

an Enumeration listing the relations.

See Also:

getRelationsVector(int, int)

getRelations

public Enumeration<MMObjectNode> getRelations(int source,
                                              int otype,
                                              int role)

Get relations for a specified MMObjectNode

Parameters:

source - this is the number of the MMObjectNode requesting the relations

otype - the object type of the nodes you want to have. -1 means any node.

role - Identifying number of the role (reldef)

Returns:

An Enumeration whose enumeration consists of MMObjectNode object related to the source according to the specified filter(s).

getRelations

public Enumeration<MMObjectNode> getRelations(int source,
                                              int otype,
                                              int role,
                                              boolean usedirectionality)

Gets relations for a specified MMObjectNode

Parameters:

source - this is the number of the MMObjectNode requesting the relations

otype - the object type of the nodes you want to have. -1 means any node.

role - Identifying number of the role (reldef)

usedirectionality - if true teh result si filtered on unidirectional relations. specify false if you want to show unidoerctional relations from destination to source.

Returns:

An Enumeration whose enumeration consists of MMObjectNode object related to the source according to the specified filter(s).

hasRelations

public boolean hasRelations(int source)

Checks whether any relations exist for a MMObjectNode. This includes unidirection relations which would otherwise not be counted. If the query fails to execute, the system will assume that relations exists.

Parameters:

source - Identifying number of the object to find the relations of.

Returns:

true if any relations exist, false otherwise.

getRelationNodes

public List<MMObjectNode> getRelationNodes(int source)
                                    throws SearchQueryException

Get relation(s) for an MMObjectNode, using a specified role (reldef) as a filter. This function returns all relations based on this role in which the node is either a source, or where the node is the destination, but the direction is bidirectional.

Parameters:

source - Identifying number of the object to find the relations of.

Returns:

A List containing the relation nodes.

Throws:

SearchQueryException - if a storage error occurs

getRelationsVector

public Vector<MMObjectNode> getRelationsVector(int source)

Deprecated. use getRelationNodes(int)

Get relation(s) for a MMObjectNode.

getRelationNodes

public List<MMObjectNode> getRelationNodes(int source,
                                           int role)
                                    throws SearchQueryException

Get relation(s) for an MMObjectNode, using a specified role (reldef) as a filter. This function returns all relations based on this role in which the node is either a source, or where the node is the destination, but the direction is bidirectional.

Parameters:

source - Identifying number of the object to find the relations of.

role - The number of the relation definition (role) to filter on, -1 means any role

Returns:

A List containing the relation nodes.

Throws:

SearchQueryException - if a storage error occurs

getRelationsVector

public Vector<MMObjectNode> getRelationsVector(int source,
                                               int role)

Deprecated. use getRelationNodes(int, int, boolean)

Get relation(s) for a MMObjectNode, using a specified role.

getRelationNodes

public List<MMObjectNode> getRelationNodes(int source,
                                           boolean useDirectionality)
                                    throws SearchQueryException

Get all relation(s) for an MMObjectNode. This function returns all relations in which the node is either a source or the destination.

Parameters:

source - Identifying number of the object to find the relations of.

useDirectionality - if truie, take directionality into account. If false, returns all relations, even if the direction is unidirectional.

Returns:

A List containing the relation nodes.

Throws:

SearchQueryException - if a storage error occurs

getAllRelationsVector

public Vector<MMObjectNode> getAllRelationsVector(int source)

Deprecated. use getRelationNodes(int, boolean)

Get all relation(s) for a MMObjectNode.

getRelationNodes

public List<MMObjectNode> getRelationNodes(int source,
                                           int role,
                                           boolean useDirectionality)
                                    throws SearchQueryException

Get all relation(s) for a MMObjectNode This function returns all relations in which the node is either a source or the destination.

Parameters:

source - Identifying number of the object to find the relations of.

role - The number of the relation definition (role) to filter on, -1 means any role

useDirectionality - if truie, take directionality into account. If false, returns all relations, even if the direction is unidirectional.

Returns:

A List containing the relation nodes.

Throws:

SearchQueryException - if a storage error occurs

getAllRelationsVector

public Vector<MMObjectNode> getAllRelationsVector(int source,
                                                  int role)

Deprecated. use getRelationNodes(int, int, boolean)

Get all relation(s) for a MMObjectNode.

getRelationNode

public MMObjectNode getRelationNode(int source,
                                    int destination,
                                    int role)
                             throws SearchQueryException

Test whether a relation exists and returns the corresponding node. Note that this test is strict: it determines whether a relation exists from a source to a destination with a specific role. If only a role-relation exists where source and destination are reversed, this method assumed that this is a different relation type, and it returns null.

Parameters:

source - Identifying number of the source object

destination - Identifying number of the destination object

role - Identifying number of the role (reldef)

Returns:

The corresponding MMObjectNode if the exact relation exists,null otherwise

Throws:

SearchQueryException - if a storage error occurs

getRelation

public MMObjectNode getRelation(int source,
                                int destination,
                                int role)

Test whether a relation exists and returns the corresponding node. Note that this test is strict: it determines whether a relation exists from a source to a destination with a specific role. If only a role-relation exists where source and destination are reversed, this method assumed that this is a different relation type, and it returns null.

Parameters:

source - Identifying number of the source object

destination - Identifying number of the destination object

role - Identifying number of the role (reldef)

Returns:

The corresponding MMObjectNode if the exact relation exists,null otherwise

getRelated

public Enumeration<MMObjectNode> getRelated(String sourceNode,
                                            String nodeType)

get MMObjectNodes related to a specified MMObjectNode

Parameters:

sourceNode - this is the source MMObjectNode

nodeType - Specifies the type of the nodes you want to have e.g. "pools"

getRelated

public Enumeration<MMObjectNode> getRelated(int source,
                                            String nodeType)

get MMObjectNodes related to a specified MMObjectNode

Parameters:

source - this is the number of the source MMObjectNode

nodeType - Specifies the type of the nodes you want to have e.g. "pools"

getRelated

public Enumeration<MMObjectNode> getRelated(int source,
                                            int otype)

Get MMObjectNodes of a specified type related to a specified MMObjectNode

Parameters:

source - this is the number of the source MMObjectNode

otype - the object type of the nodes you want to have

Returns:

An Enumeration of MMObjectNode object related to the source

getRelated

public Enumeration<MMObjectNode> getRelated(String sourceNode,
                                            String nodeType,
                                            String roleName)

get MMObjectNodes related to a specified MMObjectNode

Parameters:

sourceNode - this is the number of the source MMObjectNode (in string format)

nodeType - Specifies the type of the nodes you want to have e.g. "pools"

roleName - the role of teh relation (name in reldef)

getRelated

public Enumeration<MMObjectNode> getRelated(int source,
                                            String nodeType,
                                            String roleName)

get MMObjectNodes related to a specified MMObjectNode

Parameters:

source - this is the number of the source MMObjectNode

nodeType - Specifies the type of the nodes you want to have e.g. "pools"

roleName - the name of the role of the relation (name in reldef)

getRelated

public Enumeration<MMObjectNode> getRelated(int source,
                                            int otype,
                                            int role)

Get MMObjectNodes of a specified type related to a specified MMObjectNode

Parameters:

source - this is the number of the source MMObjectNode

otype - the object type of the nodes you want to have

role - Identifying number of the role (reldef)

Returns:

An Enumeration of MMObjectNode object related to the source

getRelatedVector

public Vector<MMObjectNode> getRelatedVector(int source,
                                             int otype)

Deprecated.

Get MMObjectNodes related to a specified MMObjectNode

Parameters:

source - this is the number of the MMObjectNode requesting the relations

otype - the object type of the nodes you want to have. -1 means any node.

Returns:

A Vector whose enumeration consists of MMObjectNode object related to the source according to the specified filter(s).

getRelatedVector

public Vector<MMObjectNode> getRelatedVector(int source,
                                             int otype,
                                             int role)

Deprecated.

Get MMObjectNodes related to a specified MMObjectNode

Parameters:

source - this is the number of the MMObjectNode requesting the relations

otype - the object type of the nodes you want to have. -1 means any node.

role - Identifying number of the role (reldef)

Returns:

A Vector whose enumeration consists of MMObjectNode object related to the source according to the specified filter(s).

getGUIIndicator

public String getGUIIndicator(MMObjectNode node)

Description copied from class: MMObjectBuilder

What should a GUI display for this node. Default the value returned is GUI_INDICATOR ('no info'). Override this to display your own choice (see Images.java). You may want to override MMObjectBuilder.getNodeGUIIndicator(MMObjectNode, org.mmbase.util.functions.Parameters) for more flexibility.

Overrides:

getGUIIndicator in class MMObjectBuilder

Parameters:

node - The node to display

Returns:

the display of the node as a String

getGUIIndicator

public String getGUIIndicator(String field,
                              MMObjectNode node)

Get the display string for a given field of this node. Returns for 'snumber' the name of the source object, for 'dnumber' the name of the destination object, and for 'rnumber' the name of the relation definition.

Overrides:

getGUIIndicator in class MMObjectBuilder

Parameters:

field - name of the field to describe.

node - Node containing the field data.

Returns:

A String describing the requested field's content

reldefCorrect

public boolean reldefCorrect(int source,
                             int destination,
                             int role)

Deprecated. Use TypeRel.reldefCorrect(int, int, int) instead

Checks whether a specific relation exists. Maintains a cache containing the last checked relations Note that this routine returns false both when a source/destination are swapped, and when a typecombo does not exist - it is not possible to derive whether one or the other has occurred.

Parameters:

source - Number of the source node

destination - Number of the destination node

role - Number of the relation definition

Returns:

A boolean indicating success when the relation exists, failure if it does not.

deleteRelationCache

public void deleteRelationCache()

Deletes the Relation cache. This is to be called if caching gives problems. Make sure that you can't use the deleteRelationCache(int source) instead.

deleteRelationCache

public void deleteRelationCache(int source)

Delete a specified relation from the relationCache

Parameters:

source - the number of the relation to remove from the cache

getGuessedNumber

public int getGuessedNumber(String name)

Search the relation definition table for the identifying number of a relation, by name. Success is dependent on the uniqueness of the relation's name (not enforced, so unpredictable).

Parameters:

name - The name on which to search for the relation

Returns:

A int value indicating the relation's object number, or -1 if not found.

setDefaults

public void setDefaults(MMObjectNode node)

Set defaults for a node. Tries to determine a default for 'relnumber' by searching the RelDef table for an occurrence of the node's builder. Uses the table-mapping system, and should be replaced.

Overrides:

setDefaults in class MMObjectBuilder

Parameters:

node - The node whose defaults to set.