View Javadoc

1   /*
2    * $Id: IOWLAbstractSyntaxTree.java,v 1.7 2005/05/31 23:28:07 jlerner Exp $
3    *
4    * Copyright (c) 1999-2004, BBN Technologies, LLC.
5    * All rights reserved.
6    * http://www.daml.org/legal/opensource/bbn_license.html
7    */
8   
9   package com.bbn.swede.core.dom;
10  
11  import java.util.List;
12  
13  import com.bbn.swede.core.IOWLDocument;
14  import com.hp.hpl.jena.ontology.OntModel;
15  import com.hp.hpl.jena.rdf.model.Resource;
16  import com.hp.hpl.jena.rdf.model.Statement;
17  
18  /***
19   * Interface for OWL abstract syntax trees.  This interface provides convenience
20   * methods for interacting with the document as a whole and retrieving
21   * specific nodes.
22   * @author jlerner
23   */
24  public interface IOWLAbstractSyntaxTree
25  {
26     /***
27      * Returns the root node of the OAST.
28      * @return The root node.
29      */
30     DocumentRoot getRoot();
31  
32     /***
33      * Returns a Jena model representing the OAST.  If the model does not already
34      * exist, it will be built automatically. 
35      * @return The Jena model for this OAST
36      */
37     OntModel getJenaModel();
38  
39     /***
40      * Finds the lowest-level node in the tree that contains a given offset.
41      * @param offset The offset to find
42      * @return The node containing the offset or the document root if no
43      *         containing node is found
44      */
45     OASTNode getNode(int offset);
46  
47     /***
48      * Finds a node that represents a specific Jena statement.
49      * @param stmt The statement to find
50      * @return The node that corresponds to the statement, or null if no such
51      *         node is found.
52      */
53     OASTNode getNode(Statement stmt);
54  
55     /***
56      * Finds a node that represents a specific Jena resource.
57      * @param res The resource to find
58      * @return The node that corresponds to the resource, or null if no such
59      *         node is found
60      */
61     OASTNode getNode(Resource res);
62  
63     /***
64      * Finds a node that represents a specific URI.
65      * @param sUri The URI to find
66      * @return The node that corresponds to the URI, or null if no such node is
67      *         found
68      */
69     OASTNode getNode(String sUri);
70  
71     /***
72      * Finds the IOWLDocument corresponding to a namespace URI.
73      * @param uri URI of the namespace to locate
74      * @return The IOWLDocument for the specified URI, or null if the project
75      *         does not contain a document with the specified base URI
76      */
77     IOWLDocument getNamespace(String uri);
78  
79     /***
80      * Returns the base URI for the document represented by this OAST.
81      * @return The document's base URI
82      */
83     String getBaseURI();
84  
85     /***
86      * Lists all namespace URIs in the current project.
87      * @return A java.util.List of all known document URIs
88      */
89     List listNamespaces();
90     
91     /***
92      * Registers a new OASTChangeListener.  Listeners receive notifications
93      * before and after nodes are added or removed from the OAST.
94      * @param ocl The listener to register
95      */
96     void addOASTChangeListener(IOASTChangeListener ocl);
97  
98     /***
99      * Unregisters an OASTChangeListener.  It will no longer receive
100     * OASTAboutToChange and OASTChange notifications.
101     * @param ocl The listener to unregister.  If ocl is not registered as an
102     *            OASTChangeListener, this method does nothing.
103     */
104    void removeOASTChangeListener(IOASTChangeListener ocl);
105    
106    /***
107     * Runs the given action as an atomic OWL abstract syntax tree operation.
108     * All OAST modifications that occur within the runnable will be combined
109     * into a single event so that listeners are only notified once.
110     * @param action The action to perform.
111     * @throws OASTException if this OAST is read-only and <code>action</code>
112     *                       attempts to modify it
113     */
114    void run(IOASTRunnable action) throws OASTException;
115 
116    /***
117     * Indicates whether the tree's Jena model has been built.
118     * @return <code>true</code> if the tree is maintaining a Jena model,
119     *         <code>false</code> if it has not been built yet.
120     */
121    boolean hasModel();
122 
123    /***
124     * Indicates whether the tree represents a read-only document.  A read-only
125     * OAST cannot be modified with the OAST API.  An {@link OASTException} will
126     * be thrown by any API method that is called on a read-only OAST.
127     * @return <code>true</code> if the OAST is read-only, <code>false</code> if
128     *         it can be modified.
129     */
130    boolean isReadOnly();
131 }