001: /*
002: * (c) Copyright 2000, 2001, 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: * Literal.java
028: *
029: * Created on 26 July 2000, 14:33
030: */
031:
032: package com.hp.hpl.jena.rdf.model;
033:
034: import com.hp.hpl.jena.datatypes.RDFDatatype;
035:
036: /** An RDF Literal.
037: *
038: * <p>In RDF2003 literals can be typed. If typed then the literal comprises a
039: * datatype, a lexical form and a value (together with an optional xml:lang
040: * string). Old style literals have no type and are termed "plain" literals.</p>
041: *
042: * <p>Implementations of this interface should be able to support both plain
043: * and typed literals. In the case of typed literals the primitive accessor methods
044: * such as getInt() determine if the literal value can be coerced to an appropriate
045: * java wrapper class. If so then the class is unwrapped to extract the primitive
046: * value returned. If the coercion fails then a runtime DatatypeFormatException is
047: * thrown.</p>
048: *
049: * <p>In the case of plain literals then the primitve accessor methods duplicate
050: * the behvaiour of jena1. The literal is internally stored in lexical form but
051: * the accessor methods such as getInt will attempt to parse the lexical form
052: * and if successful will return the primitive value.</p>
053: *
054: * <p>Object (i.e. non-primitive) values are supported. In the case of typed literals
055: * then a global TypeMapper registry determines what datatype representation to
056: * use for a given Object type. In the case of plain literals then the object
057: * will be stored in the lexical form given by its <CODE>toString</CODE> method.
058: * Factory objects, provided by the application, are needed in that case to covert
059: * the lexical form back into the appropriate object type.</p>
060: *
061: * @author bwm and der
062: * @version $Name: $ $Revision: 1.16 $ $Date: 2008/01/02 12:05:46 $
063: */
064: public interface Literal extends RDFNode {
065:
066: /**
067: * Return the value of the literal. In the case of plain literals
068: * this will return the literal string. In the case of typed literals
069: * it will return a java object representing the value. In the case
070: * of typed literals representing a java primitive then the appropriate
071: * java wrapper class (Integer etc) will be returned.
072: */
073: public Object getValue();
074:
075: /**
076: * Return the datatype of the literal. This will be null in the
077: * case of plain literals.
078: */
079: public RDFDatatype getDatatype();
080:
081: /**
082: * Return the uri of the datatype of the literal. This will be null in the
083: * case of plain literals.
084: */
085: public String getDatatypeURI();
086:
087: /**
088: * Return the lexical form of the literal.
089: */
090: public String getLexicalForm();
091:
092: /**
093: * If the literal is interpretable as a Boolean return its value
094: * as a boolean. Plain literals are interpreted by parsing their
095: * lexical representation, typed literals are interpreted by coercion
096: * of the java object representing their value.
097: *
098:
099: * @return the literal interpeted as a boolean
100: */
101: public boolean getBoolean();
102:
103: /**
104: * If the literal is interpretable as a Byte return its value.
105: * Plain literals are interpreted by parsing their
106: * lexical representation, typed literals are interpreted by coercion
107: * of the java object representing their value.
108: *
109:
110: * @return the literal interpeted as a byte
111: */
112: public byte getByte();
113:
114: /**
115: * If the literal is interpretable as a Short return its value.
116: * Plain literals are interpreted by parsing their
117: * lexical representation, typed literals are interpreted by coercion
118: * of the java object representing their value.
119: *
120:
121: * @return the literal interpeted as a short
122: */
123: public short getShort();
124:
125: /**
126: * If the literal is interpretable as a Integer return its value.
127: * Plain literals are interpreted by parsing their
128: * lexical representation, typed literals are interpreted by coercion
129: * of the java object representing their value.
130: *
131:
132: * @return the literal interpeted as an int
133: */
134: public int getInt();
135:
136: /**
137: * If the literal is interpretable as a Long return its value.
138: * Plain literals are interpreted by parsing their
139: * lexical representation, typed literals are interpreted by coercion
140: * of the java object representing their value.
141: *
142:
143: * @return the literal interpeted as a long
144: */
145: public long getLong();
146:
147: /**
148: * If the literal is interpretable as a Char return its value.
149: * Plain literals are interpreted by parsing their
150: * lexical representation, typed literals are interpreted by coercion
151: * of the java object representing their value.
152: *
153:
154: * @return the literal interpeted as a char
155: */
156: public char getChar();
157:
158: /**
159: * If the literal is interpretable as a Float return its value.
160: * Plain literals are interpreted by parsing their
161: * lexical representation, typed literals are interpreted by coercion
162: * of the java object representing their value.
163: *
164:
165: * @return the literal interpeted as a float
166: */
167: public float getFloat();
168:
169: /**
170: * If the literal is interpretable as a Double return its value.
171: * Plain literals are interpreted by parsing their
172: * lexical representation, typed literals are interpreted by coercion
173: * of the java object representing their value.
174: *
175:
176: * @return the literal interpeted as a double
177: */
178: public double getDouble();
179:
180: /**
181: * If the literal is interpretable as a string return its value.
182: * For typed literals this will throw an error for non string
183: * literals and one needs to use getLexicalForm to return the
184: * string form of other datatypes.
185: *
186:
187: * @return the literal string
188: */
189: // TODO is this the right approach, could make getString synonomous
190: // with getLexicalForm
191: public String getString();
192:
193: /**
194: * In the case of plain literals this recreates an object from its
195: * lexical form using the given factory. In the case of typed literals
196: * the factory is ignored and the value is returned instead.
197: *
198: * @return the object created from the literal string
199: * @param f A factory object for creating the returned object.
200:
201: */
202: // @TODO is this the right approach, could reparse the lexical form
203: // using the factory even for typed literals
204: public Object getObject(ObjectF f);
205:
206: /**
207: If a language is defined for this literal return it
208: @return the language for this literal if it exists, or empty string if none
209: */
210: public String getLanguage();
211:
212: /** Return whether Literal is well formed XML
213: * @deprecated use isWellFormedXML instead.
214: * @return true if the literal is well formed XML, e.g. as
215: * would be produced from a parseType="Literal"
216: * element.
217: */
218: public boolean getWellFormed();
219:
220: /**
221: Answer true iff this literal is (or claims to be) well-formed XML.
222: */
223: public boolean isWellFormedXML();
224:
225: /** Test whether another object is equal to this object.
226: *
227: * <p>A plain Literal is equal to another object only if the object is
228: * also a plain Literal and the string value and language of both
229: * literals are equal. In the case of a typed literal equality is
230: * defined by the datatype equality function on the value spaces and
231: * may or may not include comparison of the lang strings.</p>
232: * @param o The object to test against
233: * @return true if the the objects are equal, false otherwise
234: */
235: public boolean equals(Object o);
236:
237: /**
238: * Test that two literals are semantically equivalent.
239: * In some cases this may be the sames as equals, in others
240: * equals is stricter. For example, two xsd:int literals with
241: * the same value but different language tag are semantically
242: * equivalent but distinguished by the java equality function
243: * in order to support round tripping.
244: */
245: public boolean sameValueAs(Literal other);
246: }
|