View Javadoc

1   /*
2    * ModeShape (http://www.modeshape.org)
3    * See the COPYRIGHT.txt file distributed with this work for information
4    * regarding copyright ownership.  Some portions may be licensed
5    * to Red Hat, Inc. under one or more contributor license agreements.
6    * See the AUTHORS.txt file in the distribution for a full listing of 
7    * individual contributors.
8    *
9    * ModeShape is free software. Unless otherwise indicated, all code in ModeShape
10   * is licensed to you under the terms of the GNU Lesser General Public License as
11   * published by the Free Software Foundation; either version 2.1 of
12   * the License, or (at your option) any later version.
13   * 
14   * ModeShape is distributed in the hope that it will be useful,
15   * but WITHOUT ANY WARRANTY; without even the implied warranty of
16   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17   * Lesser General Public License for more details.
18   *
19   * You should have received a copy of the GNU Lesser General Public
20   * License along with this software; if not, write to the Free
21   * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
22   * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
23   */
24  package org.modeshape.sequencer.ddl;
25  
26  import org.modeshape.common.text.ParsingException;
27  import org.modeshape.sequencer.ddl.node.AstNode;
28  
29  /**
30   * Interface for parsing DDL files.
31   */
32  public interface DdlParser {
33  
34      /**
35       * Determine this parser's score for the given DDL string. This method is called to determine how well this parser handles the
36       * supplied DDL, and is often called before the {@link #parse(String, AstNode, Object)} method.
37       * 
38       * @param ddl the input string to parse; may not be null
39       * @param fileName the name of the DDL content, which may be used to improve the score; may be null if not known
40       * @param scorer the scorer that should be used to record the score; may not be null
41       * @return an object that will be passed to the {@link #parse(String, AstNode,Object)} method
42       * @throws ParsingException if there is an error parsing the supplied DDL content
43       */
44      public Object score( String ddl,
45                           String fileName,
46                           DdlParserScorer scorer ) throws ParsingException;
47  
48      /**
49       * Parses a DDL string, adding child {@link AstNode}s and properties to the supplied root. This method instantiates the
50       * tokenizer, calls a method to allow subclasses to register keywords and statement start phrases with the tokenizer and
51       * finally performs the tokenizing (i.e. tokens.start()) before calling the actual parse method.
52       * 
53       * @param ddl the input string to parse; may not be null
54       * @param rootNode the top level {@link AstNode}; may not be null
55       * @param scoreReturnObject the object returned from {@link #score(String, String, DdlParserScorer)} for the same DDL content;
56       *        may be null if the {@link #score(String, String, DdlParserScorer)} method was not called
57       * @throws ParsingException if there is an error parsing the supplied DDL content
58       */
59      public void parse( String ddl,
60                         AstNode rootNode,
61                         Object scoreReturnObject ) throws ParsingException;
62  
63      /**
64       * Get the identifier for this parser.
65       * 
66       * @return the parser's identifier; never null
67       */
68      public String getId();
69  
70  }