001: /*
002:
003: This software is OSI Certified Open Source Software.
004: OSI Certified is a certification mark of the Open Source Initiative.
005:
006: The license (Mozilla version 1.0) can be read at the MMBase site.
007: See http://www.MMBase.org/license
008:
009: */
010:
011: package org.mmbase.bridge;
012:
013: import java.util.*;
014:
015: import org.mmbase.security.UserContext;
016: import org.mmbase.util.functions.Function;
017:
018: /**
019: * A Cloud is a collection of Nodes (and relations that are also nodes).
020: * A Cloud is part of a CloudContexts.
021: *
022: * @author Rob Vermeulen
023: * @author Pierre van Rooden
024: * @author Jaco de Groot
025: * @version $Id: Cloud.java,v 1.66 2008/03/17 10:05:02 michiel Exp $
026: */
027: public interface Cloud {
028:
029: public static final String PROP_XMLMODE = "org.mmbase.xml-mode";
030:
031: public static final String PROP_SESSIONNAME = "org.mmbase.cloud.sessionname";
032:
033: /**
034: * If you set this property on the cloud to true, validation errors will not be fatal, and nodes
035: * can be saved anyways.
036: *
037: * @since MMBase-1.8.6
038: */
039: public static final String PROP_IGNOREVALIDATION = "org.mmbase.cloud.ignore-validation";
040:
041: /**
042: * Returns the node with the specified number from this cloud. The returned
043: * node is a new instance of <code>Node</code> with a reference to this
044: * instance of <code>Cloud</code>.
045: *
046: * @param number the number of the requested node
047: * @return the requested node
048: * @throws NotFoundException if the specified node could not be found
049: */
050: public Node getNode(int number) throws NotFoundException;
051:
052: /**
053: * Returns the node with the specified number from this cloud.
054: * If the string passed is not a number, the string is assumed to be an alias.
055: * The returned node is a new instance of <code>Node</code> with a reference to this
056: * instance of <code>Cloud</code>.
057: *
058: * @param number a string containing the number or alias of the requested node
059: * @return the requested node
060: * @throws NotFoundException if the specified node could not be found
061: */
062: public Node getNode(String number) throws NotFoundException;
063:
064: /**
065: * Returns the node with the specified alias from this cloud. The returned
066: * node is a new instance of <code>Node</code> with a reference to this
067: * instance of <code>Cloud</code>.
068: *
069: * @param alias the alias of the requested node
070: * @return the requested node
071: * @throws NotFoundException if the specified node could not be found
072: */
073: public Node getNodeByAlias(String alias) throws NotFoundException;
074:
075: /**
076: * Returns the relation with the specified number from this cloud. The returned
077: * node is a new instance of <code>Relation</code> with a reference to this
078: * instance of <code>Cloud</code>.
079: *
080: * @param number the number of the requested node
081: * @return the requested node
082: * @throws NotFoundException if the specified node could not be found
083: * @throws ClassCastException if the specified node is not a relation
084: * @since MMBase-1.6
085: */
086: public Relation getRelation(int number) throws NotFoundException;
087:
088: /**
089: * Returns the relation with the specified number from this cloud.
090: * If the string passed is not a number, the string is assumed to be an alias.
091: * The returned node is a new instance of <code>Relation</code> with a reference to this
092: * instance of <code>Cloud</code>.
093: *
094: * @param number a string containing the number or alias of the requested node
095: * @return the requested node
096: * @throws NotFoundException if the specified node could not be found
097: * @throws ClassCastException if the specified node is not a relation
098: * @since MMBase-1.6
099: */
100: public Relation getRelation(String number) throws NotFoundException;
101:
102: /**
103: * Determines whether a node with the specified number exists in this cloud.
104: * Note that this method does not determien whether you may actually access (read) this node,
105: * use {@link #mayRead(int)} to determine this.
106: *
107: * @param number the number of the node
108: * @return true if the node exists
109: * @since MMBase-1.6
110: */
111: public boolean hasNode(int number);
112:
113: /**
114: * Determines whether a node with the specified number is available from this cloud.
115: * If the string passed is not a number, the string is assumed to be an alias.
116: * Note that this method does not determien whether you may actually access (read) this node,
117: * use {@link #mayRead(int)} to determine this.
118: *
119: * @param number a string containing the number or alias of the requested node
120: * @return true if the node exists
121: * @since MMBase-1.6
122: */
123: public boolean hasNode(String number);
124:
125: /**
126: * Determines whether a relation with the specified number exists in this cloud.
127: * The node returns true if a Node exists and is a relation.
128: * Note that this method does not determien whether you may actually access (read) this node,
129: * use {@link #mayRead(int)} to determine this.
130: *
131: * @param number the number of the node
132: * @return true if the relation exists
133: * @since MMBase-1.6
134: */
135: public boolean hasRelation(int number);
136:
137: /**
138: * Determines whether a relation with the specified number is available from this cloud.
139: * If the string passed is not a number, the string is assumed to be an alias.
140: * The node returns true if a Node exists and is a relation.
141: * Note that this method does not determien whether you may actually access (read) this node,
142: * use {@link #mayRead(int)} to determine this.
143: *
144: * @param number a string containing the number or alias of the requested node
145: * @return true if the relation exists
146: * @since MMBase-1.6
147: */
148: public boolean hasRelation(String number);
149:
150: /**
151: * Determines whether a node with the specified number is accessible for the user - that is,
152: * the user has sufficient rights to read the node.
153: * The node must exist - the method throws an exception if it doesn't.
154: *
155: * @param number the number of the requested node
156: * @return true if the node is accessible
157: * @throws NotFoundException if the specified node could not be found
158: * @since MMBase-1.6
159: */
160: public boolean mayRead(int number);
161:
162: /**
163: * Check whether an action is allowed
164: * @param action Action to perform
165: * @param parameters parameters passed into this action
166: * @return <code>true</code> when allowed
167: * @since MMBase-1.9
168: */
169: public boolean may(org.mmbase.security.Action action,
170: org.mmbase.util.functions.Parameters parameters);
171:
172: /**
173: * Determines whether a node with the specified number is accessible for the user - that is,
174: * the user has sufficient rights to read the node.
175: * If the string passed is not a number, the string is assumed to be an alias.
176: * The node must exist - the method throws an exception if it doesn't.
177: *
178: * @param number a string containing the number or alias of the requested node
179: * @return true if the node is accessible
180: * @throws NotFoundException if the specified node could not be found
181: * @since MMBase-1.6
182: */
183: public boolean mayRead(String number);
184:
185: /**
186: * Returns all node managers available in this cloud.
187: *
188: * @return a <code>NodeManagerList</code> containing all node managers
189: * available in this cloud.
190: */
191: public NodeManagerList getNodeManagers();
192:
193: /**
194: * Returns the specified node manager.
195: *
196: * @param name the name of the requested node manager
197: * @return the requested node manager
198: * @throws NotFoundException if the specified node manager could not be found
199: */
200: public NodeManager getNodeManager(String name)
201: throws NotFoundException;
202:
203: /**
204: * Returns whether the specified node manager exists.
205: *
206: * @param name the name of the requested node manager
207: * @return <code>true</code> if the specified node manager exists
208: */
209: public boolean hasNodeManager(String name);
210:
211: /**
212: * Returns the specified node manager.
213: *
214: * @param nodeManagerId Unique ID of the NodeManager to retrieve
215: * @return the requested node manager
216: * @throws NotFoundException if the specified node manager could not be found
217: * @since MMBase-1.6
218: */
219: public NodeManager getNodeManager(int nodeManagerId)
220: throws NotFoundException;
221:
222: /**
223: * Returns the specified relation manager.
224: *
225: * @param relationManagerId Unique ID of the RelationManager to retrieve
226: * @return the requested relation manager
227: * @throws NotFoundException if the specified relation manager could not be found
228: * @since MMBase-1.6
229: */
230: public RelationManager getRelationManager(int relationManagerId)
231: throws NotFoundException;
232:
233: /**
234: * Returns the specified relation manager.
235: *
236: * @param sourceManagerName name of the node manager of the source node
237: * @param destinationManagerName name of the node manager of the destination node
238: * @param roleName name of the role
239: * @return the requested relation manager
240: * @throws NotFoundException if the specified relation manager could not be found
241: */
242: public RelationManager getRelationManager(String sourceManagerName,
243: String destinationManagerName, String roleName)
244: throws NotFoundException;
245:
246: /**
247: * Returns the specified relation manager.
248: *
249: * @param sourceManager the node manager of the source node
250: * @param destinationManager the node manager of the destination node
251: * @param roleName name of the role
252: * @return the requested relation manager
253: * @throws NotFoundException if the specified relation manager could not be found
254: * @since MMBase-1.7
255: */
256: public RelationManager getRelationManager(
257: NodeManager sourceManager, NodeManager destinationManager,
258: String roleName) throws NotFoundException;
259:
260: /**
261: * Returns whether the specified relation manager exists.
262: *
263: * @param sourceManagerName name of the node manager of the source node
264: * @param destinationManagerName name of the node manager of the destination node
265: * @param roleName name of the role
266: * @return <code>true</code> if the specified relation manager could be found
267: */
268: public boolean hasRelationManager(String sourceManagerName,
269: String destinationManagerName, String roleName);
270:
271: /**
272: * Returns whether the specified relation manager exists.
273: *
274: * @param sourceManager name of the node manager of the source node
275: * @param destinationManager name of the node manager of the destination node
276: * @param roleName name of the role
277: * @return <code>true</code> if the specified relation manager could be found
278: * @since MMBase-1.7
279: */
280: public boolean hasRelationManager(NodeManager sourceManager,
281: NodeManager destinationManager, String roleName);
282:
283: /**
284: * Returns whether the specified role exists.
285: * @param roleName name of the role
286: * @return <code>true</code> if the specified role could be found
287: * @since MMBase-1.7
288: */
289: public boolean hasRole(String roleName);
290:
291: /**
292: * Returns the specified relation manager.
293: *
294: * @param roleName name of the role
295: * @return the requested relation manager
296: * @throws NotFoundException if the specified relation manager could not be found
297: */
298: public RelationManager getRelationManager(String roleName)
299: throws NotFoundException;
300:
301: /**
302: * Returns whether the specified relation manager exists.
303: *
304: * @param roleName name of the role
305: * @return <code>true</code> if the specified relation manager exists
306: */
307: public boolean hasRelationManager(String roleName);
308:
309: /**
310: * Returns all relation managers available in this cloud.
311: *
312: * @return a <code>RelationManagerList</code> containing all relation
313: * managers available in this cloud
314: */
315: public RelationManagerList getRelationManagers();
316:
317: /**
318: * Returns all relation managers available in this cloud that follow the specified filter.
319: *
320: * @param sourceManagerName the name of the manager for the source of the relation
321: * @param destinationManagerName the name of the manager for the destination of the relation
322: * @param roleName the rolename
323: * @return a <code>RelationManagerList</code> containing all relation
324: * managers that follow this filter
325: * @throws NotFoundException if one of the specified relation managers or the rolename could not be found
326: */
327: public RelationManagerList getRelationManagers(
328: String sourceManagerName, String destinationManagerName,
329: String roleName) throws NotFoundException;
330:
331: /**
332: * Returns all relation managers available in this cloud that follow the specified filter.
333: *
334: * @param sourceManager the manager for the source of the relation
335: * @param destinationManager the manager for the destination of the relation
336: * @param roleName the rolename
337: * @return a <code>RelationManagerList</code> containing all relation
338: * managers that follwo thsi filter
339: * @throws NotFoundException if one of the specified relation managers or the rolename could not be found
340: */
341: public RelationManagerList getRelationManagers(
342: NodeManager sourceManager, NodeManager destinationManager,
343: String roleName) throws NotFoundException;
344:
345: /**
346: * Returns the context to which this cloud belongs.
347: *
348: * @return a <code>CloudContext</code> to which this cloud belongs
349: */
350: public CloudContext getCloudContext();
351:
352: /**
353: * Creates a transaction on this cloud. The returned
354: * <code>Transaction</code> will have a generic ID.
355: *
356: * @return a <code>Transaction</code> on this cloud
357: */
358: public Transaction createTransaction();
359:
360: /**
361: * Creates a transaction on this cloud with a specified name.
362: *
363: * @param name an unique name to use for the transaction
364: * @return a <code>Transaction</code> on this cloud
365: * @throws AlreadyExistsException if a transaction with the specified name allready exists
366: */
367: public Transaction createTransaction(String name)
368: throws AlreadyExistsException;
369:
370: /**
371: * Creates a transaction on this cloud with a specified name.
372: *
373: * @param name an unique name to use for the transaction
374: * @param overwrite if <code>true</code>, cancels and replaces
375: * any existing transaction of this name for the current user
376: * @return a <code>Transaction</code> on this cloud
377: * @throws AlreadyExistsException if a transaction with the specified name allready
378: * exists and overwrite is <code>false</code>
379: */
380: public Transaction createTransaction(String name, boolean overwrite)
381: throws AlreadyExistsException;
382:
383: /**
384: * Returnes the transaction with the specified name.
385: * If no active transaction exists, a new transaction is created.
386: *
387: * @param name the name of the requested transaction
388: * @return the requested transaction
389: */
390: public Transaction getTransaction(String name);
391:
392: /**
393: * Returns the name of this cloud. The name of the cloud is the string "mmbase" unless this
394: * Cloud is a {@link Transaction}.
395: *
396: * @return the name of this cloud
397: */
398: public String getName();
399:
400: /**
401: * This may return {@link #getName}, but in principable it could have been localized using the
402: * value also returned by {@link #getLocale}.
403: *
404: * @return the description of this cloud
405: */
406: public String getDescription();
407:
408: /**
409: * Who is using this cloud.
410: *
411: * @return the User object describing who is using this cloud now.
412: */
413: public UserContext getUser();
414:
415: /**
416: * Returns a list of virtual nodes that are composed by fields of other
417: * nodes.
418: * Starting at one or more specified nodes traversals are made according to
419: * a specified path. One traversal makes up one virtual node. All possible
420: * traversals that can be made starting at one or more nodes of the same
421: * type and following a specified path are stored in the returned list.
422: *
423: * Suppose we have defined the following:
424: *
425: * <pre>
426: * - A node manager recordcompany containing a field name.
427: * - A node manager artist containing a field name.
428: * - A node manager url containing a field description and url.
429: * - A relation type related between recordcompany and artist.
430: * - A relation type related between artist and url.
431: * - A relation type homepagerel between artist and url.
432: * </pre>
433: *
434: * If node 100 has a node manager called recordcompany we can do
435: * the following to get a list of the record company's artists and all urls
436: * belonging
437: * to these artist (including nodes found through the related relation and
438: * the homepagerel relation):
439: * <pre>
440: * getList("100", "recordcompany,artist,url",
441: * "artist.name,description,url", null, null, null, null, true);
442: * </pre>
443: * This call returns a list of virtual nodes with the fields artist.name,
444: * description and url for every valid traversal.
445: *
446: * <p>
447: * If we only want to list homepage urls of the artists we do:
448: * <pre>
449: * getList("100", "recordcompany,artist,url",
450: * "artist.name,description,homepagerel,url", null, null, null,
451: * null, true);
452: * </pre>
453: *
454: * <p>
455: * If we want to list all url's except the the homepage urls we do:
456: * <pre>
457: * getList("100", "recordcompany,artist,url",
458: * "artist.name,description,related,url", null, null, null, null, true);
459: * </pre>
460: *
461: * <p>
462: * If node 200 also has a node manager with name recordcompany we can get
463: * the info from their artist together with the info of the artist from the
464: * first company by also putting number 200 in the first parameter:
465: * <pre>
466: * getList("100,200", "recordcompany,artist,url",
467: * "artist.name,description,related,url", null, null, null, null, true);
468: * </pre>
469: *
470: * For more information about the <code>constraints</code> parameter consult
471: * {@link NodeManager#getList(String constraints, String orderby, String
472: * directions)}.
473: *
474: * @param startNodes A comma separated list of node numbers that should
475: * be used as a starting point for all traversals
476: * or <code>null</code> if all nodes of the first node
477: * manager in <code>nodePath</code> should be used.
478: * @param nodePath A comma separated list of node manager names
479: * which specifies the path that should be followed.
480: * It is possible to explicitly specify a relation
481: * manager that should be used to go from one node to
482: * an other. If no relation manager is specified
483: * between two nodes, all possible relation managers
484: * that can be used to go to the next specified node in
485: * the path are followed.
486: * @param fields A comma separated list of field names that will make
487: * up the returned virtual
488: * nodes. A fieldname can be prefixed with the
489: * original node manager name of the field and a dot
490: * in cases where more than one node manager in the
491: * path has a field with the same name.
492: * @param constraints Constraints to prevent nodes from being
493: * included in the resulting list which would normally
494: * by included or <code>null</code> if no constraints
495: * should be applied.
496: * @param orderby A comma separated list of field names on which the
497: * returned list should be sorted or <code>null</code>
498: * if the order of the returned virtual nodes doesn't
499: * matter.
500: * @param directions A comma separated list of values indicating wether
501: * to sort up (ascending) or down (descending) on the
502: * corresponding field in the <code>orderby</code>
503: * parameter or <code>null</code> if sorting on all
504: * fields should be up.
505: * The value DOWN (case insensitive) indicates
506: * that sorting on the corresponding field should be
507: * down, all other values (including the
508: * empty value) indicate that sorting on the
509: * corresponding field should be up.
510: * If the number of values found in this parameter are
511: * less than the number of fields in the
512: * <code>orderby</code> parameter, all fields that
513: * don't have a corresponding direction value are
514: * sorted according to the last specified direction
515: * value.
516: * @param searchDir Determines how directionality affects the search.
517: * This is a string with the following possible values:<br />
518: * <code>"both"</code>, which is the default, searches for all
519: * valid relations through a path, checking full directionality
520: * of relations where appropriate.
521: * <code>"destination"</code> searches for only those relations
522: * in a path where valid relations exist from source to destination,
523: * in the order of the nodemanagers given in the nodePath.
524: * <code>"source"</code> searches for only those relations
525: * in a path where valid relations exist from destination to source,
526: * in the order of the nodemanagers given in the nodePath.
527: * <code>"all"</code> searches all existing relations, and does
528: * not check on directionality.
529: * A value of <code>null</code> or any other values than those
530: * listed above are ignored. In that case, search is
531: * treated as if the default (<code>"both"</code>) was specified.
532: * @param distinct <code>true</code> if nodes who allready exist in
533: * the list should not be added to the list.
534: * <code>false</code> if all nodes should be added to
535: * the list even if a node with exactly the same field
536: * values is allready present.
537: * @return a list of virtual nodes
538: */
539: public NodeList getList(String startNodes, String nodePath,
540: String fields, String constraints, String orderby,
541: String directions, String searchDir, boolean distinct);
542:
543: /**
544: * Executes a query and returns the result as a Cluster Node List (also if the query is a {@link NodeQuery}).
545: * @param query Query to execute
546: * @return Cluster Node List
547: *
548: * @see org.mmbase.storage.search.SearchQuery
549: * @since MMBase-1.7
550: */
551: public NodeList getList(Query query);
552:
553: /**
554: * Create an empty Query, which can be filled, and used in {@link #getList(Query)}.
555: * @return empty Query
556: * @since MMBase-1.7
557: */
558: public Query createQuery();
559:
560: /*
561: * TODO: Why has there to be a difference between aggregated and non-aggregaged queries?
562: * @since MMBase-1.7
563: */
564: public Query createAggregatedQuery();
565:
566: /**
567: * Create an empty NodeQuery, which can be filled, and used in {@link NodeManager#getList(NodeQuery)} or
568: * {@link #getList(Query)} (but then no 'real' node are returned). The query can be used on NodeManager only when at
569: * least one step is added, and {@link NodeQuery#setNodeStep} is called.
570: * @return empty NodeQuery
571: * @since MMBase-1.7
572: */
573: public NodeQuery createNodeQuery();
574:
575: /**
576: * Sets a locale for this <code>Cloud</code> instance.
577: * @param locale To which locale it must be set. It can be null, in which case it will be reset to a default.
578: *
579: * @since MMBase-1.6
580: */
581: public void setLocale(Locale locale);
582:
583: /**
584: * Gets the locale assocatied with this <code>Cloud</code> instance.
585: * @return Locale of this Cloud instance
586: *
587: * @since MMBase-1.6
588: */
589: public Locale getLocale();
590:
591: /**
592: * Retrieves a property previously set for this cloud. If this Cloud has a 'parent' cloud
593: * (ie. this Cloud is a {@link Transaction}), then this will also mirror properties in this
594: * parent cloud.
595: * @see #setProperty(Object, Object)
596: * @param key the key of the property
597: * @return the property value
598: * @since MMBase-1.8
599: */
600: public Object getProperty(Object key);
601:
602: /**
603: * Sets a property for this cloud object.
604: * This can be used as a kind of 'environment' variables.
605: * @param key the key of the property
606: * @param value the property value
607: * @since MMBase-1.8
608: */
609: public void setProperty(Object key, Object value);
610:
611: /**
612: * Retrieves all properties previously set for this cloud.
613: * @return all properties
614: * @since MMBase-1.8
615: */
616: public Map<Object, Object> getProperties();
617:
618: /**
619: * Returns all Function objects from a function set.
620: * Function sets group functions by name, and are configured in the functionset.xml configuration file.
621: * In each entry in the returned map, the key is the function name, and the value is a
622: * {@link org.mmbase.util.functions.Function} object.
623: *
624: * @since MMBase-1.8
625: * @param setName name of the function set
626: * @return a Set of {@link org.mmbase.util.functions.Function} objects.
627: * @throws NotFoundException if the function set does not exist
628: */
629: public Collection<Function<?>> getFunctions(String setName);
630:
631: /**
632: * Returns a Function object from a function set.
633: * Function sets group functions by name, and are configured in the functionset.xml configuration file.
634: * The object returned is a {@link org.mmbase.util.functions.Function} object.
635: *
636: * @since MMBase-1.8
637: * @param setName name of the function set
638: * @param functionName name of the function
639: * @return a {@link org.mmbase.util.functions.Function} object.
640: * @throws NotFoundException if the function set or the function do not exist
641: */
642: public Function<?> getFunction(String setName, String functionName);
643:
644: /**
645: * Returns a new, empty node list for this cloud
646: *
647: * @return The empty list
648: * @since MMBase-1.8
649: */
650: public NodeList createNodeList();
651:
652: /**
653: * Returns a new, empty relation list for this cloud
654: *
655: * @return The empty list
656: * @since MMBase-1.8
657: */
658: public RelationList createRelationList();
659:
660: /**
661: * Returns a new, empty node manager list for this cloud
662: *
663: * @return The empty list
664: * @since MMBase-1.8
665: */
666: public NodeManagerList createNodeManagerList();
667:
668: /**
669: * Returns a new, empty relation manager list for this cloud
670: *
671: * @return The empty list
672: * @since MMBase-1.8
673: */
674: public RelationManagerList createRelationManagerList();
675:
676: /**
677: * Contacts the security implementation to find out to which possible contexts are
678: * available to the current user.
679: *
680: * @return A StringList containing the contexts which can be used by teh suer
681: * @throws SecurityException When appropriate rights to perform this are lacking (read rights)
682: */
683: public StringList getPossibleContexts();
684:
685: public Cloud getNonTransactionalCloud();
686:
687: }
|