Literal


1   /*
2    *  (c) Copyright 2000, 2001, 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
3    *  All rights reserved.
4    *
5    * Redistribution and use in source and binary forms, with or without
6    * modification, are permitted provided that the following conditions
7    * are met:
8    * 1. Redistributions of source code must retain the above copyright
9    *    notice, this list of conditions and the following disclaimer.
10   * 2. Redistributions in binary form must reproduce the above copyright
11   *    notice, this list of conditions and the following disclaimer in the
12   *    documentation and/or other materials provided with the distribution.
13   * 3. The name of the author may not be used to endorse or promote products
14   *    derived from this software without specific prior written permission.
15  
16   * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17   * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19   * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20   * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21   * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22   * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23   * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24   * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25   * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26   *
27   * Literal.java
28   *
29   * Created on 26 July 2000, 14:33
30   */
31  
32  package com.hp.hpl.jena.rdf.model;
33  import com.hp.hpl.jena.datatypes.RDFDatatype;
34  
35  /** An RDF Literal.
36   * 
37   * <p>In RDF2003 literals can be typed. If typed then the literal comprises a
38   * datatype, a lexical form and a value (together with an optional xml:lang
39   * string). Old style literals have no type and are termed "plain" literals.</p>
40   * 
41   * <p>Implementations of this interface should be able to support both plain
42   * and typed literals. In the case of typed literals the primitive accessor methods 
43   * such as getInt()  determine if the literal value can be coerced to an appropriate
44   * java wrapper class. If so then the class is unwrapped to extract the primitive
45   * value returned. If the coercion fails then a runtime DatatypeFormatException is 
46   * thrown.</p>
47   * 
48   * <p>In the case of plain literals then the primitve accessor methods duplicate
49   * the behvaiour of jena1. The literal is internally stored in lexical form but
50   * the accessor methods such as getInt will attempt to parse the lexical form
51   * and if successful will return the primitive value.</p>
52   * 
53   * <p>Object (i.e. non-primitive) values are supported. In the case of typed literals
54   * then a global TypeMapper registry determines what datatype representation to
55   * use for a given Object type. In the case of plain literals then the object
56   * will be stored in the lexical form given by its <CODE>toString</CODE> method. 
57   * Factory objects, provided by the application, are needed in that case to covert
58   * the lexical form back into the appropriate object type.</p>
59   * 
60   * @author bwm and der
61   * @version $Name:  $ $Revision: 1.10 $ $Date: 2005/02/21 12:14:03 $
62   */
63  public interface Literal extends RDFNode {
64          
65      /** Answer true.
66       */
67      public boolean isLiteral();
68      
69      /**
70       * Return the value of the literal. In the case of plain literals
71       * this will return the literal string. In the case of typed literals
72       * it will return a java object representing the value. In the case
73       * of typed literals representing a java primitive then the appropriate
74       * java wrapper class (Integer etc) will be returned.
75       */
76      public Object   getValue();
77      
78      /**
79       * Return the datatype of the literal. This will be null in the
80       * case of plain literals.
81       */
82      public RDFDatatype getDatatype();
83       
84      /**
85       * Return the uri of the datatype of the literal. This will be null in the
86       * case of plain literals.
87       */
88      public String   getDatatypeURI();
89      
90      /**
91       * Return the lexical form of the literal.
92       */
93      public String   getLexicalForm();
94      
95      /**
96       * If the literal is interpretable as a Boolean return its value
97       * as a boolean. Plain literals are interpreted by parsing their
98       * lexical representation, typed literals are interpreted by coercion
99       * of the java object representing their value.
100      * 
101      
102      * @return the literal interpeted as a boolean
103      */
104     public boolean getBoolean() ;
105     
106     /**
107      * If the literal is interpretable as a Byte return its value.
108      * Plain literals are interpreted by parsing their
109      * lexical representation, typed literals are interpreted by coercion
110      * of the java object representing their value.
111      * 
112      
113      * @return the literal interpeted as a byte
114      */
115     public byte getByte() ;
116     
117     /**
118      * If the literal is interpretable as a Short return its value.
119      * Plain literals are interpreted by parsing their
120      * lexical representation, typed literals are interpreted by coercion
121      * of the java object representing their value.
122      * 
123      
124      * @return the literal interpeted as a short
125      */
126     public short getShort() ;
127     
128     /**
129      * If the literal is interpretable as a Integer return its value.
130      * Plain literals are interpreted by parsing their
131      * lexical representation, typed literals are interpreted by coercion
132      * of the java object representing their value.
133      * 
134      
135      * @return the literal interpeted as an int
136      */
137     public int getInt() ;
138     
139     /**
140      * If the literal is interpretable as a Long return its value.
141      * Plain literals are interpreted by parsing their
142      * lexical representation, typed literals are interpreted by coercion
143      * of the java object representing their value.
144      * 
145      
146      * @return the literal interpeted as a long
147      */
148     public long getLong() ;
149     
150     /**
151      * If the literal is interpretable as a Char return its value.
152      * Plain literals are interpreted by parsing their
153      * lexical representation, typed literals are interpreted by coercion
154      * of the java object representing their value.
155      * 
156      
157      * @return the literal interpeted as a char
158      */
159     public char getChar() ;
160     
161     /**
162      * If the literal is interpretable as a Float return its value.
163      * Plain literals are interpreted by parsing their
164      * lexical representation, typed literals are interpreted by coercion
165      * of the java object representing their value.
166      * 
167      
168      * @return the literal interpeted as a float
169      */
170     public float getFloat() ;
171     
172     /**
173      * If the literal is interpretable as a Double return its value.
174      * Plain literals are interpreted by parsing their
175      * lexical representation, typed literals are interpreted by coercion
176      * of the java object representing their value.
177      * 
178      
179      * @return the literal interpeted as a double
180      */
181     public double getDouble() ;
182     
183     /**
184      * If the literal is interpretable as a string return its value.
185      * For typed literals this will throw an error for non string
186      * literals and one needs to use getLexicalForm to return the 
187      * string form of other datatypes.
188      * 
189      
190      * @return the literal string
191      */
192     // TODO is this the right approach, could make getString synonomous 
193     //       with getLexicalForm
194     public String   getString() ;
195     
196     /**
197      * In the case of plain literals this recreates an object from its
198      * lexical form using the given factory. In the case of typed literals
199      * the factory is ignored and the value is returned instead.
200      * 
201      * @return the object created from the literal string
202      * @param f A factory object for creating the returned object.
203      
204      */
205     // @TODO is this the right approach, could reparse the lexical form 
206     //       using the factory even for typed literals
207     public Object   getObject(ObjectF f) ;
208     
209     /** If a language is defined for this literal return it
210      * @return the language for this literal if it exists, or null
211      */    
212     public String   getLanguage();
213     
214     /** Return whether Literal is well formed XML
215      *  @return true if the literal is well formed XML, e.g. as
216      *               would be produced from a parseType="Literal"
217      *               element.
218      */
219     public boolean getWellFormed();
220     
221     /** Test whether another object is equal to this object.
222      *
223      * <p>A plain Literal is equal to another object only if the object is 
224      *    also a plain Literal and the string value and language of both 
225      *    literals are equal. In the case of a typed literal equality is 
226      *    defined by the datatype equality function on the value spaces and
227      *    may or may not include comparison of the lang strings.</p>
228      * @param o The object to test against
229      * @return true if the the objects are equal, false otherwise
230      */    
231     public boolean equals(Object   o);
232    
233     /**
234      * Test that two literals are semantically equivalent.
235      * In some cases this may be the sames as equals, in others
236      * equals is stricter. For example, two xsd:int literals with
237      * the same value but different language tag are semantically
238      * equivalent but distinguished by the java equality function
239      * in order to support round tripping.
240      */
241     public boolean sameValueAs(Literal other);
242 }
243 
244
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags