KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > sapia > regis > Query


1 package org.sapia.regis;
2
3 import java.io.Serializable JavaDoc;
4 import java.util.Collections JavaDoc;
5 import java.util.HashMap JavaDoc;
6 import java.util.Map JavaDoc;
7
8 /**
9  * An instance of this class is used to acquire a given collection of nodes,
10  * under a given node instance.
11  * <p>
12  * In other words, it is meant to filter the <code>Node</code>s that a
13  * given node holds, based on the name/value of the filtered nodes.
14  * <p>
15  * For example, imagine that we have a node holding child nodes that
16  * correspond to user accounts (username/password). The username and password
17  * would be kept as properties, in each account node.
18  * <p>
19  * To acquire the node corresponding to a given account, we could query
20  * the node holding each the account nodes:
21  * <pre>
22  * Collection result = accounts.getNodes(Query.create().addCrit("username", "jsmith"));
23  * if(result.size() == 0) {
24  * throw new IllegalArgumentException("Invalid username");
25  * }
26  * else if(result.size() > 1){
27  * throw new IllegalStateException("System corrupted; more than one account with same username");
28  * }
29  * else{
30  * Node account = (Node)result.iterator().next();
31  * if(account.getProperty("passwd").asString().equals(givenPasswd)){
32  * ...
33  * }
34  * else{
35  * throw new AuthenticationException("Invalid login; wrong username and/or password");
36  * }
37  * }
38  * </pre>
39  * <p>
40  * Now in the example above, the queried node is the one that is expected to contain the
41  * nodes that are to be filtered. But imagine that the parent node is under the "system/accounts"
42  * path (under the root). Using the root node of the registry, we would retrieve our desired
43  * account as follows:
44  * <pre>
45  * Collection result = root.getNodes(Query.create("system/accounts")
46  * .addCrit("username", "jsmith"));
47  * </pre>
48  *
49  * @see org.sapia.regis.Node#getNodes(Query)
50  *
51  * @author yduchesne
52  *
53  */

54 public class Query implements Serializable JavaDoc{
55
56   static final long serialVersionUID = 1L;
57   
58   private Path _path;
59   private Map JavaDoc _criteria;
60   
61   /**
62    * @param path a <code>Path</code> corresponding to a <code>Node</code> whose
63    * children nodes should be returned, provided they match this instance's criteria.
64    * @return
65    */

66   public Query setPath(Path path){
67     _path = path;
68     return this;
69   }
70   
71   /**
72    * @see #setPath(Path)
73    * @see Path#parse(String)
74    */

75   public Query setPath(String JavaDoc path){
76     _path = Path.parse(path);
77     return this;
78   }
79   
80   /**
81    * @return this instance's <code>Path</code>, or null if this instance
82    * has no path.
83    */

84   public Path getPath(){
85     return _path;
86   }
87   
88   /**
89    * Adds a criterion, corresponding to the expected name/value of a property. This
90    * method can be called in chained invocations:
91    * <pre>
92    * query.addCrit("prop1", "value1").addCrit("prop2", "value2");
93    * </pre>
94    *
95    * @param name a property name.
96    * @param value a property value.
97    * @return this instance.
98    */

99   public Query addCrit(String JavaDoc name, String JavaDoc value){
100     crit().put(name, value);
101     return this;
102   }
103   
104   /**
105    * @return the <code>Map</code> of criteria held by this instance.
106    */

107   public Map JavaDoc getCriteria(){
108     return _criteria == null ? Collections.EMPTY_MAP : _criteria;
109   }
110   
111   /**
112    * @return a new instance of this class.
113    */

114   public static Query create(){
115     return new Query();
116   }
117   
118   /**
119    * @see #create(Path)
120    */

121   public static Query create(String JavaDoc path){
122     return create(Path.parse(path));
123   }
124   
125   /**
126    * @param path a <code>Path</code>.
127    * @return anew instance of this class, bound to the given path.
128    */

129   public static Query create(Path path){
130     Query q = new Query();
131     q.setPath(path);
132     return q;
133   }
134   
135   private Map JavaDoc crit(){
136     if(_criteria == null) _criteria = new HashMap JavaDoc();
137     return _criteria;
138   }
139 }
140
Popular Tags