NodeManager


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.Map  ;
13  import java.util.Locale  ;
14  import javax.servlet.ServletResponse  ;
15  import javax.servlet.ServletRequest  ;
16  
17  
18  /**
19   * This interface represents a node's type information object - what used to be the 'builder'.
20   * It contains all the field and attribuut information, as well as GUI data for editors and
21   * some information on deribed and deriving types. It also contains some maintenance code - code
22   * to create new nodes, en code to query objects belonging to the same manager.
23   * Since node types are normally maintained through use of config files (and not in the database),
24   * as wel as for security issues, the data of a nodetype cannot be changed except through
25   * the use of an administration module (which is why we do not include setXXX methods here).
26   * @author Rob Vermeulen
27   * @author Pierre van Rooden
28   * @version $Id: NodeManager.java,v 1.38 2005/09/19 12:24:21 pierre Exp $
29   */
30  public interface NodeManager extends Node {
31  
32      /**
33       * A constant for use with {@link #getFields(int)}, meaning `all fields, even those which are
34       * not stored.
35       */
36      public final static int ORDER_NONE = -1;
37      /**
38       * A constant for use with {@link #getFields(int)}, meaning `all fields, in storage order (so
39       * which are in storage'.
40       */
41      public final static int ORDER_CREATE = 0;
42      /**
43       * A constant for use with {@link #getFields(int)}, meaning all fields which a user may want to
44       * fill when creating or editing this node. That are normally all nodes without the `automatic'
45       * ones like `number' and `otype'.
46       */
47      public final static int ORDER_EDIT = 1;
48      /**
49       * A constant for use with {@link #getFields(int)}. When presenting a Node in some list overview
50       * then less essential fields can be left out, to get a more concise presentation of the node.
51       */
52      public final static int ORDER_LIST = 2;
53      /**
54       * A constant for use with {@link #getFields(int)} On some fields, like binary fields (e.g. images) it makes no sense searching. These are left
55       * out among the `search' fields.
56       */
57      public final static int ORDER_SEARCH = 3;
58  
59      public final static int GUI_SINGULAR = 1;
60      public final static int GUI_PLURAL = 2;
61  
62      /**
63      * Creates a new node. The returned node will not be visible in the cloud
64      * until the commit() method is called on this node. Until then it will have
65      * a temporary node number.
66      *
67      * @return the new <code>Node</code>
68      */
69      public Node createNode();
70  
71      /**
72       * Returns the cloud to which this manager belongs.
73       *
74       * @return the cloud to which this manager belongs
75       */
76      public Cloud getCloud();
77  
78      /**
79       * Retrieve the parent of this NodeManager (the Nodemanager that this nodemanager extends from)
80       * @return the NodeManager's parent
81       * @throws NotFoundException if no parent exists (i.e. this nodeManager is "object")
82       */
83      public NodeManager getParent() throws NotFoundException;
84  
85      /**
86       * Retrieve a  list of descendant nodemanagers (the Nodemanager that - posisbly indirectly - extend from this nodemanager)
87       * @return a list of NodeManagers
88       * @since MMBase-1.7
89       */
90      public NodeManagerList getDescendants();
91  
92      /**
93       * Returns the name of this node manager. This name is a unique name.
94       *
95       * @return the name of this node manager.
96       */
97      public String   getName();
98  
99      /**
100      * Retrieve a property of the node manager.
101      * @param name the name of the property
102      * @return the property value (null if not given)
103      * @since  MMBase-1.7
104      */
105     public String   getProperty(String   name);
106 
107     /**
108      * Retrieve a copy of the node manager's properties
109      * @return a map of node manager properties
110      * @since  MMBase-1.7
111      */
112     public Map   getProperties();
113 
114     /**
115      * Returns the descriptive name of this node manager. This name will be in
116      * the language of the current cloud  (defined in cloud.getLocale()).
117      *
118      * @return the descriptive name of this node manager
119      */
120     public String   getGUIName();
121 
122     /**
123      * Returns the descriptive name of this node manager. This name will be in
124      * the language of the current cloud  (defined in cloud.getLocale()).
125      *
126      * @since MMBase-1.6
127      * @param plurality the plurality (number of objects) for which to return a description
128      *                  ({@link #GUI_SINGULAR} or {@link #GUI_PLURAL})
129      * @return the descriptive name of this node manager
130      */
131     public String   getGUIName(int plurality);
132 
133     /**
134      * Returns the descriptive name of this node manager ina a specified language.
135      *
136      * @since MMBase-1.6
137      * @param plurality the plurality (number of objects) for which to return a description
138      *                  ({@link #GUI_SINGULAR} or {@link #GUI_PLURAL})
139      * @param locale the locale that determines the language for the GUI name
140      * @return the descriptive name of this node manager
141      */
142     public String   getGUIName(int plurality, Locale   locale);
143 
144     /**
145      * Returns the description of this node manager.
146      *
147      * @return the description of this node manager
148      */
149     public String   getDescription();
150 
151     /**
152      * Returns the description of this node manager in a specified language.
153      *
154      * @param locale the locale that determines the language for the description
155      * @return the description of this node manager
156      * @since MMBase-1.7
157      */
158     public String   getDescription(Locale   locale);
159 
160     /**
161      * Returns a list of all fields defined for this node manager.
162      *
163      * @return a list of all fields defined for this node manager
164      */
165     public FieldList getFields();
166 
167     /**
168      * Retrieve a subset of field types of this NodeManager, depending on a given order. The order
169      * is a integer constant which symbolizes `none', `create', `edit', `list' or `search'. These last three one may recognize
170      * from builder XML's. `none' means `all fields'. The actual integer contants are present as the
171      * ORDER contants in this interface.
172      *
173      * @param order the order in which to list the fields
174      * @return a <code>FieldList</code> object, which is a specialized <code>List</code> of {@link Field} objects.
175      * @see   #ORDER_NONE
176      * @see   #ORDER_CREATE
177      * @see   #ORDER_EDIT
178      * @see   #ORDER_LIST
179      * @see   #ORDER_SEARCH
180      */
181     public FieldList getFields(int order);
182 
183     /**
184      * Returns the field with the specified name.
185      *
186      * @param name  the name of the field to be returned
187      * @return      the field with the requested name
188      * @throws NotFoundException is the field does not exist
189      */
190     public Field getField(String   name) throws NotFoundException;
191 
192     /**
193      * Tests whether the field with the specified name exists in this nodemanager.
194      *
195      * @since MMBase-1.6
196      * @param fieldName  the name of the field to be returned
197      * @return      <code>true</code> if the field with the requested name exists
198      */
199     public boolean hasField(String   fieldName);
200 
201     /**
202      * Returns a list of nodes belonging to this node manager. Constraints can
203      * be given to exclude nodes from the returned list. These constraints
204      * follow the syntax of the SQL where clause. It's a good practice to use
205      * uppercase letters for the operators and lowercase letters for the
206      * fieldnames. Example constraints are:
207      *
208      * <pre>
209      * "number = 100" (!=, <, >, <= and >= can also be used)
210      * "name = 'admin'",
211      * "email IS NULL" (indicating the email field is empty)
212      * "email LIKE '%.org'" (indication the email should end with .org)
213      * "number BETWEEN 99 AND 101"
214      * "name IN ('admin', 'anonymous')"
215      * </pre>
216      *
217      * The NOT operator can be used to get the opposite result like:
218      *
219      * <pre>
220      * "NOT (number = 100)"
221      * "NOT (name = 'admin')",
222      * "email IS NOT NULL"
223      * "email NOT LIKE '%.org'" (indication the email should not end with .org)
224      * "number NOT BETWEEN 99 AND 101"
225      * "name NOT IN ('admin', 'anonymous')"
226      * </pre>
227      *
228      * Some special functions (not part of standard SQL, but most databases
229      * support them) can be used like:
230      *
231      * <pre>
232      * "LOWER(name) = 'admin'" (to also allow 'Admin' to be selected)
233      * "LENGTH(name) > 5" (to only select names longer then 5 characters)
234      * </pre>
235      *
236      * Constraints can be linked together using AND and OR:
237      *
238      * <pre>
239      * "((number=100) OR (name='admin') AND email LIKE '%.org')"
240      * </pre>
241      *
242      * The single quote can be escaped using it twice for every single
243      * occurence:
244      *
245      * <pre>
246      * "name='aaa''bbb'" (if we want to find the string aaa'bbb)
247      * </pre>
248      *
249      * For more info consult a SQL tutorial like
250      * <a HREF="http://hea-www.harvard.edu/MST/simul/software/docs/pkg/pgsql/sqltut/sqltut.htm">Jim Hoffman's introduction to Structured Query Language</a>.
251      *
252      * @param constraints   Constraints to prevent nodes from being
253      *                      included in the resulting list which would normally
254      *                      by included or <code>null</code> if no constraints
255      *                      should be applied .
256      * @param orderby       A comma separated list of field names on which the
257      *                      returned list should be sorted or <code>null</code>
258      *                      if the order of the returned virtual nodes doesn't
259      *                      matter.
260      * @param directions    A comma separated list of values indicating wether
261      *                      to sort up (ascending) or down (descending) on the
262      *                      corresponding field in the <code>orderby</code>
263      *                      parameter or <code>null</code> if sorting on all
264      *                      fields should be up.
265      *                      The value DOWN (case insensitive) indicates
266      *                      that sorting on the corresponding field should be
267      *                      down, all other values (including the
268      *                      empty value) indicate that sorting on the
269      *                      corresponding field should be up.
270      *                      If the number of values found in this parameter are
271      *                      less than the number of fields in the
272      *                      <code>orderby</code> parameter, all fields that
273      *                      don't have a corresponding direction value are
274      *                      sorted according to the last specified direction
275      *                      value.
276      * @return              a list of nodes belonging to this node manager
277      */
278     public NodeList getList(String   constraints, String   orderby, String   directions);
279 
280 
281 
282     /**
283      * Creates a query for this NodeNanager. The nodemanager is added as a step, and also all (non
284      * byte array) fields are added.  The query can be used  by getList of Cloud.
285      *
286      * You can not add steps to this NodeQuery.
287      * @return query for this NodeNanager
288      *
289      * @since MMBase-1.7
290      * @see #getList(NodeQuery)
291      * @see Cloud#createNodeQuery
292      */
293     public NodeQuery createQuery();
294 
295     /**
296      * Executes a query and returns the result as nodes of this NodeManager (or of extensions)
297      * @param query query to execute
298      * @return list of nodes
299      *
300      * @since MMBase-1.7
301      */
302     public NodeList getList(NodeQuery query);
303 
304 
305     /**
306      * Retrieve info from a node manager based on a command string.
307      * Similar to the $MOD command in SCAN.
308      * @param command the info to obtain, i.e. "USER-OS".
309      * @return info from a node manager
310      */
311     public String   getInfo(String   command);
312 
313     /**
314      * Retrieve info from a node manager based on a command string
315      * Similar to the $MOD command in SCAN.
316      * @param command the info to obtain, i.e. "USER-OS".
317      * @param req the Request item to use for obtaining user information. For backward compatibility.
318      * @param resp the Response item to use for redirecting users. For backward compatibility.
319      * @return info from a node manager
320      */
321     public String   getInfo(String   command, ServletRequest   req,  ServletResponse   resp);
322 
323     /**
324      * Retrieve all relation managers that can be used to create relations for objects of this nodemanager.
325      * @return the relation manager list
326      * @since MMBase-1.6
327      */
328     public RelationManagerList getAllowedRelations();
329 
330     /**
331      * Retrieve all relation managers that can be used to create relations for objects from this nodemanager,
332      * to the specified manager, using the specified role and direction.
333      * @param nodeManager the name of the nodemanger with which to make a relation, can be null
334      * @param role the role with which to make a relation, can be null
335      * @param direction the search direction ("source", "destination", "both"), can be null
336      * @return the relation manager list
337      * @since MMBase-1.6
338      */
339     public RelationManagerList getAllowedRelations(String   nodeManager, String   role, String   direction);
340 
341     /**
342      * Retrieve all relation managers that can be used to create relations for objects from this nodemanager,
343      * to the specified manager, using the specified role and direction.
344      * @param nodeManager the nodemanger with which to make a relation, can be null
345      * @param role the role with which to make a relation, can be null
346      * @param direction the search direction ("source", "destination", "both"), can be null
347      * @return the relation manager list
348      * @since MMBase-1.6
349      */
350     public RelationManagerList getAllowedRelations(NodeManager nodeManager, String   role, String   direction);
351 
352     /**
353      * Retrieve info (as a list of virtual nodes) from a node manager based on a command string.
354      * Similar to the LIST command in SCAN.
355      * The values retrieved are represented as fields of a virtual node, named following the fieldnames listed in the fields paramaters..
356      * @param command the info to obtain, i.e. "USER-OS".
357      * @param parameters a hashtable containing the named parameters of the list.
358      * @return info from a node manager (as a list of virtual nodes)
359      */
360     public NodeList getList(String   command, Map   parameters);
361 
362     /**
363      * Retrieve info from a node manager based on a command string
364      * Similar to the LIST command in SCAN.
365      * The values retrieved are represented as fields of a virtual node, named following the fieldnames listed in the fields paramaters..
366      * @param command the info to obtain, i.e. "USER-OS".
367      * @param parameters a hashtable containing the named parameters of the list.
368      * @param req the Request item to use for obtaining user information. For backward compatibility.
369      * @param resp the Response item to use for redirecting users. For backward compatibility.
370      * @return info from a node manager (as a list of virtual nodes)
371      */
372     public NodeList getList(String   command, Map   parameters, ServletRequest   req, ServletResponse   resp);
373 
374     /**
375      * Check if the current user may create a new node of this type.
376      *
377      * @return  Check if the current user may create a new node of this type.
378      */
379     public boolean mayCreateNode();
380 
381     /**
382      * Returns a new, empty field list for this nodemanager
383      *
384      * @return  The empty list
385      * @since   MMBase-1.8
386      */
387     public FieldList createFieldList();
388 
389     /**
390      * Returns a new, empty node list for this nodemanager
391      *
392      * @return  The empty list
393      * @since   MMBase-1.8
394      */
395     public NodeList createNodeList();
396 
397     /**
398      * Returns a new, empty relation list for this nodemanager
399      *
400      * @return  The empty list
401      * @since   MMBase-1.8
402      */
403     public RelationList createRelationList();
404 
405 }
406
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags