001: /*
002: (c) Copyright 2000-2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
003: [See end of file]
004: $Id: Statement.java,v 1.21 2008/01/02 12:05:48 andy_seaborne Exp $
005: */
006:
007: package com.hp.hpl.jena.rdf.model;
008:
009: import com.hp.hpl.jena.graph.*;
010: import com.hp.hpl.jena.util.iterator.Map1;
011:
012: /** An RDF Statement.
013: *
014: * <p>A Statement is not a Resource, but can produce a ReifiedStatement
015: * that represents it and from which the Statement can be recovered.</p>
016: *
017: * <p>A statement instance tracks which model created it, if any. All the
018: * Resource components of a Statement are in the same model as the
019: * Statement, if it has one, and are in no model if the Statement isn't.</p>
020: *
021: * <p>This interface provides methods supporting typed literals. This means
022: * that methods are provided which will translate a built in type, or an
023: * object to an RDF Literal. This translation is done by invoking the
024: * <CODE>toString()</CODE> method of the object, or its built in equivalent.
025: * The reverse translation is also supported. This is built in for built
026: * in types. Factory objects, provided by the application, are used
027: * for application objects.</p>
028:
029: * @author bwm; additions by kers
030: * @version $Name: $ $Revision: 1.21 $ $Date: 2008/01/02 12:05:48 $
031: */
032:
033: public interface Statement extends FrontsTriple {
034:
035: /** determine whether two statements are equal.
036: *
037: * <p> Two statements are considered to be equal if they have the
038: * the same subject, predicate and object. A statement can
039: * only be equal to another statement object.
040: * </p>
041: * @return true if and only if the equality condition is met.
042: * @param o the object to be compared
043: */
044:
045: public boolean equals(Object o);
046:
047: /** Returns asTriple().hashCode()
048: */
049: public int hashCode();
050:
051: /** An accessor method to return the subject of the statements.
052: * @return The subject of the statement.
053: */
054: public Resource getSubject();
055:
056: /** An accessor function to return the predicate of the statement.
057: * @return The predicate of the statement.
058: */
059: public Property getPredicate();
060:
061: /** An accessor funtion to return the object of the statement.
062: * @return Return the object of the statement.
063: */
064: public RDFNode getObject();
065:
066: /** Get a property of the object of the statement.
067: *
068: * <p>There is an unfortunate ambiguity here. GetProperty would normally
069: * treat the statement as a resource, and return a property about this
070: * statement. This is not what is wanted in most cases, so getProperty
071: * on a statement is defined to call getProperty on its object. If
072: * a property of the statement itself is required, getStatementProperty
073: * should be used.</p>
074: *
075: * <p>If the object of the statement is not a resource, an exception is
076: * thrown.</p>
077: * @param p the property sought
078:
079: * @return a statement representing an instance of the required
080: * property
081: */
082: public Statement getProperty(Property p);
083:
084: /** Return a property of this statement.
085: *
086: * <p>The model associated with this statement is searched for a statement with
087: * this statement as subject and the specified property as predicate. If
088: * such a statement is found it is return. If more than one exists in the
089: * model, then it is undefined which is returned. If no such statement
090: * exists, an exception is thrown.</p>
091: * @param p the property sought
092:
093: * @return a statement representing an instance of the specified
094: * property.
095: */
096: public Statement getStatementProperty(Property p);
097:
098: /** Return the object of the statement.
099: *
100: * <p>An exception will be thrown if the object is not a resource.</p>
101: *
102: * @return The Resource which is the object of the statement.
103: */
104: public Resource getResource();
105:
106: /** Return the object of the statement.
107: *
108: * <p>An exception will be thrown if the object is not a Literal.</p>
109: *
110: * @return The Literal which is the object of the statement.
111: */
112: public Literal getLiteral();
113:
114: /** Return the object of the statement.
115: *
116: * <p>An exception will be thrown if the object is not a Literal.</p>
117: *
118: * @return The object of the statement interpreted as a value of the
119: * the specified type.
120: */
121: public boolean getBoolean();
122:
123: /** Return the object of the statement.
124: *
125: * <p>An exception will be thrown if the object is not a Literal.</p>
126: *
127: * @return The object of the statement interpreted as a value of the
128: * the specified type.
129: */
130: public byte getByte();
131:
132: /** Return the object of the statement.
133: *
134: * <p>An exception will be thrown if the object is not a Literal.</p>
135: *
136: * @return The object of the statement interpreted as a value of the
137: * the specified type.
138: */
139: public short getShort();
140:
141: /** Return the object of the statement.
142: *
143: * <p>An exception will be thrown if the object is not a Literal.</p>
144: *
145: * @return The object of the statement interpreted as a value of the
146: * the specified type.
147: */
148: public int getInt();
149:
150: /** Return the object of the statement.
151: *
152: * <p>An exception will be thrown iof the object is not a Literal.</p>
153: *
154: * @return The object of the statement interpreted as a value of the
155: * the specified type.
156: */
157: public long getLong();
158:
159: /** Return the object of the statement.
160: *
161: * <p>An exception will be thrown if the object is not a Literal.</p>
162: *
163: * @return The object of the statement interpreted as a value of the
164: * the specified type.
165: */
166: public char getChar();
167:
168: /** Return the object of the statement.
169: *
170: * <p>An exception will be thrown if the object is not a Literal.</p>
171: *
172: * @return The object of the statement interpreted as a value of the
173: * the specified type.
174: */
175: public float getFloat();
176:
177: /** Return the object of the statement.
178: *
179: * <p>An exception will be thrown if the object is not a Literal.</p>
180: *
181: * @return The object of the statement interpreted as a value of the
182: * the specified type.
183: */
184: public double getDouble();
185:
186: /** Return the object of the statement.
187: *
188: * <p>An exception will be thrown if the object is not a Literal.</p>
189: *
190: * @return The object of the statement interpreted as a value of the
191: * the specified type.
192: */
193: public String getString();
194:
195: /** Return the object of the statement.
196: *
197: * <p>An exception will be thrown if the object is not a Resource.</p>
198: * @return The object of the statement.
199: *
200: */
201: public Resource getResource(ResourceF f);
202:
203: /** Return the object of the statement.
204: * <p>An exception will be thrown if the object is not a Literal.</p>
205: * @return The object of the statement.
206: * @param f A factory used to create the returned object.
207: *
208: */
209: public Object getObject(ObjectF f);
210:
211: /** Return the object of the statement.
212: *
213: * <p>An exception will be thrown if the object is not a Resource.</p>
214: *
215: * @return The object of the statement interpreted as a value of the
216: * the specified type.
217: */
218: public Bag getBag();
219:
220: /** Return the object of the statement.
221: *
222: * <p>An exception will be thrown if the object is not a Resource.</p>
223: *
224: * @return The object of the statement interpreted as a value of the
225: * the specified type.
226: */
227: public Alt getAlt();
228:
229: /** Return the object of the statement.
230: *
231: * <p>An exception will be thrown if the object is not a Resource.</p>
232: *
233: * @return The object of the statement interpreted as a value of the
234: * the specified type.
235: */
236: public Seq getSeq();
237:
238: /** Return the language of the object of the statement.
239: *
240: * <p>An exception will be thrown if the object is not a Literal.</p>
241: *
242: * @return the language of the object of the statement
243: */
244: public String getLanguage();
245:
246: /**
247: Answer true iff the Literal object of this statement is well-formed XML
248: (ie equivalent to getLiteral().isWellFormedXML()). If the object is not
249: a Literal, throw an exception.
250: */
251: public boolean hasWellFormedXML();
252:
253: /**
254: Remove this statement (s, p, x) from the model that contains it. Create a
255: new statement (s, p, o'), where o' is the typed literal corresponding to
256: o, add it to the model, and answer it.
257: */
258: public Statement changeLiteralObject(boolean o);
259:
260: /**
261: Remove this statement (s, p, x) from the model that contains it. Create a
262: new statement (s, p, o'), where o' is the typed literal corresponding to
263: o, add it to the model, and answer it.
264: */
265: public Statement changeLiteralObject(long o);
266:
267: /**
268: Remove this statement (s, p, x) from the model that contains it. Create a
269: new statement (s, p, o'), where o' is the typed literal corresponding to
270: o, add it to the model, and answer it.
271: */
272: public Statement changeLiteralObject(int o);
273:
274: /**
275: Remove this statement (s, p, x) from the model that contains it. Create a
276: new statement (s, p, o'), where o' is the typed literal corresponding to
277: o, add it to the model, and answer it.
278: */
279: public Statement changeLiteralObject(char o);
280:
281: /**
282: Remove this statement (s, p, x) from the model that contains it. Create a
283: new statement (s, p, o'), where o' is the typed literal corresponding to
284: o, add it to the model, and answer it.
285: */
286: public Statement changeLiteralObject(float o);
287:
288: /**
289: Remove this statement (s, p, x) from the model that contains it. Create a
290: new statement (s, p, o'), where o' is the typed literal corresponding to
291: o, add it to the model, and answer it.
292: */
293: public Statement changeLiteralObject(double o);
294:
295: /** @deprecated use changeLiteralObject etc */
296: public Statement changeObject(float o);
297:
298: /** @deprecated use changeLiteralObject etc */
299: public Statement changeObject(boolean o);
300:
301: /** @deprecated use changeLiteralObject etc */
302: public Statement changeObject(long o);
303:
304: /** @deprecated use changeLiteralObject etc */
305: public Statement changeObject(double o);
306:
307: /** @deprecated use changeLiteralObject etc */
308: public Statement changeObject(Object o);
309:
310: /** change the object of the statement (S, P, X) to (S, P, o).
311: * <p>The statement with the old value is removed from the model and
312: * a new statement with the new value added and returned.</p>
313: * @param o The value to be set.
314: *
315: * @return the new (S, P, o) statement.
316: */
317: public Statement changeObject(String o);
318:
319: /** change the object of the statement (S, P, X) to (S, P, o).
320: * <p>The statement with the old value is removed from the model and
321: * a new statement with the new value added and returned.</p>
322: * @param o The value to be set.
323: * @param wellFormed true if o is well formed XML
324: *
325: * @return the new (S, P, o) statement.
326: */
327: public Statement changeObject(String o, boolean wellFormed);
328:
329: /** change the object of the statement (S, P, X) to (S, P, o).
330: * <p>The statement with the old value is removed from the model and
331: * a new statement with the new value added.</p>
332: * @param o The value to be set.
333: * @param l the language of the String
334: *
335: * @return the new (S, P, o) statement..
336: */
337: public Statement changeObject(String o, String l);
338:
339: /** change the object of the statement (S, P, X) to (S, P, o).
340: * <p>The statement with the old value is removed from the model and
341: * a new statement with the new value added.</p>
342: * @param o The value to be set.
343: * @param l the language of the String
344: *
345: * @return the new (S, P, o) statement.
346: */
347: public Statement changeObject(String o, String l, boolean wellFormed);
348:
349: /** change the object of the statement (S, P, X) to (S, P, o).
350: * <p>The statement with the old value is removed from the model and
351: * a new statement with the new value added.</p>
352: * @param o The value to be set
353: * @return the new (S, P, o) statement.
354: */
355: public Statement changeObject(RDFNode o);
356:
357: /** Remove this statement from its associated model.
358: *
359: * <p>The statement with the same subject, predicate and object as this
360: * statement will be removed from the model associated with this
361: * statement.</p>
362: *
363: * @return this statement.
364: */
365: public Statement remove();
366:
367: /**
368: Determine if this statement is the subject of any statements its associated
369: model.
370: @return true iff this statement is the subject of a statement in the model.
371: */
372: boolean isReified();
373:
374: /**
375: answer a ReifiedStatement object that embodies this Statement and
376: is in the same Model (if any).
377: */
378: ReifiedStatement createReifiedStatement();
379:
380: /**
381: answer a ReifiedStatement object that embodies this Statement, has
382: the same Model, and has the given <code>uri</code>.
383: */
384: ReifiedStatement createReifiedStatement(String uri);
385:
386: /**
387: answer an iterator which delivers all the reified statements in the model
388: this Statement belongs to that match this Statement.
389: */
390: RSIterator listReifiedStatements();
391:
392: /**
393: get the Model this Statement was created in.
394: */
395: Model getModel();
396:
397: /**
398: * Finds all possible resources which are
399: * the reification of this statement, and for each
400: * removes all four triples of the reification quad.
401: */
402: void removeReification();
403:
404: /**
405: Utility constants -- in a nested class for namespace reasons.
406: */
407: public static class Util {
408: public static final Map1 getSubject = new Map1() {
409: public Object map1(Object o) {
410: return ((Statement) o).getSubject();
411: }
412: };
413:
414: public static final Map1 getPredicate = new Map1() {
415: public Object map1(Object o) {
416: return ((Statement) o).getPredicate();
417: }
418: };
419:
420: public static final Map1 getObject = new Map1() {
421: public Object map1(Object o) {
422: return ((Statement) o).getObject();
423: }
424: };
425: }
426: }
427: /*
428: (c) Copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
429: All rights reserved.
430:
431: Redistribution and use in source and binary forms, with or without
432: modification, are permitted provided that the following conditions
433: are met:
434: 1. Redistributions of source code must retain the above copyright
435: notice, this list of conditions and the following disclaimer.
436: 2. Redistributions in binary form must reproduce the above copyright
437: notice, this list of conditions and the following disclaimer in the
438: documentation and/or other materials provided with the distribution.
439: 3. The name of the author may not be used to endorse or promote products
440: derived from this software without specific prior written permission.
441:
442: THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
443: IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
444: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
445: IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
446: INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
447: NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
448: DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
449: THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
450: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
451: THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
452: */
|