org.mmbase.bridge

Interface Cloud

All Known Subinterfaces:

Transaction

All Known Implementing Classes:

AbstractCloud, BasicCloud, BasicTransaction, MockCloud, MockTransaction, RemoteCloud_Proxy, RemoteTransaction_Proxy, UriRemoteCloud_Proxy

public interface Cloud

Basicly a Cloud represents a collection of Nodes (and Relations that are also nodes), and is also associated with a certain authentication UserContext. A Cloud can be obtained using a CloudContext (which itself can be obtained from ContextProvider). The Cloud also contains the information about what types of nodes getNodeManagers() and what type of relations between nodes getRelationManagers() can be made. Cloud also can support Transactions, which are a kind of temporary 'sub' clouds.

Version:

$Id$

Author:

Rob Vermeulen, Pierre van Rooden, Jaco de Groot

Field Summary

Fields

Modifier and Type	Field and Description
static String	PROP_IGNOREVALIDATION If you set this property on the cloud to true, validation errors will not be fatal, and nodes can be saved anyways.
static String	PROP_REQUEST With the Cloud a ServletRequest can be associated and stored in a property with this name
static String	PROP_RESPONSE With the Cloud a ServletResponse can be associated and stored in a property with this name.
static String	PROP_SESSIONNAME The cloud itself may have been stored in a user's 'session', using this the key stored in this property.
static String	PROP_XMLMODE This property can contain hints on how to deal with XML fields.

Method Summary

Modifier and Type	Method and Description
Query	createAggregatedQuery()
NodeList	createNodeList() Returns a new, empty node list for this cloud
NodeManagerList	createNodeManagerList() Returns a new, empty node manager list for this cloud
NodeQuery	createNodeQuery() Create an empty NodeQuery, which can be filled, and used in NodeManager.getList(NodeQuery) or getList(Query) (but then no 'real' node are returned).
Query	createQuery() Create an empty Query, which can be filled, and used in getList(Query).
RelationList	createRelationList() Returns a new, empty relation list for this cloud
RelationManagerList	createRelationManagerList() Returns a new, empty relation manager list for this cloud
Transaction	createTransaction() Creates a transaction on this cloud.
Transaction	createTransaction(String name) Creates a transaction on this cloud with a specified name.
Transaction	createTransaction(String name, boolean overwrite) Creates a transaction on this cloud with a specified name.
CloudContext	getCloudContext() Returns the context to which this cloud belongs.
String	getDescription() This may return getName(), but in principable it could have been localized using the value also returned by getLocale().
Function<?>	getFunction(String setName, String functionName) Returns a Function object from a function set.
Collection<Function<?>>	getFunctions(String setName) Returns all Function objects from a function set.
NodeList	getList(Query query) Executes a query and returns the result as a Cluster Node List (also if the query is a NodeQuery).
NodeList	getList(String startNodes, String nodePath, String fields, String constraints, String orderby, String directions, String searchDir, boolean distinct) Returns a list of virtual nodes that are composed by fields of other nodes.
Locale	getLocale() Gets the locale assocatied with this Cloud instance.
String	getName() Returns the name of this cloud.
Node	getNode(int number) Returns the node with the specified number from this cloud.
Node	getNode(String number) Returns the node with the specified number from this cloud.
Node	getNodeByAlias(String alias) Returns the node with the specified alias from this cloud.
NodeManager	getNodeManager(int nodeManagerId) Returns the specified node manager.
NodeManager	getNodeManager(String name) Returns the specified node manager.
NodeManagerList	getNodeManagers() Returns all node managers available in this cloud.
Cloud	getNonTransactionalCloud() Returns a cloud which is not a Transaction.
StringList	getPossibleContexts() Contacts the security implementation to find out to which possible contexts are available to the current user.
Map<Object,Object>	getProperties() Retrieves all properties previously set for this cloud.
Object	getProperty(Object key) Retrieves a property previously set for this cloud.
Relation	getRelation(int number) Returns the relation with the specified number from this cloud.
Relation	getRelation(String number) Returns the relation with the specified number from this cloud.
RelationManager	getRelationManager(int relationManagerId) Returns the specified relation manager.
RelationManager	getRelationManager(NodeManager sourceManager, NodeManager destinationManager, String roleName) Returns the specified relation manager.
RelationManager	getRelationManager(String roleName) Returns the specified relation manager.
RelationManager	getRelationManager(String sourceManagerName, String destinationManagerName, String roleName) Returns the specified relation manager.
RelationManagerList	getRelationManagers() Returns all relation managers available in this cloud.
RelationManagerList	getRelationManagers(NodeManager sourceManager, NodeManager destinationManager, String roleName) Returns all relation managers available in this cloud that follow the specified filter.
RelationManagerList	getRelationManagers(String sourceManagerName, String destinationManagerName, String roleName) Returns all relation managers available in this cloud that follow the specified filter.
Transaction	getTransaction(String name) Returnes the transaction with the specified name.
UserContext	getUser() Who is using this cloud.
boolean	hasNode(int number) Determines whether a node with the specified number exists in this cloud.
boolean	hasNode(String number) Determines whether a node with the specified number is available from this cloud.
boolean	hasNodeManager(String name) Returns whether the specified node manager exists.
boolean	hasRelation(int number) Determines whether a relation with the specified number exists in this cloud.
boolean	hasRelation(String number) Determines whether a relation with the specified number is available from this cloud.
boolean	hasRelationManager(NodeManager sourceManager, NodeManager destinationManager, String roleName) Returns whether the specified relation manager exists.
boolean	hasRelationManager(String roleName) Returns whether the specified relation manager exists.
boolean	hasRelationManager(String sourceManagerName, String destinationManagerName, String roleName) Returns whether the specified relation manager exists.
boolean	hasRole(String roleName) Returns whether the specified role exists.
boolean	may(Action action, Parameters parameters) Check whether an action is allowed
boolean	mayRead(int number) Determines whether a node with the specified number is accessible for the user - that is, the user has sufficient rights to read the node.
boolean	mayRead(String number) Determines whether a node with the specified number is accessible for the user - that is, the user has sufficient rights to read the node.
void	setLocale(Locale locale) Sets a locale for this Cloud instance.
void	setProperty(Object key, Object value) Sets a property for this cloud object.
void	shutdown() Shutdown MMBase, if you are allowed to do so.

Field Detail

PROP_XMLMODE

static final String PROP_XMLMODE

This property can contain hints on how to deal with XML fields. Things like 'xml', 'plain', 'wiki'.

See Also:

Constant Field Values

PROP_SESSIONNAME

static final String PROP_SESSIONNAME

The cloud itself may have been stored in a user's 'session', using this the key stored in this property.

See Also:

Constant Field Values

PROP_REQUEST

static final String PROP_REQUEST

With the Cloud a ServletRequest can be associated and stored in a property with this name

Since:

MMBase-1.9

See Also:

Constant Field Values

PROP_RESPONSE

static final String PROP_RESPONSE

With the Cloud a ServletResponse can be associated and stored in a property with this name.

Since:

MMBase-1.9.3

See Also:

Constant Field Values

PROP_IGNOREVALIDATION

static final String PROP_IGNOREVALIDATION

If you set this property on the cloud to true, validation errors will not be fatal, and nodes can be saved anyways.

Since:

MMBase-1.8.6

See Also:

Constant Field Values

Method Detail

getNode

Node getNode(int number)
      throws NotFoundException

Returns the node with the specified number from this cloud. The returned node is a new instance of Node with a reference to this instance of Cloud.

Parameters:

number - the number of the requested node

Returns:

the requested node

Throws:

NotFoundException - if the specified node could not be found

getNode

Node getNode(String number)
      throws NotFoundException

Returns the node with the specified number from this cloud. If the string passed is not a number, the string is assumed to be an alias. The returned node is a new instance of Node with a reference to this instance of Cloud.

Parameters:

number - a string containing the number or alias of the requested node

Returns:

the requested node

Throws:

NotFoundException - if the specified node could not be found

getNodeByAlias

Node getNodeByAlias(String alias)
             throws NotFoundException

Returns the node with the specified alias from this cloud. The returned node is a new instance of Node with a reference to this instance of Cloud.

Parameters:

alias - the alias of the requested node

Returns:

the requested node

Throws:

NotFoundException - if the specified node could not be found

getRelation

Relation getRelation(int number)
              throws NotFoundException

Returns the relation with the specified number from this cloud. The returned node is a new instance of Relation with a reference to this instance of Cloud.

Parameters:

number - the number of the requested node

Returns:

the requested node

Throws:

NotFoundException - if the specified node could not be found

ClassCastException - if the specified node is not a relation

Since:

MMBase-1.6

getRelation

Relation getRelation(String number)
              throws NotFoundException

Returns the relation with the specified number from this cloud. If the string passed is not a number, the string is assumed to be an alias. The returned node is a new instance of Relation with a reference to this instance of Cloud.

Parameters:

number - a string containing the number or alias of the requested node

Returns:

the requested node

Throws:

NotFoundException - if the specified node could not be found

ClassCastException - if the specified node is not a relation

Since:

MMBase-1.6

hasNode

boolean hasNode(int number)

Determines whether a node with the specified number exists in this cloud. Note that this method does not determine whether you may actually access (read) this node, use mayRead(int) to determine this.

Parameters:

number - the number of the node

Returns:

true if the node exists

Since:

MMBase-1.6

hasNode

boolean hasNode(String number)

Determines whether a node with the specified number is available from this cloud. If the string passed is not a number, the string is assumed to be an alias. Note that this method does not determine whether you may actually access (read) this node, use mayRead(int) to determine this.

Parameters:

number - a string containing the number or alias of the requested node

Returns:

true if the node exists

Since:

MMBase-1.6

hasRelation

boolean hasRelation(int number)

Determines whether a relation with the specified number exists in this cloud. The node returns true if a Node exists and is a relation. Note that this method does not determine whether you may actually access (read) this node, use mayRead(int) to determine this.

Parameters:

number - the number of the node

Returns:

true if the relation exists

Since:

MMBase-1.6

hasRelation

boolean hasRelation(String number)

Determines whether a relation with the specified number is available from this cloud. If the string passed is not a number, the string is assumed to be an alias. The node returns true if a Node exists and is a relation. Note that this method does not determine whether you may actually access (read) this node, use mayRead(int) to determine this.

Parameters:

number - a string containing the number or alias of the requested node

Returns:

true if the relation exists

Since:

MMBase-1.6

mayRead

boolean mayRead(int number)

Determines whether a node with the specified number is accessible for the user - that is, the user has sufficient rights to read the node. The node must exist - the method throws an exception if it doesn't.

Parameters:

number - the number of the requested node

Returns:

true if the node is accessible

Throws:

NotFoundException - if the specified node could not be found

Since:

MMBase-1.6

may

boolean may(Action action,
            Parameters parameters)

Check whether an action is allowed

Parameters:

action - Action to perform

parameters - parameters passed into this action

Returns:

true when allowed

Since:

MMBase-1.9

mayRead

boolean mayRead(String number)

Determines whether a node with the specified number is accessible for the user - that is, the user has sufficient rights to read the node. If the string passed is not a number, the string is assumed to be an alias. The node must exist - the method throws an exception if it doesn't.

Parameters:

number - a string containing the number or alias of the requested node

Returns:

true if the node is accessible

Throws:

NotFoundException - if the specified node could not be found

Since:

MMBase-1.6

getNodeManagers

NodeManagerList getNodeManagers()

Returns all node managers available in this cloud.

Returns:

a NodeManagerList containing all node managers available in this cloud.

getNodeManager

NodeManager getNodeManager(String name)
                    throws NotFoundException

Returns the specified node manager.

Parameters:

name - the name of the requested node manager

Returns:

the requested node manager

Throws:

NotFoundException - if the specified node manager could not be found

hasNodeManager

boolean hasNodeManager(String name)

Returns whether the specified node manager exists.

Parameters:

name - the name of the requested node manager

Returns:

true if the specified node manager exists

getNodeManager

NodeManager getNodeManager(int nodeManagerId)
                    throws NotFoundException

Returns the specified node manager.

Parameters:

nodeManagerId - Unique ID of the NodeManager to retrieve

Returns:

the requested node manager

Throws:

NotFoundException - if the specified node manager could not be found

Since:

MMBase-1.6

getRelationManager

RelationManager getRelationManager(int relationManagerId)
                            throws NotFoundException

Returns the specified relation manager.

Parameters:

relationManagerId - Unique ID of the RelationManager to retrieve

Returns:

the requested relation manager

Throws:

NotFoundException - if the specified relation manager could not be found

Since:

MMBase-1.6

getRelationManager

RelationManager getRelationManager(String sourceManagerName,
                                   String destinationManagerName,
                                   String roleName)
                            throws NotFoundException

Returns the specified relation manager.

Parameters:

sourceManagerName - name of the node manager of the source node

destinationManagerName - name of the node manager of the destination node

roleName - name of the role

Returns:

the requested relation manager

Throws:

NotFoundException - if the specified relation manager could not be found

getRelationManager

RelationManager getRelationManager(NodeManager sourceManager,
                                   NodeManager destinationManager,
                                   String roleName)
                            throws NotFoundException

Returns the specified relation manager.

Parameters:

sourceManager - the node manager of the source node

destinationManager - the node manager of the destination node

roleName - name of the role

Returns:

the requested relation manager

Throws:

NotFoundException - if the specified relation manager could not be found

Since:

MMBase-1.7

hasRelationManager

boolean hasRelationManager(String sourceManagerName,
                           String destinationManagerName,
                           String roleName)

Returns whether the specified relation manager exists.

Parameters:

sourceManagerName - name of the node manager of the source node

destinationManagerName - name of the node manager of the destination node

roleName - name of the role

Returns:

true if the specified relation manager could be found

hasRelationManager

boolean hasRelationManager(NodeManager sourceManager,
                           NodeManager destinationManager,
                           String roleName)

Returns whether the specified relation manager exists.

Parameters:

sourceManager - name of the node manager of the source node

destinationManager - name of the node manager of the destination node

roleName - name of the role

Returns:

true if the specified relation manager could be found

Since:

MMBase-1.7

hasRole

boolean hasRole(String roleName)

Returns whether the specified role exists.

Parameters:

roleName - name of the role

Returns:

true if the specified role could be found

Since:

MMBase-1.7

getRelationManager

RelationManager getRelationManager(String roleName)
                            throws NotFoundException

Returns the specified relation manager.

Parameters:

roleName - name of the role

Returns:

the requested relation manager

Throws:

NotFoundException - if the specified relation manager could not be found

hasRelationManager

boolean hasRelationManager(String roleName)

Returns whether the specified relation manager exists.

Parameters:

roleName - name of the role

Returns:

true if the specified relation manager exists

getRelationManagers

RelationManagerList getRelationManagers()

Returns all relation managers available in this cloud.

Returns:

a RelationManagerList containing all relation managers available in this cloud

getRelationManagers

RelationManagerList getRelationManagers(String sourceManagerName,
                                        String destinationManagerName,
                                        String roleName)
                                 throws NotFoundException

Returns all relation managers available in this cloud that follow the specified filter.

Parameters:

sourceManagerName - the name of the manager for the source of the relation

destinationManagerName - the name of the manager for the destination of the relation

roleName - the rolename

Returns:

a RelationManagerList containing all relation managers that follow this filter

Throws:

NotFoundException - if one of the specified relation managers or the rolename could not be found

getRelationManagers

RelationManagerList getRelationManagers(NodeManager sourceManager,
                                        NodeManager destinationManager,
                                        String roleName)
                                 throws NotFoundException

Returns all relation managers available in this cloud that follow the specified filter.

Parameters:

sourceManager - the manager for the source of the relation

destinationManager - the manager for the destination of the relation

roleName - the rolename

Returns:

a RelationManagerList containing all relation managers that follwo thsi filter

Throws:

NotFoundException - if one of the specified relation managers or the rolename could not be found

getCloudContext

CloudContext getCloudContext()

Returns the context to which this cloud belongs.

Returns:

a CloudContext to which this cloud belongs

createTransaction

Transaction createTransaction()

Creates a transaction on this cloud. The returned Transaction will have a generic ID.

Returns:

a Transaction on this cloud

createTransaction

Transaction createTransaction(String name)
                       throws AlreadyExistsException

Creates a transaction on this cloud with a specified name.

Parameters:

name - an unique name to use for the transaction

Returns:

a Transaction on this cloud

Throws:

AlreadyExistsException - if a transaction with the specified name allready exists

createTransaction

Transaction createTransaction(String name,
                              boolean overwrite)
                       throws AlreadyExistsException

Creates a transaction on this cloud with a specified name.

Parameters:

name - an unique name to use for the transaction

overwrite - if true, cancels and replaces any existing transaction of this name for the current user

Returns:

a Transaction on this cloud

Throws:

AlreadyExistsException - if a transaction with the specified name allready exists and overwrite is false

getTransaction

Transaction getTransaction(String name)

Returnes the transaction with the specified name. If no active transaction exists, a new transaction is created.

Parameters:

name - the name of the requested transaction

Returns:

the requested transaction

getName

String getName()

Returns the name of this cloud. The name of the cloud is the string "mmbase" unless this Cloud is a Transaction.

Returns:

the name of this cloud

getDescription

String getDescription()

This may return getName(), but in principable it could have been localized using the value also returned by getLocale().

Returns:

the description of this cloud

getUser

UserContext getUser()

Who is using this cloud.

Returns:

the User object describing who is using this cloud now.

getList

NodeList getList(String startNodes,
                 String nodePath,
                 String fields,
                 String constraints,
                 String orderby,
                 String directions,
                 String searchDir,
                 boolean distinct)

Returns a list of virtual nodes that are composed by fields of other nodes. Starting at one or more specified nodes traversals are made according to a specified path. One traversal makes up one virtual node. All possible traversals that can be made starting at one or more nodes of the same type and following a specified path are stored in the returned list. Suppose we have defined the following:

 - A node manager recordcompany containing a field name.
 - A node manager artist containing a field name.
 - A node manager url containing a field description and url.
 - A relation type related between recordcompany and artist.
 - A relation type related between artist and url.
 - A relation type homepagerel between artist and url.
 

If node 100 has a node manager called recordcompany we can do the following to get a list of the record company's artists and all urls belonging to these artist (including nodes found through the related relation and the homepagerel relation):

 getList("100", "recordcompany,artist,url",
         "artist.name,description,url", null, null, null, null, true);
 

This call returns a list of virtual nodes with the fields artist.name, description and url for every valid traversal.

If we only want to list homepage urls of the artists we do:

 getList("100", "recordcompany,artist,url",
         "artist.name,description,homepagerel,url", null, null, null,
         null, true);
 

If we want to list all url's except the the homepage urls we do:

 getList("100", "recordcompany,artist,url",
         "artist.name,description,related,url", null, null, null, null, true);
 

If node 200 also has a node manager with name recordcompany we can get the info from their artist together with the info of the artist from the first company by also putting number 200 in the first parameter:

 getList("100,200", "recordcompany,artist,url",
         "artist.name,description,related,url", null, null, null, null, true);
 

For more information about the constraints parameter consult NodeManager.getList(String constraints, String orderby, String directions).

Parameters:

startNodes - A comma separated list of node numbers that should be used as a starting point for all traversals or null if all nodes of the first node manager in nodePath should be used.

nodePath - A comma separated list of node manager names which specifies the path that should be followed. It is possible to explicitly specify a relation manager that should be used to go from one node to an other. If no relation manager is specified between two nodes, all possible relation managers that can be used to go to the next specified node in the path are followed.

fields - A comma separated list of field names that will make up the returned virtual nodes. A fieldname can be prefixed with the original node manager name of the field and a dot in cases where more than one node manager in the path has a field with the same name.

constraints - Constraints to prevent nodes from being included in the resulting list which would normally by included or null if no constraints should be applied.

orderby - A comma separated list of field names on which the returned list should be sorted or null if the order of the returned virtual nodes doesn't matter.

directions - A comma separated list of values indicating wether to sort up (ascending) or down (descending) on the corresponding field in the orderby parameter or null if sorting on all fields should be up. The value DOWN (case insensitive) indicates that sorting on the corresponding field should be down, all other values (including the empty value) indicate that sorting on the corresponding field should be up. If the number of values found in this parameter are less than the number of fields in the orderby parameter, all fields that don't have a corresponding direction value are sorted according to the last specified direction value.

searchDir - Determines how directionality affects the search. This is a string with the following possible values:
"both", which is the default, searches for all valid relations through a path, checking full directionality of relations where appropriate. "destination" searches for only those relations in a path where valid relations exist from source to destination, in the order of the nodemanagers given in the nodePath. "source" searches for only those relations in a path where valid relations exist from destination to source, in the order of the nodemanagers given in the nodePath. "all" searches all existing relations, and does not check on directionality. A value of null or any other values than those listed above are ignored. In that case, search is treated as if the default ("both") was specified.

distinct - true if nodes who allready exist in the list should not be added to the list. false if all nodes should be added to the list even if a node with exactly the same field values is allready present.

Returns:

a list of virtual nodes

getList

NodeList getList(Query query)

Executes a query and returns the result as a Cluster Node List (also if the query is a NodeQuery).

Parameters:

query - Query to execute

Returns:

Cluster Node List

Since:

MMBase-1.7

See Also:

SearchQuery

createQuery

Query createQuery()

Create an empty Query, which can be filled, and used in getList(Query).

Returns:

empty Query

Since:

MMBase-1.7

createAggregatedQuery

Query createAggregatedQuery()

createNodeQuery

NodeQuery createNodeQuery()

Create an empty NodeQuery, which can be filled, and used in NodeManager.getList(NodeQuery) or getList(Query) (but then no 'real' node are returned). The query can be used on NodeManager only when at least one step is added, and NodeQuery.setNodeStep(org.mmbase.storage.search.Step) is called.

Returns:

empty NodeQuery

Since:

MMBase-1.7

setLocale

void setLocale(Locale locale)

Sets a locale for this Cloud instance.

Parameters:

locale - To which locale it must be set. It can be null, in which case it will be reset to a default.

Since:

MMBase-1.6

getLocale

Locale getLocale()

Gets the locale assocatied with this Cloud instance.

Returns:

Locale of this Cloud instance

Since:

MMBase-1.6

getProperty

Object getProperty(Object key)

Retrieves a property previously set for this cloud. If this Cloud has a 'parent' cloud (ie. this Cloud is a Transaction), then this will also mirror properties in this parent cloud.

Parameters:

key - the key of the property

Returns:

the property value

Since:

MMBase-1.8

See Also:

setProperty(Object, Object)

setProperty

void setProperty(Object key,
                 Object value)

Sets a property for this cloud object. This can be used as a kind of 'environment' variables.

Parameters:

key - the key of the property

value - the property value

Since:

MMBase-1.8

getProperties

Map<Object,Object> getProperties()

Retrieves all properties previously set for this cloud.

Returns:

all properties

Since:

MMBase-1.8

getFunctions

Collection<Function<?>> getFunctions(String setName)

Returns all Function objects from a function set. Function sets group functions by name, and are configured in the functionset.xml configuration file. In each entry in the returned map, the key is the function name, and the value is a Function object.

Parameters:

setName - name of the function set

Returns:

a Set of Function objects.

Throws:

NotFoundException - if the function set does not exist

Since:

MMBase-1.8

getFunction

Function<?> getFunction(String setName,
                        String functionName)

Returns a Function object from a function set. Function sets group functions by name, and are configured in the functionset.xml configuration file. The object returned is a Function object.

Parameters:

setName - name of the function set

functionName - name of the function

Returns:

a Function object.

Throws:

NotFoundException - if the function set or the function do not exist

Since:

MMBase-1.8

createNodeList

NodeList createNodeList()

Returns a new, empty node list for this cloud

Returns:

The empty list

Since:

MMBase-1.8

createRelationList

RelationList createRelationList()

Returns a new, empty relation list for this cloud

Returns:

The empty list

Since:

MMBase-1.8

createNodeManagerList

NodeManagerList createNodeManagerList()

Returns a new, empty node manager list for this cloud

Returns:

The empty list

Since:

MMBase-1.8

createRelationManagerList

RelationManagerList createRelationManagerList()

Returns a new, empty relation manager list for this cloud

Returns:

The empty list

Since:

MMBase-1.8

getPossibleContexts

StringList getPossibleContexts()

Contacts the security implementation to find out to which possible contexts are available to the current user.

Returns:

A StringList containing the contexts which can be used by teh suer

Throws:

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

getNonTransactionalCloud

Cloud getNonTransactionalCloud()

Returns a cloud which is not a Transaction.

Returns:

This cloud or a parent cloud if this cloud is a Transaction

Since:

MMBase-1.9.1

shutdown

void shutdown()

Shutdown MMBase, if you are allowed to do so.

Throws:

SecurityException - If you are not allowed.

Since:

MMBase-1.9