001: /*
002: (c) Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
003: [See end of file]
004: $Id: GraphMaker.java,v 1.19 2008/01/02 12:06:55 andy_seaborne Exp $
005: */
006:
007: package com.hp.hpl.jena.graph;
008:
009: import com.hp.hpl.jena.shared.*;
010: import com.hp.hpl.jena.util.iterator.*;
011:
012: /**
013: A factory for providing instances of named graphs with appropriate storage models.
014: It represents a directory, or a database, or a mapping: names map to graphs for the
015: lifetime of the GraphMaker. Names can be "arbitrary" character sequences.
016: <p>
017: A GraphMaker has a reification style which is shared by all the graphs it creates.
018: */
019:
020: public interface GraphMaker {
021: /**
022: Answer the reification style of all the graphs that this GraphMaker constructs.
023: @return the reification style given to all created graphs
024: */
025: public ReificationStyle getReificationStyle();
026:
027: /**
028: Answer the default graph of this GraphMaker. The same graph is returned on
029: each call. It may only be constructed on the first call of getGraph(), or at any
030: previous time.
031:
032: @return the same default graph each time
033: */
034: public Graph getGraph();
035:
036: /**
037: Answer the default graph of this GraphMaker, if it has one. If not,
038: throw an exception.
039: */
040: public Graph openGraph();
041:
042: /**
043: Answer a graph who's name isn't interesting. Each call delivers a different graph.
044: The GraphMaker may reserve a bunch of names for this purpose, of the form
045: "anon_<digits>", if it cannot support truly anonymous graphs.
046:
047: @return a fresh anonymous graph
048: */
049: public Graph createGraph();
050:
051: /**
052: Create a new graph associated with the given name. If there is no such
053: association, create one and return it. If one exists but <code>strict</code>
054: is false, return the associated graph. Otherwise throw an AlreadyExistsException.
055:
056: @param name the name to give to the new graph
057: @param strict true to cause existing bindings to throw an exception
058: @exception AlreadyExistsException if that name is already bound.
059: */
060: public Graph createGraph(String name, boolean strict);
061:
062: /**
063: Create a graph that does not already exist - equivalent to
064: <br><code>createGraph( name, false )</code>.
065: */
066: public Graph createGraph(String name);
067:
068: /**
069: Find an existing graph that this factory knows about under the given
070: name. If such a graph exists, return it. Otherwise, if <code>strict</code>
071: is false, create a new graph, associate it with the name, and return it.
072: Otherwise throw a DoesNotExistException.
073:
074: @param name the name of the graph to find and return
075: @param strict false to create a new one if one doesn't already exist
076: @exception DoesNotExistException if there's no such named graph
077: */
078: public Graph openGraph(String name, boolean strict);
079:
080: /**
081: Equivalent to <code>openGraph( name, false )</code>
082: */
083: public Graph openGraph(String name);
084:
085: /**
086: Remove the association between the name and the graph. create
087: will now be able to create a graph with that name, and open will no
088: longer be able to find it. Throws an exception if there's no such graph.
089: The graph itself is not touched.
090:
091: @param name the name to disassociate
092: @exception DoesNotExistException if the name is unbound
093: */
094: public void removeGraph(String name);
095:
096: /**
097: return true iff the factory has a graph with the given name
098:
099: @param name the name of the graph to look for
100: @return true iff there's a graph with that name
101: */
102: public boolean hasGraph(String name);
103:
104: /**
105: Answer a Graph describing this GraphMaker using the vocabulary of
106: JenaModelSpec.
107:
108: @return a Graph describing this Maker.
109: */
110: public Graph getDescription();
111:
112: public Graph getDescription(Node root);
113:
114: /**
115: Add the description of this GraphMaker to the description graph desc, under the
116: name self.
117: @param desc the graph to which to add the description
118: @param self the root resource to use for the description
119: */
120: public Graph addDescription(Graph desc, Node self);
121:
122: /**
123: Close the factory - no more requests need be honoured, and any clean-up
124: can be done.
125: */
126: public void close();
127:
128: /**
129: Answer an [extended] iterator where each element is the name of a graph in
130: the maker, and the complete sequence exhausts the set of names. No particular
131: order is expected from the list.
132: @return an extended iterator over the names of graphs known to this Maker.
133: */
134: ExtendedIterator listGraphs();
135: }
136:
137: /* ****************************************************************************
138: * Source code information
139: * -----------------------
140: * Original author Ian Dickinson, HP Labs Bristol
141: * Package Jena 2
142: * Web http://sourceforge.net/projects/jena/
143: * Created 06-Mar-2003
144: *
145: * Last modified on $Date: 2008/01/02 12:06:55 $
146: * by $Author: andy_seaborne $
147:
148: *****************************************************************************/
149:
150: /*
151: (c) Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
152: All rights reserved.
153:
154: Redistribution and use in source and binary forms, with or without
155: modification, are permitted provided that the following conditions
156: are met:
157:
158: 1. Redistributions of source code must retain the above copyright
159: notice, this list of conditions and the following disclaimer.
160:
161: 2. Redistributions in binary form must reproduce the above copyright
162: notice, this list of conditions and the following disclaimer in the
163: documentation and/or other materials provided with the distribution.
164:
165: 3. The name of the author may not be used to endorse or promote products
166: derived from this software without specific prior written permission.
167:
168: THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
169: IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
170: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
171: IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
172: INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
173: NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
174: DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
175: THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
176: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
177: THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
178: */
|