KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > mmbase > bridge > Cloud


1 /*
2
3 This software is OSI Certified Open Source Software.
4 OSI Certified is a certification mark of the Open Source Initiative.
5
6 The license (Mozilla version 1.0) can be read at the MMBase site.
7 See http://www.MMBase.org/license
8
9 */

10
11 package org.mmbase.bridge;
12 import java.util.*;
13
14 import org.mmbase.security.UserContext;
15 import org.mmbase.util.functions.Function;
16
17 /**
18  * A Cloud is a collection of Nodes (and relations that are also nodes).
19  * A Cloud is part of a CloudContexts.
20  *
21  * @author Rob Vermeulen
22  * @author Pierre van Rooden
23  * @author Jaco de Groot
24  * @version $Id: Cloud.java,v 1.58.2.1 2006/09/07 12:46:22 pierre Exp $
25  */

26 public interface Cloud {
27
28     public static final String JavaDoc PROP_XMLMODE = "org.mmbase.xml-mode";
29
30     public static final String JavaDoc PROP_SESSIONNAME = "org.mmbase.cloud.sessionname";
31
32     /**
33      * Returns the node with the specified number from this cloud. The returned
34      * node is a new instance of <code>Node</code> with a reference to this
35      * instance of <code>Cloud</code>.
36      *
37      * @param number the number of the requested node
38      * @return the requested node
39      * @throws NotFoundException if the specified node could not be found
40      */

41     public Node getNode(int number) throws NotFoundException;
42
43     /**
44      * Returns the node with the specified number from this cloud.
45      * If the string passed is not a number, the string is assumed to be an alias.
46      * The returned node is a new instance of <code>Node</code> with a reference to this
47      * instance of <code>Cloud</code>.
48      *
49      * @param number a string containing the number or alias of the requested node
50      * @return the requested node
51      * @throws NotFoundException if the specified node could not be found
52      */

53     public Node getNode(String JavaDoc number) throws NotFoundException;
54
55
56     /**
57      * Returns the node with the specified alias from this cloud. The returned
58      * node is a new instance of <code>Node</code> with a reference to this
59      * instance of <code>Cloud</code>.
60      *
61      * @param alias the alias of the requested node
62      * @return the requested node
63      * @throws NotFoundException if the specified node could not be found
64      */

65     public Node getNodeByAlias(String JavaDoc alias) throws NotFoundException;
66
67     /**
68      * Returns the relation with the specified number from this cloud. The returned
69      * node is a new instance of <code>Relation</code> with a reference to this
70      * instance of <code>Cloud</code>.
71      *
72      * @param number the number of the requested node
73      * @return the requested node
74      * @throws NotFoundException if the specified node could not be found
75      * @throws ClassCastException if the specified node is not a relation
76      * @since MMBase-1.6
77      */

78     public Relation getRelation(int number) throws NotFoundException;
79
80     /**
81      * Returns the relation with the specified number from this cloud.
82      * If the string passed is not a number, the string is assumed to be an alias.
83      * The returned node is a new instance of <code>Relation</code> with a reference to this
84      * instance of <code>Cloud</code>.
85      *
86      * @param number a string containing the number or alias of the requested node
87      * @return the requested node
88      * @throws NotFoundException if the specified node could not be found
89      * @throws ClassCastException if the specified node is not a relation
90      * @since MMBase-1.6
91      */

92     public Relation getRelation(String JavaDoc number) throws NotFoundException;
93
94     /**
95      * Determines whether a node with the specified number exists in this cloud.
96      * Note that this method does not determien whether you may actually access (read) this node,
97      * use {@link #mayRead(int)} to determine this.
98      *
99      * @param number the number of the node
100      * @return true if the node exists
101      * @since MMBase-1.6
102      */

103     public boolean hasNode(int number);
104
105     /**
106      * Determines whether a node with the specified number is available from this cloud.
107      * If the string passed is not a number, the string is assumed to be an alias.
108      * Note that this method does not determien whether you may actually access (read) this node,
109      * use {@link #mayRead(int)} to determine this.
110      *
111      * @param number a string containing the number or alias of the requested node
112      * @return true if the node exists
113      * @since MMBase-1.6
114      */

115     public boolean hasNode(String JavaDoc number);
116
117     /**
118      * Determines whether a relation with the specified number exists in this cloud.
119      * The node returns true if a Node exists and is a relation.
120      * Note that this method does not determien whether you may actually access (read) this node,
121      * use {@link #mayRead(int)} to determine this.
122      *
123      * @param number the number of the node
124      * @return true if the relation exists
125      * @since MMBase-1.6
126      */

127     public boolean hasRelation(int number);
128
129     /**
130      * Determines whether a relation with the specified number is available from this cloud.
131      * If the string passed is not a number, the string is assumed to be an alias.
132      * The node returns true if a Node exists and is a relation.
133      * Note that this method does not determien whether you may actually access (read) this node,
134      * use {@link #mayRead(int)} to determine this.
135      *
136      * @param number a string containing the number or alias of the requested node
137      * @return true if the relation exists
138      * @since MMBase-1.6
139      */

140     public boolean hasRelation(String JavaDoc number);
141
142     /**
143      * Determines whether a node with the specified number is accessible for the user - that is,
144      * the user has sufficient rights to read the node.
145      * The node must exist - the method throws an exception if it doesn't.
146      *
147      * @param number the number of the requested node
148      * @return true if the node is accessible
149      * @throws NotFoundException if the specified node could not be found
150      * @since MMBase-1.6
151      */

152     public boolean mayRead(int number);
153
154     /**
155      * Determines whether a node with the specified number is accessible for the user - that is,
156      * the user has sufficient rights to read the node.
157      * If the string passed is not a number, the string is assumed to be an alias.
158      * The node must exist - the method throws an exception if it doesn't.
159      *
160      * @param number a string containing the number or alias of the requested node
161      * @return true if the node is accessible
162      * @throws NotFoundException if the specified node could not be found
163      * @since MMBase-1.6
164      */

165     public boolean mayRead(String JavaDoc number);
166
167     /**
168      * Returns all node managers available in this cloud.
169      *
170      * @return a <code>NodeManagerList</code> containing all node managers
171      * available in this cloud.
172      */

173     public NodeManagerList getNodeManagers();
174
175     /**
176      * Returns the specified node manager.
177      *
178      * @param name the name of the requested node manager
179      * @return the requested node manager
180      * @throws NotFoundException if the specified node manager could not be found
181      */

182     public NodeManager getNodeManager(String JavaDoc name) throws NotFoundException;
183
184     /**
185      * Returns whether the specified node manager exists.
186      *
187      * @param name the name of the requested node manager
188      * @return <code>true</code> if the specified node manager exists
189      */

190     public boolean hasNodeManager(String JavaDoc name);
191
192     /**
193      * Returns the specified node manager.
194      *
195      * @param nodeManagerId Unique ID of the NodeManager to retrieve
196      * @return the requested node manager
197      * @throws NotFoundException if the specified node manager could not be found
198      * @since MMBase-1.6
199      */

200     public NodeManager getNodeManager(int nodeManagerId) throws NotFoundException;
201
202     /**
203      * Returns the specified relation manager.
204      *
205      * @param relationManagerId Unique ID of the RelationManager to retrieve
206      * @return the requested relation manager
207      * @throws NotFoundException if the specified relation manager could not be found
208      * @since MMBase-1.6
209      */

210     public RelationManager getRelationManager(int relationManagerId) throws NotFoundException;
211
212     /**
213      * Returns the specified relation manager.
214      *
215      * @param sourceManagerName name of the node manager of the source node
216      * @param destinationManagerName name of the node manager of the destination node
217      * @param roleName name of the role
218      * @return the requested relation manager
219      * @throws NotFoundException if the specified relation manager could not be found
220      */

221     public RelationManager getRelationManager(String JavaDoc sourceManagerName, String JavaDoc destinationManagerName, String JavaDoc roleName) throws NotFoundException;
222
223
224     /**
225      * Returns the specified relation manager.
226      *
227      * @param sourceManager the node manager of the source node
228      * @param destinationManager the node manager of the destination node
229      * @param roleName name of the role
230      * @return the requested relation manager
231      * @throws NotFoundException if the specified relation manager could not be found
232      * @since MMBase-1.7
233      */

234     public RelationManager getRelationManager(NodeManager sourceManager, NodeManager destinationManager, String JavaDoc roleName) throws NotFoundException;
235
236
237
238     /**
239      * Returns whether the specified relation manager exists.
240      *
241      * @param sourceManagerName name of the node manager of the source node
242      * @param destinationManagerName name of the node manager of the destination node
243      * @param roleName name of the role
244      * @return <code>true</code> if the specified relation manager could be found
245      */

246     public boolean hasRelationManager(String JavaDoc sourceManagerName, String JavaDoc destinationManagerName, String JavaDoc roleName);
247
248
249     /**
250      * Returns whether the specified relation manager exists.
251      *
252      * @param sourceManager name of the node manager of the source node
253      * @param destinationManager name of the node manager of the destination node
254      * @param roleName name of the role
255      * @return <code>true</code> if the specified relation manager could be found
256      * @since MMBase-1.7
257      */

258     public boolean hasRelationManager(NodeManager sourceManager, NodeManager destinationManager, String JavaDoc roleName);
259
260
261     /**
262      * Returns whether the specified role exists.
263      * @param roleName name of the role
264      * @return <code>true</code> if the specified role could be found
265      * @since MMBase-1.7
266      */

267     public boolean hasRole(String JavaDoc roleName);
268
269
270     /**
271      * Returns the specified relation manager.
272      *
273      * @param roleName name of the role
274      * @return the requested relation manager
275      * @throws NotFoundException if the specified relation manager could not be found
276      */

277     public RelationManager getRelationManager(String JavaDoc roleName) throws NotFoundException;
278
279     /**
280      * Returns whether the specified relation manager exists.
281      *
282      * @param roleName name of the role
283      * @return <code>true</code> if the specified relation manager exists
284      */

285     public boolean hasRelationManager(String JavaDoc roleName);
286
287     /**
288      * Returns all relation managers available in this cloud.
289      *
290      * @return a <code>RelationManagerList</code> containing all relation
291      * managers available in this cloud
292      */

293     public RelationManagerList getRelationManagers();
294
295     /**
296      * Returns all relation managers available in this cloud that follow the specified filter.
297      *
298      * @param sourceManagerName the name of the manager for the source of the relation
299      * @param destinationManagerName the name of the manager for the destination of the relation
300      * @param roleName the rolename
301      * @return a <code>RelationManagerList</code> containing all relation
302      * managers that follow this filter
303      * @throws NotFoundException if one of the specified relation managers or the rolename could not be found
304      */

305     public RelationManagerList getRelationManagers(String JavaDoc sourceManagerName, String JavaDoc destinationManagerName, String JavaDoc roleName) throws NotFoundException;
306
307     /**
308      * Returns all relation managers available in this cloud that follow the specified filter.
309      *
310      * @param sourceManager the manager for the source of the relation
311      * @param destinationManager the manager for the destination of the relation
312      * @param roleName the rolename
313      * @return a <code>RelationManagerList</code> containing all relation
314      * managers that follwo thsi filter
315      * @throws NotFoundException if one of the specified relation managers or the rolename could not be found
316      */

317     public RelationManagerList getRelationManagers(NodeManager sourceManager, NodeManager destinationManager,
318                 String JavaDoc roleName) throws NotFoundException;
319
320     /**
321      * Returns the context to which this cloud belongs.
322      *
323      * @return a <code>CloudContext</code> to which this cloud belongs
324      */

325     public CloudContext getCloudContext();
326
327     /**
328      * Creates a transaction on this cloud. The returned
329      * <code>Transaction</code> will have a generic ID.
330      *
331      * @return a <code>Transaction</code> on this cloud
332      */

333     public Transaction createTransaction();
334
335     /**
336      * Creates a transaction on this cloud with a specified name.
337      *
338      * @param name an unique name to use for the transaction
339      * @return a <code>Transaction</code> on this cloud
340      * @throws AlreadyExistsException if a transaction with the specified name allready exists
341      */

342     public Transaction createTransaction(String JavaDoc name) throws AlreadyExistsException;
343
344     /**
345      * Creates a transaction on this cloud with a specified name.
346      *
347      * @param name an unique name to use for the transaction
348      * @param overwrite if <code>true</code>, cancels and replaces
349      * any existing transaction of this name for the current user
350      * @return a <code>Transaction</code> on this cloud
351      * @throws AlreadyExistsException if a transaction with the specified name allready
352      * exists and overwrite is <code>false</code>
353      */

354     public Transaction createTransaction(String JavaDoc name, boolean overwrite) throws AlreadyExistsException;
355
356     /**
357      * Returnes the transaction with the specified name.
358      * If no active transaction exists, a new transaction is created.
359      *
360      * @param name the name of the requested transaction
361      * @return the requested transaction
362      */

363     public Transaction getTransaction(String JavaDoc name);
364
365
366     /**
367      * Returns the name of this cloud. The name of the cloud is the string "mmbase" unless this
368      * Cloud is a {@link Transaction}.
369      *
370      * @return the name of this cloud
371      */

372     public String JavaDoc getName();
373
374     /**
375      * This may return {@link #getName}, but in principable it could have been localized using the
376      * value also returned by {@link #getLocale}.
377      *
378      * @return the description of this cloud
379      */

380     public String JavaDoc getDescription();
381
382     /**
383      * Who is using this cloud.
384      *
385      * @return the User object describing who is using this cloud now.
386      */

387     public UserContext getUser();
388
389     /**
390      * Returns a list of virtual nodes that are composed by fields of other
391      * nodes.
392      * Starting at one or more specified nodes traversals are made according to
393      * a specified path. One traversal makes up one virtual node. All possible
394      * traversals that can be made starting at one or more nodes of the same
395      * type and following a specified path are stored in the returned list.
396      *
397      * Suppose we have defined the following:
398      *
399      * <pre>
400      * - A node manager recordcompany containing a field name.
401      * - A node manager artist containing a field name.
402      * - A node manager url containing a field description and url.
403      * - A relation type related between recordcompany and artist.
404      * - A relation type related between artist and url.
405      * - A relation type homepagerel between artist and url.
406      * </pre>
407      *
408      * If node 100 has a node manager called recordcompany we can do
409      * the following to get a list of the record company's artists and all urls
410      * belonging
411      * to these artist (including nodes found through the related relation and
412      * the homepagerel relation):
413      * <pre>
414      * getList("100", "recordcompany,artist,url",
415      * "artist.name,description,url", null, null, null, null, true);
416      * </pre>
417      * This call returns a list of virtual nodes with the fields artist.name,
418      * description and url for every valid traversal.
419      *
420      * <p>
421      * If we only want to list homepage urls of the artists we do:
422      * <pre>
423      * getList("100", "recordcompany,artist,url",
424      * "artist.name,description,homepagerel,url", null, null, null,
425      * null, true);
426      * </pre>
427      *
428      * <p>
429      * If we want to list all url's except the the homepage urls we do:
430      * <pre>
431      * getList("100", "recordcompany,artist,url",
432      * "artist.name,description,related,url", null, null, null, null, true);
433      * </pre>
434      *
435      * <p>
436      * If node 200 also has a node manager with name recordcompany we can get
437      * the info from their artist together with the info of the artist from the
438      * first company by also putting number 200 in the first parameter:
439      * <pre>
440      * getList("100,200", "recordcompany,artist,url",
441      * "artist.name,description,related,url", null, null, null, null, true);
442      * </pre>
443      *
444      * For more information about the <code>constraints</code> parameter consult
445      * {@link NodeManager#getList(String constraints, String orderby, String
446      * directions)}.
447      *
448      * @param startNodes A comma separated list of node numbers that should
449      * be used as a starting point for all traversals
450      * or <code>null</code> if all nodes of the first node
451      * manager in <code>nodePath</code> should be used.
452      * @param nodePath A comma separated list of node manager names
453      * which specifies the path that should be followed.
454      * It is possible to explicitly specify a relation
455      * manager that should be used to go from one node to
456      * an other. If no relation manager is specified
457      * between two nodes, all possible relation managers
458      * that can be used to go to the next specified node in
459      * the path are followed.
460      * @param fields A comma separated list of field names that will make
461      * up the returned virtual
462      * nodes. A fieldname can be prefixed with the
463      * original node manager name of the field and a dot
464      * in cases where more than one node manager in the
465      * path has a field with the same name.
466      * @param constraints Constraints to prevent nodes from being
467      * included in the resulting list which would normally
468      * by included or <code>null</code> if no constraints
469      * should be applied.
470      * @param orderby A comma separated list of field names on which the
471      * returned list should be sorted or <code>null</code>
472      * if the order of the returned virtual nodes doesn't
473      * matter.
474      * @param directions A comma separated list of values indicating wether
475      * to sort up (ascending) or down (descending) on the
476      * corresponding field in the <code>orderby</code>
477      * parameter or <code>null</code> if sorting on all
478      * fields should be up.
479      * The value DOWN (case insensitive) indicates
480      * that sorting on the corresponding field should be
481      * down, all other values (including the
482      * empty value) indicate that sorting on the
483      * corresponding field should be up.
484      * If the number of values found in this parameter are
485      * less than the number of fields in the
486      * <code>orderby</code> parameter, all fields that
487      * don't have a corresponding direction value are
488      * sorted according to the last specified direction
489      * value.
490      * @param searchDir Determines how directionality affects the search.
491      * This is a string with the following possible values:<br />
492      * <code>"both"</code>, which is the default, searches for all
493      * valid relations through a path, checking full directionality
494      * of relations where appropriate.
495      * <code>"destination"</code> searches for only those relations
496      * in a path where valid relations exist from source to destination,
497      * in the order of the nodemanagers given in the nodePath.
498      * <code>"source"</code> searches for only those relations
499      * in a path where valid relations exist from destination to source,
500      * in the order of the nodemanagers given in the nodePath.
501      * <code>"all"</code> searches all existing relations, and does
502      * not check on directionality.
503      * A value of <code>null</code> or any other values than those
504      * listed above are ignored. In that case, search is
505      * treated as if the default (<code>"both"</code>) was specified.
506      * @param distinct <code>true</code> if nodes who allready exist in
507      * the list should not be added to the list.
508      * <code>false</code> if all nodes should be added to
509      * the list even if a node with exactly the same field
510      * values is allready present.
511      * @return a list of virtual nodes
512      */

513     public NodeList getList(String JavaDoc startNodes, String JavaDoc nodePath, String JavaDoc fields,
514             String JavaDoc constraints, String JavaDoc orderby, String JavaDoc directions,
515             String JavaDoc searchDir, boolean distinct);
516
517     /**
518      * Executes a query and returns the result as a Cluster Node List (also if the query is a {@link NodeQuery}).
519      * @param query Query to execute
520      * @return Cluster Node List
521      *
522      * @see org.mmbase.storage.search.SearchQuery
523      * @since MMBase-1.7
524      */

525     public NodeList getList(Query query);
526
527
528     /**
529      * Create an empty Query, which can be filled, and used in {@link #getList(Query)}.
530      * @return empty Query
531      * @since MMBase-1.7
532      */

533     public Query createQuery();
534
535
536     /*
537      * TODO: Why has there to be a difference between aggregated and non-aggregaged queries?
538      * @since MMBase-1.7
539      */

540     public Query createAggregatedQuery();
541
542
543     /**
544      * Create an empty NodeQuery, which can be filled, and used in {@link NodeManager#getList(NodeQuery)} or
545      * {@link #getList(Query)} (but then no 'real' node are returned). The query can be used on NodeManager only when at
546      * least one step is added, and {@link NodeQuery#setNodeStep} is called.
547      * @return empty NodeQuery
548      * @since MMBase-1.7
549      */

550     public NodeQuery createNodeQuery();
551
552
553     /**
554      * Sets a locale for this <code>Cloud</code> instance.
555      * @param locale To which locale it must be set. It can be null, in which case it will be reset to a default.
556      *
557      * @since MMBase-1.6
558      */

559     public void setLocale(Locale locale);
560
561    /**
562      * Gets the locale assocatied with this <code>Cloud</code> instance.
563      * @return Locale of this Cloud instance
564      *
565      * @since MMBase-1.6
566      */

567     public Locale getLocale();
568
569     /**
570      * Retrieves a property previously set for this cloud.
571      * @see #setProperty(Object, Object)
572      * @param key the key of the property
573      * @return the property value
574      * @since MMBase-1.8
575      */

576     public Object JavaDoc getProperty(Object JavaDoc key);
577
578     /**
579      * Sets a property for this cloud object.
580      * This can be used as a kind of 'environment' variables.
581      * @param key the key of the property
582      * @param value the property value
583      * @since MMBase-1.8
584      */

585     public void setProperty(Object JavaDoc key, Object JavaDoc value);
586
587     /**
588      * Retrieves all properties previously set for this cloud.
589      * @since MMBase-1.8
590      */

591     public Map getProperties();
592
593     /**
594      * Returns all Function objects from a function set.
595      * Function sets group functions by name, and are configured in the functionset.xml configuration file.
596      * In each entry in the returned map, the key is the function name, and the value is a
597      * {@link org.mmbase.util.functions.Function} object.
598      *
599      * @since MMBase-1.8
600      * @param setName name of the function set
601      * @return a Set of {@link org.mmbase.util.functions.Function} objects.
602      * @throws NotFoundException if the function set does not exist
603      */

604     public Collection getFunctions(String JavaDoc setName);
605
606     /**
607      * Returns a Function object from a function set.
608      * Function sets group functions by name, and are configured in the functionset.xml configuration file.
609      * The object returned is a {@link org.mmbase.util.functions.Function} object.
610      *
611      * @since MMBase-1.8
612      * @param setName name of the function set
613      * @return a {@link org.mmbase.util.functions.Function} object.
614      * @throws NotFoundException if the function set or the function do not exist
615      */

616     public Function getFunction(String JavaDoc setName, String JavaDoc functionName);
617
618     /**
619      * Returns a new, empty node list for this cloud
620      *
621      * @return The empty list
622      * @since MMBase-1.8
623      */

624     public NodeList createNodeList();
625
626     /**
627      * Returns a new, empty relation list for this cloud
628      *
629      * @return The empty list
630      * @since MMBase-1.8
631      */

632     public RelationList createRelationList();
633
634     /**
635      * Returns a new, empty node manager list for this cloud
636      *
637      * @return The empty list
638      * @since MMBase-1.8
639      */

640     public NodeManagerList createNodeManagerList();
641
642     /**
643      * Returns a new, empty relation manager list for this cloud
644      *
645      * @return The empty list
646      * @since MMBase-1.8
647      */

648     public RelationManagerList createRelationManagerList();
649
650     /**
651      * Contacts the security implementation to find out to which possible contexts are
652      * available to the current user.
653      *
654      * @return A StringList containing the contexts which can be used by teh suer
655      * @throws SecurityException When appropriate rights to perform this are lacking (read rights)
656      */

657     public StringList getPossibleContexts();
658
659 }
660
Popular Tags