View Javadoc

1   // Copyright 2006-2007, by the California Institute of Technology.
2   // ALL RIGHTS RESERVED. United States Government Sponsorship acknowledged.
3   // Any commercial use must be negotiated with the Office of Technology Transfer
4   // at the California Institute of Technology.
5   //
6   // This software is subject to U. S. export control laws and regulations
7   // (22 C.F.R. 120-130 and 15 C.F.R. 730-774). To the extent that the software
8   // is subject to U.S. export control laws and regulations, the recipient has
9   // the responsibility to obtain export licenses or other export authority as
10  // may be required before exporting such information to foreign countries or
11  // providing access to foreign nationals.
12  //
13  // $Id: Dictionary.java 2628 2007-04-26 16:04:43Z pramirez $ 
14  //
15  
16  package gov.nasa.pds.tools.dict;
17  
18  import gov.nasa.pds.tools.label.validate.Status;
19  
20  import java.util.ArrayList;
21  import java.util.Collection;
22  import java.util.HashMap;
23  import java.util.Iterator;
24  import java.util.List;
25  import java.util.Map;
26  
27  /***
28   * This class represents a PDS data dictionary. 
29   * @author pramirez
30   * @version $Revision: 2628 $
31   * 
32   */
33  public class Dictionary implements Status {
34      private Map definitions;
35      private String information;
36      private Map units;
37      private List unitList;
38      private String status;
39      
40      public Dictionary() {
41          definitions = new HashMap();
42          units = new HashMap();
43          unitList = new ArrayList();
44          information = "";
45          status = Status.UNKNOWN;
46      }
47      
48      /***
49       * Merges dictionary without overwriting
50       * @param dictionary to be merged
51       */
52      public void merge(Dictionary dictionary) {
53          merge(dictionary, false);
54      }
55      
56      /***
57       * Merges the definitions in the dictionaries
58       * @param dictionary to be merged
59       * @param overwrite flag
60       */
61      public void merge(Dictionary dictionary, boolean overwrite) {
62          if (overwrite)
63              definitions.putAll(dictionary.definitions);
64          else {
65              Map d = new HashMap(dictionary.definitions);
66              d.putAll(definitions);
67              definitions = d;
68          }
69      }
70      
71      /***
72       * Tests to see whether or not a definition exists
73       * @param identifier of the definition
74       * @return flag indicating existence
75       */
76      public boolean containsDefinition(String identifier) {
77          return definitions.containsKey(identifier); 
78      }
79      
80      /***
81       * Tests to see whether or not an object is defined
82       * @param identifier of the object
83       * @return flag indicating existence
84       */
85      public boolean containsObjectDefinition(String identifier) {
86          Definition definition = (Definition) definitions.get(identifier);
87          if (definition != null && definition instanceof ObjectDefinition)
88              return true;
89          return false;
90      }
91      
92      /***
93       * Tests to see whether or not a group is defined 
94       * @param identifier of the the group
95       * @return flag indicating existence
96       */
97      public boolean containsGroupDefinition(String identifier) {
98          Definition definition = (Definition) definitions.get(identifier);
99          if (definition != null && definition instanceof GroupDefinition)
100             return true;
101         return false;
102     }
103     
104     /***
105      * Tests to see whether or not an element is defined
106      * @param identifier of the element
107      * @return flag indicating existence
108      */
109     public boolean containsElementDefinition(String identifier) {
110         return containsElementDefinition(null, identifier);
111     }
112     
113     public boolean containsElementDefinition(String objectContext, String identifier) {
114         Definition definition = null;
115         
116         if (objectContext != null) {
117             definition = (Definition) definitions.get(objectContext + "." + identifier);
118             if (definition != null && definition instanceof ElementDefinition)
119                 return true;
120         }
121         
122         definition = (Definition) definitions.get(identifier);
123         if (definition != null && definition instanceof ElementDefinition)
124             return true;
125         
126         return false;
127     }
128     
129     /***
130      * Retrieves the definition from the dictionary or null if not found
131      * @param identifier of the definition
132      * @return the definition
133      */
134     public Definition getDefinition(String identifier) {
135         return (Definition) definitions.get(identifier);
136     }
137     
138     /***
139      * Retrieves the object definition from the dictionary or null if not found
140      * @param identifier of the definition
141      * @return the object definition
142      */
143     public ObjectDefinition getObjectDefinition(String identifier) {
144         Definition definition = (Definition) definitions.get(identifier);
145         if (definition != null && definition instanceof ObjectDefinition)
146             return (ObjectDefinition) definition;
147         return null;
148     }
149     
150     /***
151      * Retrieves the group definition from the dictionary or null if not found
152      * @param identifier of the definition
153      * @return the group definition
154      */
155     public GroupDefinition getGroupDefinition(String identifier) {
156         Definition definition = (Definition) definitions.get(identifier);
157         if (definition != null && definition instanceof GroupDefinition)
158             return (GroupDefinition) definition;
159         return null;
160     }
161     
162     /***
163      * Retrieves the element definition from the dictionary or null if not found.
164      * @param identifier of the definition
165      * @return the element definition
166      */
167     public ElementDefinition getElementDefinition(String identifier) {
168         return getElementDefinition(null, identifier);
169     }
170     
171     public ElementDefinition getElementDefinition(String objectContext, String identifier) {
172         Definition definition = null;
173         
174         if (objectContext != null) {
175             definition = (Definition) definitions.get(objectContext + "." + identifier);
176             if (definition != null && definition instanceof ElementDefinition)
177                 return (ElementDefinition) definition;
178         }
179         
180         definition = (Definition) definitions.get(identifier);
181         if (definition != null && definition instanceof ElementDefinition)
182             return (ElementDefinition) definition;
183         
184         return null;
185     }
186     
187     /***
188      * Adds a definition to this dictionary to. Overwrites any existing definition.
189      * @param definition to be added to the dictionary
190      */
191     public void addDefinition(Definition definition) {
192         addDefinition(definition, true);
193     }
194     
195     /***
196      * Adds a defintion to this dictionary. The flag indicates whether a definition 
197      * should be overwriten.
198      * @param definition to be added to the dictionary
199      * @param overwrite indicates if definition should be overwriten
200      */
201     public void addDefinition(Definition definition, boolean overwrite) {
202         if (overwrite || (!overwrite && !definitions.containsKey(definition.getIdentifier()))) {
203             definitions.put(definition.getIdentifier(), definition);
204             if (definition instanceof ElementDefinition) {
205                 ElementDefinition elementDefinition = (ElementDefinition) definition;
206                 elementDefinition.setUnitList(unitList);
207             }
208             for (Iterator i = definition.getAliases().iterator(); i.hasNext();) {
209                 String alias = (String) i.next();
210                 definitions.put(alias, definition);
211             }
212         }
213     }
214     
215     /***
216      * Sets the description information for a dictionary. This is often captured informally in 
217      * comments at the top of a dictionary file.
218      * @param information
219      */
220     public void setInformation(String information) {
221         this.information = information;
222     }
223     
224     /***
225      * Return the dictionary's descriptive information.
226      * @return the information
227      */
228     public String getInformation() {
229         return information;
230     }
231     
232     /***
233      * Adds a list of defintions to this dictionary. The flag indicates whether the 
234      * definitions should be overwriten.
235      * @param definitions to be added to the dictionary
236      * @param overwrite
237      */
238     public void addDefinitions(Collection definitions, boolean overwrite) {
239         for (Iterator i = definitions.iterator(); i.hasNext();) {
240             Definition d = (Definition) i.next();
241             addDefinition(d, overwrite);
242         }
243     }
244     
245     /***
246      * Adds a list of defintions to this dictionary. By default definitions will be 
247      * overwritten.
248      * @param definitions to be added to the dictionary
249      */
250     public void addDefinitions(Collection definitions) {
251         addDefinitions(definitions, true);
252     }
253     
254     /***
255      * Retrieves the class definition for an object with the given identifier. 
256      * This method will search the dictionary for an ObjectDefinition whose 
257      * identifier is the greatest length and matches the end of the given identifier
258      * @param identifier to lookup up class of
259      * @return {@link ObjectDefinition} of class that will constrain object with 
260      * given identifier. Returns null if not found.
261      */
262     public ObjectDefinition findObjectClassDefinition(String identifier) {
263         ObjectDefinition definition = null;
264         String className = identifier;
265         boolean done = false;
266         
267         while (definition == null && !done) {
268             if (containsObjectDefinition(className))
269                 definition = (ObjectDefinition) definitions.get(className);
270             else {
271                 if (className.indexOf("_") == -1 || className.indexOf("_") == className.length()-1)
272                     done = true;
273                 else
274                     className = className.substring(className.indexOf("_") + 1);
275             }      
276         }
277         
278         return definition;
279     }
280     
281     /***
282      * Retrieves the class definition for a group with the given identifier. 
283      * This method will search the dictionary for a GroupDefinition whose 
284      * identifier is the greatest length and matches the end of the given identifier
285      * @param identifier to lookup up class of
286      * @return {@link GroupDefinition} of class that will constrain object with 
287      * given identifier. Returns null if not found.
288      */
289     public GroupDefinition findGroupClassDefinition(String identifier) {
290         GroupDefinition definition = null;
291         String className = identifier;
292         boolean done = false;
293         
294         while (definition == null && !done) {
295             if (containsGroupDefinition(className))
296                 definition = (GroupDefinition) definitions.get(className);
297             else {
298                 if (className.indexOf("_") == -1 || className.indexOf("_") == className.length()-1)
299                     done = true;
300                 else
301                     className = className.substring(className.indexOf("_") + 1);
302             }      
303         }
304         
305         return definition;
306     }
307     
308     /***
309      * Retrieves the map of definitions
310      * @return map of definitions.
311      */
312     protected Map getDefinitions() {
313         return definitions;
314     }
315     
316     /***
317      * Retrieves map of valid units.
318      * @return map of UNIT_ID to list of valid units
319      */
320     public Map getUnits() {
321         return units;
322     }
323     
324     /***
325      * Sets the valid units for use when performing validation against this dictionary
326      * @param units mapped set of units of the form UNIT_ID to units list
327      *              (A) -> ('A', 'AMPERE')
328      */
329     public void setUnits(Map units) {
330         this.units = units;
331         unitList = new ArrayList();
332         for (Iterator i = units.values().iterator(); i.hasNext(); ) {
333             unitList.addAll((List) i.next());
334         }
335     }
336     
337     public String getStatus() {
338         return status;
339     }
340     
341     public void setStatus(String status) {
342         //Make sure we aren't trying to set status to unknown
343         if (!UNKNOWN.equals(status)) {
344            //Set to pass if unknown 
345            //Set to fail if that is the status being passed in
346            //Drop everything else
347            if (PASS.equals(status) && UNKNOWN.equals(this.status))
348               this.status = PASS;
349            else if (FAIL.equals(status))
350               this.status = FAIL;
351         }
352     }
353 }