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.Map;
014: import java.util.Locale;
015: import javax.servlet.ServletResponse;
016: import javax.servlet.ServletRequest;
017:
018: /**
019: * This interface represents a node's type information object - what used to be the 'builder'.
020: * It contains all the field and attribuut information, as well as GUI data for editors and
021: * some information on deribed and deriving types. It also contains some maintenance code - code
022: * to create new nodes, en code to query objects belonging to the same manager.
023: * Since node types are normally maintained through use of config files (and not in the database),
024: * as wel as for security issues, the data of a nodetype cannot be changed except through
025: * the use of an administration module (which is why we do not include setXXX methods here).
026: * @author Rob Vermeulen
027: * @author Pierre van Rooden
028: * @version $Id: NodeManager.java,v 1.43 2007/12/18 12:44:57 michiel Exp $
029: */
030: public interface NodeManager extends Node {
031:
032: /**
033: * A constant for use with {@link #getFields(int)}, meaning `all fields, even those which are
034: * not stored.
035: */
036: public final static int ORDER_NONE = -1;
037: /**
038: * A constant for use with {@link #getFields(int)}, meaning `all fields, in storage order (so
039: * which are in storage'.
040: */
041: public final static int ORDER_CREATE = 0;
042: /**
043: * A constant for use with {@link #getFields(int)}, meaning all fields which a user may want to
044: * fill when creating or editing this node. That are normally all nodes without the `automatic'
045: * ones like `number' and `otype'.
046: */
047: public final static int ORDER_EDIT = 1;
048: /**
049: * A constant for use with {@link #getFields(int)}. When presenting a Node in some list overview
050: * then less essential fields can be left out, to get a more concise presentation of the node.
051: */
052: public final static int ORDER_LIST = 2;
053: /**
054: * 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
055: * out among the `search' fields.
056: */
057: public final static int ORDER_SEARCH = 3;
058:
059: public final static int GUI_SINGULAR = 1;
060: public final static int GUI_PLURAL = 2;
061:
062: /**
063: * Creates a new node. The returned node will not be visible in the cloud
064: * until the commit() method is called on this node. Until then it will have
065: * a temporary node number.
066: *
067: * @return the new <code>Node</code>
068: */
069: public Node createNode();
070:
071: /**
072: * Returns the cloud to which this manager belongs.
073: *
074: * @return the cloud to which this manager belongs
075: */
076: public Cloud getCloud();
077:
078: /**
079: * Retrieve the parent of this NodeManager (the Nodemanager that this nodemanager extends from)
080: * @return the NodeManager's parent
081: * @throws NotFoundException if no parent exists (i.e. this nodeManager is "object")
082: */
083: public NodeManager getParent() throws NotFoundException;
084:
085: /**
086: * Retrieve a list of descendant nodemanagers (the nodemanagers that - possibly indirectly - extend from this nodemanager)
087: * @return a list of NodeManagers
088: * @since MMBase-1.7
089: */
090: public NodeManagerList getDescendants();
091:
092: /**
093: * Returns the name of this node manager. This name is a unique name.
094: *
095: * @return the name of this node manager.
096: */
097: public String getName();
098:
099: /**
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<String, String> 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,
279: String directions);
280:
281: /**
282: * Creates a query for this NodeNanager. The nodemanager is added as a step, and also all (non
283: * byte array) fields are added. The query can be used by getList of Cloud.
284: *
285: * You can not add steps to this NodeQuery.
286: * @return query for this NodeNanager
287: *
288: * @since MMBase-1.7
289: * @see #getList(NodeQuery)
290: * @see Cloud#createNodeQuery
291: */
292: public NodeQuery createQuery();
293:
294: /**
295: * Executes a query and returns the result as nodes of this NodeManager (or of extensions)
296: * @param query query to execute
297: * @return list of nodes
298: *
299: * @since MMBase-1.7
300: */
301: public NodeList getList(NodeQuery query);
302:
303: /**
304: * Retrieve info from a node manager based on a command string.
305: * Similar to the $MOD command in SCAN.
306: * @param command the info to obtain, i.e. "USER-OS".
307: * @return info from a node manager
308: */
309: public String getInfo(String command);
310:
311: /**
312: * Retrieve info from a node manager based on a command string
313: * Similar to the $MOD command in SCAN.
314: * @param command the info to obtain, i.e. "USER-OS".
315: * @param req the Request item to use for obtaining user information. For backward compatibility.
316: * @param resp the Response item to use for redirecting users. For backward compatibility.
317: * @return info from a node manager
318: */
319: public String getInfo(String command, ServletRequest req,
320: ServletResponse resp);
321:
322: /**
323: * Retrieve all relation managers that can be used to create relations for objects of this nodemanager.
324: * @return the relation manager list
325: * @since MMBase-1.6
326: */
327: public RelationManagerList getAllowedRelations();
328:
329: /**
330: * Retrieve all relation managers that can be used to create relations for objects from this nodemanager,
331: * to the specified manager, using the specified role and direction.
332: * @param nodeManager the name of the nodemanger with which to make a relation, can be null
333: * @param role the role with which to make a relation, can be null
334: * @param direction the search direction ("source", "destination", "both"), can be null
335: * @return the relation manager list
336: * @since MMBase-1.6
337: */
338: public RelationManagerList getAllowedRelations(String nodeManager,
339: 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(
351: NodeManager nodeManager, String role, String direction);
352:
353: /**
354: * Retrieve info (as a list of virtual nodes) from a node manager based on a command string.
355: * Similar to the LIST command in SCAN.
356: * The values retrieved are represented as fields of a virtual node, named following the fieldnames listed in the fields paramaters..
357: * @param command the info to obtain, i.e. "USER-OS".
358: * @param parameters a hashtable containing the named parameters of the list.
359: * @return info from a node manager (as a list of virtual nodes)
360: */
361: public NodeList getList(String command, Map parameters);
362:
363: /**
364: * Retrieve info from a node manager based on a command string
365: * Similar to the LIST command in SCAN.
366: * The values retrieved are represented as fields of a virtual node, named following the fieldnames listed in the fields paramaters..
367: * @param command the info to obtain, i.e. "USER-OS".
368: * @param parameters a hashtable containing the named parameters of the list.
369: * @param req the Request item to use for obtaining user information. For backward compatibility.
370: * @param resp the Response item to use for redirecting users. For backward compatibility.
371: * @return info from a node manager (as a list of virtual nodes)
372: */
373: public NodeList getList(String command, Map parameters,
374: ServletRequest req, ServletResponse resp);
375:
376: /**
377: * Check if the current user may create a new node of this type.
378: *
379: * @return Check if the current user may create a new node of this type.
380: */
381: public boolean mayCreateNode();
382:
383: /**
384: * Returns a new, empty field list for this nodemanager
385: *
386: * @return The empty list
387: * @since MMBase-1.8
388: */
389: public FieldList createFieldList();
390:
391: /**
392: * Returns a new, empty node list for this nodemanager
393: *
394: * @return The empty list
395: * @since MMBase-1.8
396: */
397: public NodeList createNodeList();
398:
399: /**
400: * Returns a new, empty relation list for this nodemanager
401: *
402: * @return The empty list
403: * @since MMBase-1.8
404: */
405: public RelationList createRelationList();
406:
407: }
|