org.mmbase.module.corebuilders
Class RelDef

java.lang.Object
  extended by org.mmbase.util.functions.FunctionProvider
      extended by org.mmbase.module.core.MMTable
          extended by org.mmbase.module.core.MMObjectBuilder
              extended by 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: RelDef.java 41871 2010-04-13 10:31:27Z michiel $
Author:
Daniel Ockeloen, Pierre van Rooden
To Do:
Fix cache so it will be updated using multicast.

Field Summary
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, 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
RelDef()
          Contruct the builder
 
Method Summary
 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, 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.


MMBase 2.0-SNAPSHOT - null