org.mmbase.bridge
Interface Node

All Known Subinterfaces:

NodeManager, Relation, RelationManager

All Known Implementing Classes:

BasicNode, BasicNodeManager, BasicRelation, BasicRelationManager

public interface Node

Describes an object in the cloud.

Version:

$Id: Node.java,v 1.46 2003/12/23 20:00:31 michiel Exp $

Author:

Rob Vermeulen, Pierre van Rooden

Method Summary

void	cancel() Cancel changes to a node This fails if the current node is not in edit mode.
void	commit() Commit the node to the database.
int	countRelatedNodes(NodeManager otherNodeManager, java.lang.String role, java.lang.String searchDir)
int	countRelatedNodes(java.lang.String type) Returns the number of related nodes that have a specific node manager.
int	countRelations() Returns the number of relations this node has with other nodes.
int	countRelations(java.lang.String relationManager) Returns the number of relation nodes attached to this node that have a specific relation manager.
void	createAlias(java.lang.String alias) Create an alias for this node.
Relation	createRelation(Node destinationNode, RelationManager relationManager) Adds a relation between this node and a specified node to the cloud.
void	delete() Removes the Node.
void	delete(boolean deleteRelations) Removes the Node.
void	deleteAlias(java.lang.String alias) Delete an alias for this node.
void	deleteRelations() Removes all relation nodes attached to this node.
void	deleteRelations(java.lang.String relationManager) Removes all relation nodes with a certain relation manager that are attached to this node.
StringList	getAliases() Returns all aliases for this node.
boolean	getBooleanValue(java.lang.String fieldName) Returns the value of the specified field as a boolean.
byte[]	getByteValue(java.lang.String fieldName) Returns the value of the specified field as a byte array.
Cloud	getCloud() Returns the cloud this node belongs to.
java.lang.String	getContext() Get the security context of the current Node
double	getDoubleValue(java.lang.String fieldName) Returns the value of the specified field as a double.
FieldValue	getFieldValue(Field field) Returns the value of the specified field as a FieldValue object.
FieldValue	getFieldValue(java.lang.String fieldName) Returns the value of the specified field as a FieldValue object.
float	getFloatValue(java.lang.String fieldName) Returns the value of the specified field as a float.
FieldValue	getFunctionValue(java.lang.String functionName, java.util.List arguments) Returns the value of the specified function on the node.
int	getIntValue(java.lang.String fieldName) Returns the value of the specified field as an int.
long	getLongValue(java.lang.String fieldName) Returns the value of the specified field as a long.
NodeManager	getNodeManager() Returns the node manager for this node.
Node	getNodeValue(java.lang.String fieldName) Returns the value of the specified field as a Node.
int	getNumber() Returns the unique number for this node.
java.lang.Object	getObjectValue(java.lang.String fieldName) Returns the field's value as an object.
StringList	getPossibleContexts() Contacts the security implementation to find out to which other possible contextes the context of this node may be set.
NodeList	getRelatedNodes() Returns all related nodes.
NodeList	getRelatedNodes(NodeManager nodeManager) Returns all related nodes that have a specific node manager.
NodeList	getRelatedNodes(NodeManager nodeManager, java.lang.String role, java.lang.String searchDir) Returns all related nodes that have a specific node manager and role.
NodeList	getRelatedNodes(java.lang.String nodeManager) Returns all related nodes that have a specific node manager.
NodeList	getRelatedNodes(java.lang.String nodeManager, java.lang.String role, java.lang.String searchDir) Returns all related nodes that have a specific node manager and role.
RelationList	getRelations() Returns all relation nodes attached to this node.
RelationList	getRelations(java.lang.String role) Returns all relation nodes attached to this node that have a specific role
RelationList	getRelations(java.lang.String role, NodeManager nodeManager) Returns all relation nodes attached to this node that have a specific role, or refer a node from a specific nodemanager
RelationList	getRelations(java.lang.String role, NodeManager nodeManager, java.lang.String searchDir)
RelationList	getRelations(java.lang.String role, java.lang.String nodeManager) Returns all relation nodes attached to this node that have a specific role, or refer a node from a specific nodemanager
java.lang.String	getStringValue(java.lang.String fieldName) Returns the value of the specified field as a String.
java.lang.Object	getValue(java.lang.String fieldName) Returns the value of the specified field as an object.
org.w3c.dom.Document	getXMLValue(java.lang.String fieldName) Returns the value of the specified field as a dom.Document If the node value is not itself a Document, the method attempts to attempts to convert the String value into an XML.
org.w3c.dom.Element	getXMLValue(java.lang.String fieldName, org.w3c.dom.Document tree) Returns the value of the specified field as a dom.Element If the node value is not itself a Document, the method attempts to attempts to convert the String value into an XML.
boolean	hasRelations() Checks whether this node has any relations.
boolean	isNodeManager() Determine whether this Node is a NodeManager.
boolean	isRelation() Determine whether this Node is a Relation.
boolean	isRelationManager() Determine whether this Node is a RelationManager.
boolean	mayChangeContext() Check context-change rights on this node.
boolean	mayDelete() Check delete rights on this node.
boolean	mayWrite() Check write rights on this node.
void	setBooleanValue(java.lang.String fieldName, boolean value) Sets the value of the specified field using an boolean.
void	setByteValue(java.lang.String fieldName, byte[] value) Sets the value of the specified field using a byte array.
void	setContext(java.lang.String context) Sets the security context of this Node (AKA the 'owner' field)
void	setDoubleValue(java.lang.String fieldName, double value) Sets the value of the specified field using a double.
void	setFloatValue(java.lang.String fieldName, float value) Sets the value of the specified field using a float.
void	setIntValue(java.lang.String fieldName, int value) Sets the value of the specified field using an int.
void	setLongValue(java.lang.String fieldName, long value) Sets the value of the specified field using a long.
void	setNodeValue(java.lang.String fieldName, Node value) Sets the value of the specified field using an Node.
void	setObjectValue(java.lang.String fieldName, java.lang.Object value) Sets the value of the specified field using an object.
void	setStringValue(java.lang.String fieldName, java.lang.String value) Sets the value of the specified field using a String.
void	setValue(java.lang.String fieldName, java.lang.Object value) Sets the value of the specified field using an object, but delegated to the right set--Value depending on the type of the field.
void	setXMLValue(java.lang.String fieldName, org.w3c.dom.Document value) Set's the value of the specified field as a dom.Element
NodeManager	toNodeManager() Returns this as a NodeManager.
Relation	toRelation() Returns this as a Relation.
RelationManager	toRelationManager() Returns this as a RelationManager.
java.lang.String	toString() Converts the node to a string

Method Detail

getCloud

public Cloud getCloud()

Returns the cloud this node belongs to.

getNodeManager

public NodeManager getNodeManager()

Returns the node manager for this node.

getNumber

public int getNumber()

Returns the unique number for this node. Every node has a unique number which can be used to refer to it. In addition to this number a node can have one or more aliases. A value of -1 indicates an invalid number. Other negative values may be used for temporary ids (but not true node numbers). This may differ by implementation.

Returns:

the unique number for this node

See Also:

createAlias(String alias)

isRelation

public boolean isRelation()

Determine whether this Node is a Relation.

Returns:

true if this Node is a Relation.

Since:

MMBase-1.6

toRelation

public Relation toRelation()

Returns this as a Relation.

Returns:

a Relation object

Throws:

ClasscastException - if the Node is not a Relation

Since:

MMBase-1.6

isNodeManager

public boolean isNodeManager()

Determine whether this Node is a NodeManager.

Returns:

true if this Node is a NodeManager.

Since:

MMBase-1.6

toNodeManager

public NodeManager toNodeManager()

Returns this as a NodeManager.

Returns:

a NodeManager object

Throws:

ClasscastException - if the Node is not a NodeManager

Since:

MMBase-1.6

isRelationManager

public boolean isRelationManager()

Determine whether this Node is a RelationManager.

Returns:

true if this Node is a RelationManager.

Since:

MMBase-1.6

toRelationManager

public RelationManager toRelationManager()

Returns this as a RelationManager.

Returns:

a NodeManager object

Throws:

ClasscastException - if the Node is not a RelationManager

Since:

MMBase-1.6

setValue

public void setValue(java.lang.String fieldName,
                     java.lang.Object value)

Sets the value of the specified field using an object, but delegated to the right set--Value depending on the type of the field. For example a field of type int can be set using an Integer. This change will not be visible to the cloud until the commit method is called.

Parameters:

fieldName - the name of the field to be updated

value - the new value for the given field

setObjectValue

public void setObjectValue(java.lang.String fieldName,
                           java.lang.Object value)

Sets the value of the specified field using an object.

Parameters:

fieldName - the name of the field to be updated

value - the new value for the given field

Since:

MMBase-1.7

setBooleanValue

public void setBooleanValue(java.lang.String fieldName,
                            boolean value)

Sets the value of the specified field using an boolean. This change will not be visible to the cloud until the commit method is called.

Parameters:

fieldName - the name of the field to be updated

value - the new value for the given field

Since:

MMBase-1.6

setNodeValue

public void setNodeValue(java.lang.String fieldName,
                         Node value)

Sets the value of the specified field using an Node. This change will not be visible to the cloud until the commit method is called.

Parameters:

fieldName - the name of the field to be updated

value - the new value for the given field

Since:

MMBase-1.6

setIntValue

public void setIntValue(java.lang.String fieldName,
                        int value)

Sets the value of the specified field using an int. This change will not be visible to the cloud until the commit method is called.

Parameters:

fieldName - the name of the field to be updated

value - the new value for the given field

setFloatValue

public void setFloatValue(java.lang.String fieldName,
                          float value)

Sets the value of the specified field using a float. This change will not be visible to the cloud until the commit method is called.

Parameters:

fieldName - the name of the field to be updated

value - the new value for the given field

setDoubleValue

public void setDoubleValue(java.lang.String fieldName,
                           double value)

Sets the value of the specified field using a double. This change will not be visible to the cloud until the commit method is called.

Parameters:

fieldName - the name of the field to be updated

value - the new value for the given field

setByteValue

public void setByteValue(java.lang.String fieldName,
                         byte[] value)

Sets the value of the specified field using a byte array. This change will not be visible to the cloud until the commit method is called.

Parameters:

fieldName - the name of the field to be updated

value - the new value for the given field

setLongValue

public void setLongValue(java.lang.String fieldName,
                         long value)

Sets the value of the specified field using a long. This change will not be visible to the cloud until the commit method is called.

Parameters:

fieldName - the name of the field to be updated

value - the new value for the given field

setStringValue

public void setStringValue(java.lang.String fieldName,
                           java.lang.String value)

Sets the value of the specified field using a String. This change will not be visible to the cloud until the commit method is called.

Parameters:

fieldName - the name of the field to be updated

value - the new value for the given field

getValue

public java.lang.Object getValue(java.lang.String fieldName)

Returns the value of the specified field as an object. For example a field of type int is returned as an Integer. The object type may vary and is dependent on how data was stored in a field. I.e. It may be possible for an Integer field to return it's value as a String if it was stored that way in the first place.

Parameters:

fieldName - the name of the field to be returned

Returns:

the value of the specified field

getObjectValue

public java.lang.Object getObjectValue(java.lang.String fieldName)

Returns the field's value as an object. It is not delegated to the right get--Value.

Since:

MMBase-1.7

getBooleanValue

public boolean getBooleanValue(java.lang.String fieldName)

Returns the value of the specified field as a boolean. If the actual value is numeric, this call returns true if the value is a positive, non-zero, value. In other words, values '0' and '-1' are concidered false. If the value is a string, this call returns true if the value is "true" or "yes" (case-insensitive). In all other cases (including calling byte fields), false is returned.

Parameters:

fieldName - the name of the field to be returned

Returns:

the value of the specified field

getNodeValue

public Node getNodeValue(java.lang.String fieldName)

Returns the value of the specified field as a Node. If the value is not itself a Node, this call attempts to convert the original field value to a Node, by trying to retrieve a Node using the field value as a Node number or alias.
For instance, getNodeValue("destination"), when run on a OAlias object, returns the referenced destination node (instead of teh number, which is what it normally holds).
Mosty, this call is used in cluster nodes (nodes retrived by using the Cloud.getList method. A cluster node returns one of its compound nodes when an appropriate nodemanager name (name from the nodepath) is specified. I.e. getNodeValue("people") will return the people-node in the cluster. If this fails, the method returns null.
Notes: the behavior of getNodeValue when called on a field that is not intended to be a node reference is currently undefined and is not encouraged.
Calling this method with field "number" or null lets the Node return a reference to itself, regardless of the actual value of the number field or status of the Node.

Parameters:

fieldName - the name of the field to be returned

Returns:

the value of the specified field

See Also:

Cloud.getList(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, boolean)

getIntValue

public int getIntValue(java.lang.String fieldName)

Returns the value of the specified field as an int. Numeric fields are simply converted. Double and float values may be truncated. For Node values, the numeric key is returned. Long values return -1 of the value is too large. Boolean fields return 0 if false, and 1 if true. String fields are parsed. If a parsed string contains an error, ot the field value is not of a type that can be converted (i.e. a byte array), this function returns -1

Parameters:

fieldName - the name of the field to be returned

Returns:

the value of the specified field

getFloatValue

public float getFloatValue(java.lang.String fieldName)

Returns the value of the specified field as a float. This function attempts to convert the value to a float. Numeric fields are simply converted. Boolean fields return 0.0 if false, and 1.0 if true. String fields are parsed. If a parsed string contains an error, ot the field value is not of a type that can be converted (i.e. a byte array), this function returns -1.0.

Parameters:

fieldName - the name of the field to be returned

Returns:

the value of the specified field

getLongValue

public long getLongValue(java.lang.String fieldName)

Returns the value of the specified field as a long. This function attempts to convert the value to a long. Numeric fields are simply converted. Double and float values may be truncated. Boolean fields return 0 if false, and 1 if true. String fields are parsed. If a parsed string contains an error, ot the field value is not of a type that can be converted (i.e. a byte array), this function returns -1

Parameters:

fieldName - the name of the field to be returned

Returns:

the value of the specified field

getDoubleValue

public double getDoubleValue(java.lang.String fieldName)

Returns the value of the specified field as a double. This function attempts to convert the value to a double. Numeric fields are simply converted. Double may be truncated. Boolean fields return 0.0 if false, and 1.0 if true. String fields are parsed. If a parsed string contains an error, ot the field value is not of a type that can be converted (i.e. a byte array), this function returns -1.0.

Parameters:

fieldName - the name of the field to be returned

Returns:

the value of the specified field

getByteValue

public byte[] getByteValue(java.lang.String fieldName)

Returns the value of the specified field as a byte array. This function returns either the value of a byte field, or the byte value of a string (converted using the default encoding, i.e. UTF8) Other types of values return an empty byte-array.

Parameters:

fieldName - the name of the field to be returned

Returns:

the value of the specified field

getStringValue

public java.lang.String getStringValue(java.lang.String fieldName)

Returns the value of the specified field as a String. Byte arrays are converted to string using the default encoding (UTF8). Node values return a string representation of their numeric key. For other values the result is calling the toString() method on the actual object.

Parameters:

fieldName - the name of the field to be returned

Returns:

the value of the specified field

getFieldValue

public FieldValue getFieldValue(java.lang.String fieldName)
                         throws NotFoundException

Returns the value of the specified field as a FieldValue object.

Parameters:

fieldName - the name of the field whose value to return

Returns:

the value of the specified field

Throws:

NotFoundException - is the field does not exist

Since:

MMBase-1.6

getFieldValue

public FieldValue getFieldValue(Field field)

Returns the value of the specified field as a FieldValue object.

Parameters:

field - the Field object whose value to return

Returns:

the value of the specified field

Since:

MMBase-1.6

getFunctionValue

public FieldValue getFunctionValue(java.lang.String functionName,
                                   java.util.List arguments)

Returns the value of the specified function on the node. A function normally has arguments, which can be supplied with a List.

Parameters:

functionName - the name of the function to be executed

arguments - parameters to the function

Returns:

the function value of the specified function

Since:

MMBase-1.6

commit

public void commit()

Commit the node to the database. Makes this node and/or the changes made to this node visible to the cloud. If this method is called for the first time on this node it will make this node visible to the cloud, otherwise the modifications made to this node using the set methods will be made visible to the cloud. This action fails if the current node is not in edit mode. If the node is in a transaction, nothing happens - actual committing occurs through the transaction.

cancel

public void cancel()

Cancel changes to a node This fails if the current node is not in edit mode. If the node is in a transaction, nothing happens - actual committing occurs through the transaction.

delete

public void delete()

Removes the Node. Throws an exception if still has relations. Like delete(false).

delete

public void delete(boolean deleteRelations)

Removes the Node.

Parameters:

deleteRelations - a boolean. If true, then first all existing relations with this node will be removed.

toString

public java.lang.String toString()

Converts the node to a string

getXMLValue

public org.w3c.dom.Document getXMLValue(java.lang.String fieldName)
                                 throws java.lang.IllegalArgumentException

Returns the value of the specified field as a dom.Document If the node value is not itself a Document, the method attempts to attempts to convert the String value into an XML. If the value cannot be converted, this method returns null

Parameters:

fieldName - the name of the field to be returned

Returns:

the value of the specified field as a DOM Element or null

Throws:

java.lang.IllegalArgumentException - if the Field is not of type TYPE_XML.

Since:

MMBase-1.6

getXMLValue

public org.w3c.dom.Element getXMLValue(java.lang.String fieldName,
                                       org.w3c.dom.Document tree)
                                throws java.lang.IllegalArgumentException

Returns the value of the specified field as a dom.Element If the node value is not itself a Document, the method attempts to attempts to convert the String value into an XML. This method fails (throws a IllegalArgumentException) if the Field is not of type TYPE_XML. If the value cannot be converted, this method returns null

Parameters:

fieldName - the name of the field to be returned

tree - the DOM Document to which the Element is added (as the document root element)

Returns:

the value of the specified field as a DOM Element or null

Throws:

java.lang.IllegalArgumentException - if the Field is not of type TYPE_XML.

Since:

MMBase-1.6

setXMLValue

public void setXMLValue(java.lang.String fieldName,
                        org.w3c.dom.Document value)

Set's the value of the specified field as a dom.Element

Parameters:

fieldName - the name of the field to be returned

value - the DOM Document to has to be set, if not correct doc-type, system will try to convert it to the wanted type.

Since:

MMBase-1.6

hasRelations

public boolean hasRelations()

Checks whether this node has any relations.

Returns:

true if the node has relations

deleteRelations

public void deleteRelations()

Removes all relation nodes attached to this node.

deleteRelations

public void deleteRelations(java.lang.String relationManager)

Removes all relation nodes with a certain relation manager that are attached to this node.

Parameters:

relationManager - the name of the relation manager the removed relation nodes should have

getRelations

public RelationList getRelations()

Returns all relation nodes attached to this node.

Returns:

a list of relation nodes

getRelations

public RelationList getRelations(java.lang.String role)

Returns all relation nodes attached to this node that have a specific role

Parameters:

role - the name of the role the returned relation nodes should have

Returns:

a list of relation nodes

getRelations

public RelationList getRelations(java.lang.String role,
                                 java.lang.String nodeManager)

Returns all relation nodes attached to this node that have a specific role, or refer a node from a specific nodemanager

Parameters:

role - the name of the role the returned relation nodes should have

nodeManager - the name of the nodemanager for the nodes the returned relation nodes should have a relation to

Returns:

a list of relation nodes

getRelations

public RelationList getRelations(java.lang.String role,
                                 NodeManager nodeManager)

Returns all relation nodes attached to this node that have a specific role, or refer a node from a specific nodemanager

Parameters:

role - the name of the role the returned relation nodes should have

nodeManager - the nodemanager for the nodes the returned relation nodes should have a relation to (can be null)

Returns:

a list of relation nodes

getRelations

public RelationList getRelations(java.lang.String role,
                                 NodeManager nodeManager,
                                 java.lang.String searchDir)

Since:

MMBase-1.7

countRelations

public int countRelations()

Returns the number of relations this node has with other nodes.

Returns:

the number of relations this node has with other nodes

countRelations

public int countRelations(java.lang.String relationManager)

Returns the number of relation nodes attached to this node that have a specific relation manager.

Returns:

the number of relation nodes attached to this node that have a specific relation manager

getRelatedNodes

public NodeList getRelatedNodes()

Returns all related nodes. The returned nodes are not the nodes directly attached to this node (the relation nodes) but the nodes attached to the relation nodes of this node.

Returns:

a list of all related nodes

getRelatedNodes

public NodeList getRelatedNodes(java.lang.String nodeManager)

Returns all related nodes that have a specific node manager. The returned nodes are not the nodes directly attached to this node (the relation nodes) but the nodes attached to the relation nodes of this node.

Parameters:

nodeManager - the name of the node manager the returned nodes should have

Returns:

a list of related nodes

getRelatedNodes

public NodeList getRelatedNodes(NodeManager nodeManager)

Returns all related nodes that have a specific node manager. The returned nodes are not the nodes directly attached to this node (the relation nodes) but the nodes attached to the relation nodes of this node.

Parameters:

nodeManager - the node manager the returned nodes should have, can be null

Returns:

a list of related nodes

getRelatedNodes

public NodeList getRelatedNodes(java.lang.String nodeManager,
                                java.lang.String role,
                                java.lang.String searchDir)

Returns all related nodes that have a specific node manager and role. The returned nodes are not the nodes directly attached to this node (the relation nodes) but the nodes attached to the relation nodes of this node.

Parameters:

nodeManager - the name of the node manager the returned nodes should have

role - the role of the relation

searchDir - the direction of the relation

Returns:

a list of related nodes

Since:

MMBase-1.6

getRelatedNodes

public NodeList getRelatedNodes(NodeManager nodeManager,
                                java.lang.String role,
                                java.lang.String searchDir)

Returns all related nodes that have a specific node manager and role. The returned nodes are not the nodes directly attached to this node (the relation nodes) but the nodes attached to the relation nodes of this node.

Parameters:

nodeManager - the node manager the returned nodes should have

role - the role of the relation

searchDir - the direction of the relation

Returns:

a list of related nodes

Since:

MMBase-1.6

countRelatedNodes

public int countRelatedNodes(java.lang.String type)

Returns the number of related nodes that have a specific node manager. The counted nodes are not the nodes directly attached to this node (the relation nodes) but the nodes attached to the relation nodes of this node.

Returns:

the number of related nodes that have a specific node manager

countRelatedNodes

public int countRelatedNodes(NodeManager otherNodeManager,
                             java.lang.String role,
                             java.lang.String searchDir)

Since:

MMBase-1.7

getAliases

public StringList getAliases()

Returns all aliases for this node.

Returns:

a list of alias names for this node

createAlias

public void createAlias(java.lang.String alias)

Create an alias for this node. An alias can be used to refer to a node in addition to his number.

Parameters:

alias - the alias to be created for this node

Throws:

BridgeException - if the alias allready exists

deleteAlias

public void deleteAlias(java.lang.String alias)

Delete an alias for this node.

Parameters:

alias - the alias to be removed for this node

createRelation

public Relation createRelation(Node destinationNode,
                               RelationManager relationManager)

Adds a relation between this node and a specified node to the cloud.

Parameters:

destinationNode - the node to which you want to relate this node

relationManager - the relation manager you want to use

Returns:

the added relation

Throws:

BridgeException - if the relation manager is not the right one for this type of relation

setContext

public void setContext(java.lang.String context)

Sets the security context of this Node (AKA the 'owner' field)

Parameters:

context - The security context to which this node should belong,

Throws:

java.lang.SecurityException - When appropriate rights to perform this are lacking (write / change context rights)

getContext

public java.lang.String getContext()

Get the security context of the current Node

Returns:

the current context of the node (as a String)

Throws:

java.lang.SecurityException - When appropriate rights to perform this are lacking (read rights)

getPossibleContexts

public StringList getPossibleContexts()

Contacts the security implementation to find out to which other possible contextes the context of this node may be set.

Returns:

A StringList containing the contextes which can be used in setContext on this node.

Throws:

java.lang.SecurityException - When appropriate rights to perform this are lacking (read rights)

mayWrite

public boolean mayWrite()

Check write rights on this node.

Returns:

Whether the node may be changed by the current user

mayDelete

public boolean mayDelete()

Check delete rights on this node.

Returns:

Whether the node may be deleted by the current user

mayChangeContext

public boolean mayChangeContext()

Check context-change rights on this node.

Returns:

Whether the current user may change the context of this node