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: LabelParser.java 2647 2007-04-27 14:59:58Z pramirez $ 
14  //
15  
16  package gov.nasa.pds.tools.label.parser;
17  
18  import java.net.URL;
19  
20  import gov.nasa.pds.tools.dict.Dictionary;
21  import gov.nasa.pds.tools.label.Label;
22  import gov.nasa.pds.tools.label.validate.LabelValidator;
23  
24  import java.util.Properties;
25  import java.io.IOException;
26  
27  /***
28   * @author pramirez
29   * @version $Revision: 2647 $
30   * 
31   */
32  public interface LabelParser {
33      
34      /***
35       * Parses the given file
36       * @param file File to 
37       * @return {@link Label} representation of the file
38       * @throws ParseException - If any syntatic errors are encountered.  
39       *                          All errors will be written to the Logger.
40       */
41      public Label parse(URL file) throws ParseException, IOException;
42      
43      /***
44       * Parses the given file and validates against the dictionary.
45       * @param file 
46       * @param dictionary
47       * @return {@link Label} representation of the file
48       */
49      public Label parse(URL file, Dictionary dictionary) throws ParseException, IOException;
50      
51      /***
52       * Parses the given file, validates against dictionary, and may perform dataObjectValidation
53       * @param file
54       * @param dictionary
55       * @param dataObjectValidation
56       * @return {@link Label} representation of the file
57       */
58      public Label parse(URL file, Dictionary dictionary, boolean dataObjectValidation) throws ParseException, IOException;
59      
60      /***
61       * Parses the given partial label.
62       * @param file
63       * @return {@link Label} representation of the file
64       * @throws ParseException
65       * @throws IOException
66       */
67      public Label parsePartial(URL file) throws ParseException, IOException;
68      
69      /***
70       * Parses the given partial label.
71       * @param context
72       * @param file
73       * @return {@link Label} representation of the file
74       * @throws ParseException
75       * @throws IOException
76       */
77      public Label parsePartial(String context, URL file) throws ParseException, IOException;
78      
79      /***
80       * Parses the given partial label and validates against the dictionary.
81       * @param file
82       * @param dictionary
83       * @return {@link Label} representation of the file
84       * @throws ParseException
85       * @throws IOException
86       */
87      public Label parsePartial(URL file, Dictionary dictionary) throws ParseException, IOException;
88      
89      /***
90       * Parses the given partial label, validates against dictionary, and may perform dataObjectValidation
91       * @param file
92       * @param dictionary
93       * @param dataObjectValidation
94       * @return {@link Label} representation of the file
95       * @throws ParseException
96       * @throws IOException
97       */
98      public Label parsePartial(URL file, Dictionary dictionary, boolean dataObjectValidation) throws ParseException, IOException;
99      
100     /***
101      * Passes properties to the parser. 
102      * @param properties Set of properties.
103      */
104     public void setProperties(Properties properties);
105     
106     /***
107      * Retrieves parser properties.
108      * @return parser properties
109      */
110     public Properties getProperties();
111     
112     /***
113      * Returns the version of the PDS specification that this parser is compliant with.
114      * @return The PDS version string
115      */
116     public String getPDSVersion();
117     
118     /***
119      * Returns the version of ODL that this parser is compliant with.
120      * @return The ODL version string
121      */
122     public String getODLVersion();
123     
124     /***
125      * Adds an URL where references will be searched for when found in a label.
126      * @param includePath points to a directory that will be searched.
127      */
128     public void addIncludePath(URL includePath);
129     
130     /***
131      * Adds a {@link LabelValidator} that will perform some extravalidation.
132      * @param validator which will be run as a step in the validation pipeline
133      */
134     public void addValidator(LabelValidator validator);
135 }