org.mmbase.module.corebuilders

Class RelDef

java.lang.Object

org.mmbase.util.functions.FunctionProvider

org.mmbase.module.core.MMTable

org.mmbase.module.core.MMObjectBuilder

org.mmbase.module.corebuilders.RelDef

All Implemented Interfaces:

EventListener, NodeEventListener, RelationEventListener

public class RelDef
extends MMObjectBuilder

RelDef, one of the meta stucture nodes, is used to define the possible relation types.

A Relation Definition consists of a source and destination, and a descriptor (direction) for it's use (unidirectional or bidirectional).

Relations are mapped to a builder.
This is so that additional functionality can be added by means of a builder (i.e. AuthRel).
The old system mapped the relations to a builder by name. Unfortunately, this means that some care need be taken when naming relations, as unintentionally naming a relation to a builder can give bad (if not disastrous) results.
Relations that are not directly mapped to a builder are mapped (internally) to the InsRel builder instead.

The new system uses an additional field to map to a builder. This 'builder' field contains a reference (otype) to the builder to be used. If null or 0, the builder is assumed to refer to the InsRel builder. sname is now the name of the relation and serves no function.

This patched version of RelDef can make use of either direct builder references (through the builder field), or the old system of using names. The system used is determined by examining whether the builder field has been defined in the builder's configuration (xml) file. See the documentation of the relations project at http://www.mmbase.org for more info.

Version:

$Id$

Author:

Daniel Ockeloen, Pierre van Rooden

To Do:

Fix cache so it will be updated using multicast.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DIR_BIDIRECTIONAL Value of "dir" field indicating bidirectional relatios.
static int	DIR_UNIDIRECTIONAL Value of "dir" field indicating unidirectional relations.
static boolean	usesbuilder Indicates whether the relationdefinitions use the 'builder' 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, getFunctions, GUI_INDICATOR, GUI_PARAMETERS, guiFunction, infoFunction, internalVersion, nodeCache, oType, pluralNames, searchAge, singularNames, SYSTEM_OWNER, TEMPNODE_DEFAULT_SIZE, temporaryNodes, 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

Constructor Summary

Constructors

Constructor and Description
RelDef() Contruct the builder

Method Summary

Modifier and Type	Method and Description
boolean	commit(MMObjectNode node) Commit changes to this node and updated the cache.
protected String	findBuilderName(MMObjectNode node)
InsRel	getBuilder(int rnumber) Returns the builder of a relation definition.
InsRel	getBuilder(MMObjectNode node) Returns the builder of a relation definition.
String	getBuilderName(Integer reldefNodeNumber)
String	getBuilderName(MMObjectNode node) Returns the builder name of a relation definition.
MMObjectNode	getDefaultForBuilder(InsRel relBuilder) Returns the first occurrence of a reldef node of a relation definition.
int	getGuessedByName(String role) Deprecated. use getNumberByName(java.lang.String) instead
int	getGuessedNumber(String role) Deprecated. renamed to getNumberByName(java.lang.String) which better explains its use
String	getGUIIndicator(MMObjectNode node) Returns a GUI description of a relation definition.
String	getGUIIndicator(String field, MMObjectNode node) Retrieve descriptors for a relation definition's fields, specifically a descriptive text for the relation's direction (dir)
int	getNumberByName(String role) Search the relation definition table for the identifying number of a relationdefinition, by name of the role to use.
int	getNumberByName(String role, boolean searchBidirectional) Search the relation definition table for the identifying number of a relationdefinition, by name of the role to use.
Enumeration<MMObjectBuilder>	getRelationBuilders() Returns a list of builders currently implementing a relation node.
int	getRelsNrByName(String sname, String dname) Deprecated. use getNumberByName(java.lang.String) instead
Set<Integer>	getRoles() Returns all possible rnumbers ('roles').
boolean	init() Initializes the builder by reading the cache.
int	insert(String owner, MMObjectNode node) Insert a new object, and updated the cache after an insert.
boolean	isRelationBuilder(int number) Checks to see if a given builder (otype) is known to be a relation builder.
boolean	isRelationTable(String name) Checks to see if a given relation definition is stored in the cache.
boolean	nodeRemoteChanged(String machine, String number, String builder, String ctype) Called when a remote node is changed.
void	removeNode(MMObjectNode node) Remove a node from the cloud.
void	setDefaults(MMObjectNode node) Sets defaults for a new relation definition.
void	testValidData(MMObjectNode node) Tests whether the data in a node is valid (throws an exception if this is not the case).

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

addEventListener, addField, addLocalObserver, addRemoteObserver, broadcastChanges, checkAddTmpField, clearBlobCache, 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, 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, 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, setTableName, 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

DIR_UNIDIRECTIONAL

public static final int DIR_UNIDIRECTIONAL

Value of "dir" field indicating unidirectional relations.

See Also:

Constant Field Values

DIR_BIDIRECTIONAL

public static final int DIR_BIDIRECTIONAL

Value of "dir" field indicating bidirectional relatios.

See Also:

Constant Field Values

usesbuilder

public static boolean usesbuilder

Indicates whether the relationdefinitions use the 'builder' field (that is, whether the field has been defined in the xml file). Used for backward compatibility.

Constructor Detail

RelDef

public RelDef()

Contruct the builder

Method Detail

init

public boolean init()

Initializes the builder by reading the cache. Also determines whether the 'builder' field is used.

Overrides:

init in class MMObjectBuilder

Returns:

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

See Also:

MMObjectBuilder.create()

getGUIIndicator

public String getGUIIndicator(MMObjectNode node)

Returns a GUI description of a relation definition. The description is dependent on the direction (uni/bi) of the relation

Overrides:

getGUIIndicator in class MMObjectBuilder

Parameters:

node - Relation definition to describe

Returns:

A String of descriptive text

getBuilderName

public String getBuilderName(Integer reldefNodeNumber)

Parameters:

reldefNodeNumber - rnumber

Since:

MMBase-1.7

findBuilderName

protected String findBuilderName(MMObjectNode node)

Since:

MMBase-1.7

getBuilderName

public String getBuilderName(MMObjectNode node)

Returns the builder name of a relation definition. If the buildername cannot be accurately determined, the sname field will be returned instead.

Parameters:

node - The reldef Node

Returns:

the builder name

getBuilder

public InsRel getBuilder(int rnumber)

Returns the builder of a relation definition.

Returns:

the builder

getBuilder

public InsRel getBuilder(MMObjectNode node)

Returns the builder of a relation definition.

Returns:

the builder

getDefaultForBuilder

public MMObjectNode getDefaultForBuilder(InsRel relBuilder)

Returns the first occurrence of a reldef node of a relation definition. used to set the default reldef for a specific builder.

Returns:

the default reldef node, or null if not found.

testValidData

public void testValidData(MMObjectNode node)
                   throws InvalidDataException

Tests whether the data in a node is valid (throws an exception if this is not the case).

Overrides:

testValidData in class MMObjectBuilder

Parameters:

node - The node whose data to check

Throws:

InvalidDataException - If the data was unrecoverably invalid (the references did not point to existing objects)

insert

public int insert(String owner,
                  MMObjectNode node)

Insert a new object, and updated the cache after an insert. This method indirectly calls MMObjectBuilder.preCommit(org.mmbase.module.core.MMObjectNode).

Overrides:

insert in class MMObjectBuilder

Parameters:

owner - The administrator creating the node

node - The object to insert. The object need be of the same type as the current builder.

Returns:

An int value which is the new object's unique number, -1 if the insert failed.

commit

public boolean commit(MMObjectNode node)

Commit changes to this node and updated the cache. This method indirectly calls MMObjectBuilder.preCommit(org.mmbase.module.core.MMObjectNode). This method does not remove names from the cache, as currently, unique names are not enforced.

Overrides:

commit in class MMObjectBuilder

Parameters:

node - The node to be committed

Returns:

a boolean indicating success

removeNode

public void removeNode(MMObjectNode node)

Remove a node from the cloud.

Overrides:

removeNode in class MMObjectBuilder

Parameters:

node - The node to remove.

setDefaults

public void setDefaults(MMObjectNode node)

Sets defaults for a new relation definition. Initializes a relation to be bidirectional, and, if applicable, to use the 'insrel' builder.

Overrides:

setDefaults in class MMObjectBuilder

Parameters:

node - Node to be initialized

getRoles

public Set<Integer> getRoles()

Returns all possible rnumbers ('roles').

Since:

MMBase-1.9

getGUIIndicator

public String getGUIIndicator(String field,
                              MMObjectNode node)

Retrieve descriptors for a relation definition's fields, specifically a descriptive text for the relation's direction (dir)

Overrides:

getGUIIndicator in class MMObjectBuilder

Parameters:

field - Name of the field whose description should be returned. valid values : 'dir'

node - Relation definition containing the field's information

Returns:

A descriptive text for the field's contents, or null if no description could be generated

isRelationTable

public boolean isRelationTable(String name)

Checks to see if a given relation definition is stored in the cache.

Parameters:

name - A String of the relation definitions' name

Returns:

a boolean indicating success if the relationname exists

isRelationBuilder

public boolean isRelationBuilder(int number)

Checks to see if a given builder (otype) is known to be a relation builder.

Parameters:

number - The otype of the builder

Returns:

a boolean indicating success if the builder exists in the cache

getRelationBuilders

public Enumeration<MMObjectBuilder> getRelationBuilders()

Returns a list of builders currently implementing a relation node.

Returns:

an Enumeration containing the builders (as otype)

getGuessedNumber

public int getGuessedNumber(String role)

Deprecated. renamed to getNumberByName(java.lang.String) which better explains its use

Search the relation definition table for the identifying number of a relation, by name of the relation to use Similar to getGuessedByName(java.lang.String) (but does not make use of dname) Not very suitable to use, as success is dependent on the uniqueness of the builder in the table (not enforced, so unpredictable).

Parameters:

role - The builder name on which to search for the relation

Returns:

A int value indicating the relation's object number, or -1 if not found. If multiple relations use the indicated buildername, the first one found is returned.

getNumberByName

public int getNumberByName(String role)

Search the relation definition table for the identifying number of a relationdefinition, by name of the role to use. The name should be either the primary identifying role name (sname), or a combination of sname and dname separated by a slash ("/").

Parameters:

role - The role name on which to search

Returns:

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

To Do:

support for searching on dname

getNumberByName

public int getNumberByName(String role,
                           boolean searchBidirectional)

Search the relation definition table for the identifying number of a relationdefinition, by name of the role to use. Initially, this method seraches on either the primary identifying role name (sname), or a combination of sname and dname separated by a slash ("/"). If this yields no result, and searchBidirectional is true, the method then searches on the secondary identifying role name. The latter is not cached (to avoid conflict and is thus slower).

Parameters:

role - The role name on which to search

searchBidirectional - determines whether to also search in sname

Returns:

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

To Do:

support for searching on dname

getGuessedByName

public int getGuessedByName(String role)

Deprecated. use getNumberByName(java.lang.String) instead

Search the relation definition table for the identifying number of a relation, by name of the relation to use. This function is used by descendants of Insrel to determine a default reference to a 'relation definition' (reldef entry). The 'default' is the relation with the same name as the builder. If no such relation exists, there is no default.

Parameters:

role - The role name on which to search for the relation

Returns:

A int value indicating the relation's object number, or -1 if not found. If multiple relations use the indicated buildername, the first one found is returned.

getRelsNrByName

public int getRelsNrByName(String sname,
                           String dname)

Deprecated. use getNumberByName(java.lang.String) instead

Searches for the relation number on the combination of sname and dname. When there's no match found in this order a search with a swapped sname and dname will be done. Note that there is no real assurance that an sname/dname combination must be unique.

Parameters:

sname - The first name on which to search for the relation (preferred as the source)

dname - The second name on which to search for the relation (preferred as the destination)

Returns:

A int value indicating the relation's object number, or -1 if not found. If multiple relations use the indicated names, the first one found is returned.

nodeRemoteChanged

public boolean nodeRemoteChanged(String machine,
                                 String number,
                                 String builder,
                                 String ctype)

Called when a remote node is changed. Should be called by subclasses if they override it. Called when a remote node is changed. If a node is changed or newly created, this adds the new or updated role (sname and dname) to the cache.

Overrides:

nodeRemoteChanged in class MMObjectBuilder

Parameters:

machine - Name of the machine that changed the node.

number - Number of the changed node as a String

builder - type of the changed node

ctype - command type, 'c'=changed, 'd'=deleted', 'r'=relations changed, 'n'=new

Returns:

always true

Since:

MMBase-1.7.1

To Do:

Old roles are cuerrently not cleared or removed - which means that they may remain useable for some time after the actual role is deleted or renamed., Use 1.8 event mechanism in stead. This because old role information is no longer available when this call is made.