001: /*
002: * (c) Copyright 2000, 2001, 2002, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
003: * All rights reserved.
004: *
005: * Redistribution and use in source and binary forms, with or without
006: * modification, are permitted provided that the following conditions
007: * are met:
008: * 1. Redistributions of source code must retain the above copyright
009: * notice, this list of conditions and the following disclaimer.
010: * 2. Redistributions in binary form must reproduce the above copyright
011: * notice, this list of conditions and the following disclaimer in the
012: * documentation and/or other materials provided with the distribution.
013: * 3. The name of the author may not be used to endorse or promote products
014: * derived from this software without specific prior written permission.
015:
016: * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
017: * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
018: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
019: * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
020: * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
021: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
022: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
023: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
024: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
025: * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
026: *
027: * Resource.java
028: *
029: * Created on 25 July 2000, 13:14
030: */
031:
032: package com.hp.hpl.jena.rdf.model;
033:
034: import com.hp.hpl.jena.datatypes.RDFDatatype;
035: import com.hp.hpl.jena.graph.Node;
036:
037: /** An RDF Resource.
038:
039: Resource instances when created may be associated with a specific model.
040: Resources created <i>by</i> a model will refer to that model, and support
041: a range of methods, such as <code>getProperty()</code> and
042: <code>addProperty()</code> which will access or modify that model. This
043: enables the programmer to write code in a compact and easy style.
044:
045: <p>
046: Resources created by ResourceFactory will not refer to any model, and will
047: not permit operations which require a model. Such resources are useful
048: as general constants.
049:
050: <p>This interface provides methods supporting typed literals. This means
051: that methods are provided which will translate a built in type, or an
052: object to an RDF Literal. This translation is done by invoking the
053: <CODE>toString()</CODE> method of the object, or its built in equivalent.
054: The reverse translation is also supported. This is built in for built
055: in types. Factory objects, provided by the application, are used
056: for application objects.</p>
057: <p>This interface provides methods for supporting enhanced resources. An
058: enhanced resource is a resource to which the application has added
059: behaviour. RDF containers are examples of enhanced resources built in
060: to this package. Enhanced resources are supported by encapsulating a
061: resource created by an implementation in another class which adds
062: the extra behaviour. Factory objects are used to construct such
063: enhanced resources.</p>
064: @author bwm
065: @version Release='$Name: $' Revision='$Revision: 1.28 $' Date='$Date: 2008/01/02 12:05:46 $'
066: */
067: public interface Resource extends RDFNode {
068:
069: /** Returns an a unique identifier for anonymous resources.
070: *
071: * <p>The id is unique within the scope of a particular implementation. All
072: * models within an implementation will use the same id for the same anonymous
073: * resource.</p>
074: *
075: * <p>This method is undefined if called on resources which are not anonymous
076: * and may raise an exception.</p>
077: * @return A unique id for an anonymous resource.
078: */
079: public AnonId getId();
080:
081: /**
082: Answer the underlying [SPI] Node of this Resource.
083: @deprecated use asNode().
084: */
085: public Node getNode();
086:
087: /**
088: Answer true iff this Resource is a URI resource with the given URI.
089: Using this is preferred to using getURI() and .equals().
090: */
091: public boolean hasURI(String uri);
092:
093: /** Return the URI of the resource, or null if it's a bnode.
094: * @return The URI of the resource, or null if it's a bnode.
095: */
096: public String getURI();
097:
098: /** Returns the namespace associated with this resource.
099: * @return The namespace for this property.
100: */
101: public String getNameSpace();
102:
103: /** Returns the name of this resource within its namespace.
104: * @return The name of this property within its namespace.
105: */
106: public String getLocalName();
107:
108: /** Return a string representation of the resource.
109: *
110: * Returns the URI of the resource unless the resource is anonymous
111: * in which case it returns the id of the resource enclosed in square
112: * brackets.
113: * @return Return a string representation of the resource.
114: * if it is anonymous.
115: */
116: public String toString();
117:
118: /** Determine whether two objects represent the same resource.
119: *
120: * <p>A resource can only be equal to another resource.
121: * If both resources are not anonymous, then they are equal if the URI's are
122: * equal. If both resources are anonymous, they are equal only if there Id's
123: * are the same. If one resource is anonymous and the other is not, then they
124: * are not equal.</p>
125: * @param o The object to be compared.
126: * @return true if and only if both objects are equal
127: */
128: public boolean equals(Object o);
129:
130: /** Get a property value of this resource.
131: *
132: * <p>The model associated with the resource instance is searched for statements
133: * whose subject is this resource and whose predicate is p. If such a statement
134: * is found, it is returned. If several such statements are found, any one may
135: * be returned. If no such statements are found, an exception is thrown.</p>
136: * @param p The property sought.
137: * @return some (this, p, ?O) statement if one exists
138: * @throws PropertyNotFoundException if no such statement found
139: */
140: public Statement getRequiredProperty(Property p);
141:
142: /**
143: Answer some statement (this, p, O) in the associated model. If there are several
144: such statements, any one of them may be returned. If no such statements exist,
145: null is returned - in this is differs from getRequiredProperty.
146: @param p the property sought
147: @return a statement (this, p, O), or null if no such statements exist here
148: */
149: public Statement getProperty(Property p);
150:
151: /** List all the values of the property p.
152: *
153: * <p>Returns an iterator over all the statements in the associated model whose
154: * subject is this resource and whose predicate is p.</p>
155: * @param p The predicate sought.
156: * @return An iterator over the statements.
157: */
158: public StmtIterator listProperties(Property p);
159:
160: /** Return an iterator over all the properties of this resource.
161: *
162: * <p>The model associated with this resource is search and an iterator is
163: * returned which iterates over all the statements which have this resource
164: * as a subject.</p>
165: * @return An iterator over all the statements about this object.
166: */
167: public StmtIterator listProperties();
168:
169: /**
170: Add the property <code>p</code> with the typed-literal value <code>o</code>
171: to this resource, <i>ie</i> add (this, p, typed(o)) to this's model. Answer
172: this resource. The typed literal is equal to one constructed by using
173: <code>this.getModel().createTypedLiteral(o)</code>.
174: */
175: public Resource addLiteral(Property p, boolean o);
176:
177: /**
178: Add the property <code>p</code> with the typed-literal value <code>o</code>
179: to this resource, <i>ie</i> add (this, p, typed(o)) to this's model. Answer
180: this resource. The typed literal is equal to one constructed by using
181: <code>this.getModel().createTypedLiteral(o)</code>.
182: */
183: public Resource addLiteral(Property p, long o);
184:
185: /**
186: Add the property <code>p</code> with the typed-literal value <code>o</code>
187: to this resource, <i>ie</i> add (this, p, typed(o)) to this's model. Answer
188: this resource. The typed literal is equal to one constructed by using
189: <code>this.getModel().createTypedLiteral(o)</code>.
190: */
191: public Resource addLiteral(Property p, char o);
192:
193: /**
194: Add the property <code>p</code> with the typed-literal value <code>o</code>
195: to this resource, <i>ie</i> add (this, p, typed(o)) to this's model. Answer
196: this resource. The typed literal is equal to one constructed by using
197: <code>this.getModel().createTypedLiteral(o)</code>.
198: */
199: public Resource addLiteral(Property value, double d);
200:
201: /**
202: Add the property <code>p</code> with the typed-literal value <code>o</code>
203: to this resource, <i>ie</i> add (this, p, typed(o)) to this's model. Answer
204: this resource. The typed literal is equal to one constructed by using
205: <code>this.getModel().createTypedLiteral(o)</code>.
206: */
207: public Resource addLiteral(Property value, float d);
208:
209: /**
210: Add the property <code>p</code> with the typed-literal value <code>o</code>
211: to this resource, <i>ie</i> add (this, p, typed(o)) to this's model. Answer
212: this resource. The typed literal is equal to one constructed by using
213: <code>this.getModel().createTypedLiteral(o)</code>.
214: */
215: public Resource addLiteral(Property p, Object o);
216:
217: /** Add a property to this resource.
218: *
219: * <p>A statement with this resource as the subject, p as the predicate and o
220: * as the object is added to the model associated with this resource.</p>
221: * @param p The property to be added.
222: * @param o The value of the property to be added.
223: * @return This resource to allow cascading calls.
224: */
225: public Resource addProperty(Property p, String o);
226:
227: /** Add a property to this resource.
228: *
229: * <p>A statement with this resource as the subject, p as the predicate and o
230: * as the object is added to the model associated with this resource.</p>
231: * @param p The property to be added.
232: * @param o The value of the property to be added.
233: * @param l the language of the property
234: * @return This resource to allow cascading calls.
235: */
236: public Resource addProperty(Property p, String o, String l);
237:
238: /** Add a property to this resource.
239: *
240: * <p>A statement with this resource as the subject, p as the predicate and o
241: * as the object is added to the model associated with this resource.</p>
242: * @param p The property to be added.
243: * @param lexicalForm The lexical form of the literal
244: * @param datatype The datatype
245: * @return This resource to allow cascading calls.
246: */
247: public Resource addProperty(Property p, String lexicalForm,
248: RDFDatatype datatype);
249:
250: /** Add a property to this resource.
251: *
252: * <p>A statement with this resource as the subject, p as the predicate and o
253: * as the object is added to the model associated with this resource.</p>
254: * @param p The property to be added.
255: * @param o The value of the property to be added.
256: * @return This resource to allow cascading calls.
257: */
258: public Resource addProperty(Property p, RDFNode o);
259:
260: /** Determine whether this resource has any values for a given property.
261: * @param p The property sought.
262: * @return true if and only if this resource has at least one
263: * value for the property.
264: */
265: public boolean hasProperty(Property p);
266:
267: /**
268: Answer true iff this resource has the value <code>o</code> for
269: property <code>p</code>. <code>o</code> is interpreted as
270: a typed literal with the appropriate RDF type.
271: */
272: public boolean hasLiteral(Property p, boolean o);
273:
274: /**
275: Answer true iff this resource has the value <code>o</code> for
276: property <code>p</code>. <code>o</code> is interpreted as
277: a typed literal with the appropriate RDF type.
278: */
279: public boolean hasLiteral(Property p, long o);
280:
281: /**
282: Answer true iff this resource has the value <code>o</code> for
283: property <code>p</code>. <code>o</code> is interpreted as
284: a typed literal with the appropriate RDF type.
285: */
286: public boolean hasLiteral(Property p, char o);
287:
288: /**
289: Answer true iff this resource has the value <code>o</code> for
290: property <code>p</code>. <code>o</code> is interpreted as
291: a typed literal with the appropriate RDF type.
292: */
293: public boolean hasLiteral(Property p, double o);
294:
295: /**
296: Answer true iff this resource has the value <code>o</code> for
297: property <code>p</code>. <code>o</code> is interpreted as
298: a typed literal with the appropriate RDF type.
299: */
300: public boolean hasLiteral(Property p, float o);
301:
302: /**
303: Answer true iff this resource has the value <code>o</code> for
304: property <code>p</code>. <code>o</code> is interpreted as
305: a typed literal with the appropriate RDF type.
306: */
307: public boolean hasLiteral(Property p, Object o);
308:
309: /** Test if this resource has a given property with a given value.
310: * @param p The property sought.
311: * @param o The value of the property sought.
312: * @return true if and only if this resource has property p with
313: * value o.
314: */
315: public boolean hasProperty(Property p, String o);
316:
317: /** Test if this resource has a given property with a given value.
318: * @param p The property sought.
319: * @param o The value of the property sought.
320: * @param l The language of the property sought.
321: * @return true if and only if this resource has property p with
322: * value o.
323: */
324: public boolean hasProperty(Property p, String o, String l);
325:
326: /** Test if this resource has a given property with a given value.
327: * @param p The property sought.
328: * @param o The value of the property sought.
329: * @return true if and only if this resource has property p with
330: * value o.
331: */
332: public boolean hasProperty(Property p, RDFNode o);
333:
334: /** Delete all the properties for this resource from the associated model.
335: * @return This resource to permit cascading.
336: */
337: public Resource removeProperties();
338:
339: /**
340: Delete all the statements with predicate <code>p</code> for this resource
341: from its associated model.
342:
343: @param p the property to remove
344: @return this resource, to permit cascading
345: */
346: public Resource removeAll(Property p);
347:
348: /** Begin a transaction in the associated model.
349: * @return This resource to permit cascading.
350: */
351: public Resource begin();
352:
353: /** Abort the transaction in the associated model.
354: * @return This resource to permit cascading.
355: */
356: public Resource abort();
357:
358: /** Commit the transaction in the associated model.
359: * @return This resource to permit cascading.
360: */
361: public Resource commit();
362:
363: /** Return the model associated with this resource. If the Resource
364: * was not created by a Model, the result may be null.
365: *
366: * @return The model associated with this resource.
367: */
368: public Model getModel();
369: }
|