PrefixMapping


1   /*
2     (c) Copyright 2004, 2005 Hewlett-Packard Development Company, LP
3     [See end of file]
4     $Id: PrefixMapping.java,v 1.30 2005/04/10 12:45:52 chris-dollin Exp $
5   */
6   
7   package com.hp.hpl.jena.shared;
8   
9   import java.util.*;
10  import com.hp.hpl.jena.shared.impl.*;
11  import com.hp.hpl.jena.vocabulary.*;
12  
13  /**
14      Methods for recording namepsace prefix mappings and applying and
15      unapplying them to URIs.
16  <p>
17      Note that a Model *is* a PrefixMapping, so all the PrefixMapping
18      operations apply to Models, and a Model can be used to supply
19      the PrefixMapping argument to setNsPrefixes.
20      
21      @author kers
22  */
23  
24  public interface PrefixMapping
25      {
26      /**
27          Specify the prefix name for a URI prefix string. Any existing use of 
28          that prefix name is overwritten. The result is this same prefixMapping. 
29          (The earlier restriction that adding second prefix for the same URI
30          caused the earlier binding to be deleted has been withdrawn.)
31    <p>      
32          A prefix name must be a valid NCName, or the empty string. The empty string
33          is reserved to mean "the default namespace".
34    <p>
35          Need not check the RFC2396 validity of the URI. Bad URIs are either silently 
36          ignored or behave as if they were good. The earlier restriction that the URI
37          should end with a non-NCName character has been removed.
38          
39          @param prefix the string to be used for the prefix.
40          @param uri the URI prefix to be named
41          @exception IllegalPrefixException if the prefix is not an XML NCName
42          @return this PrefixMapping
43      */
44      PrefixMapping setNsPrefix( String   prefix, String   uri );
45      
46      /**
47          Remove any existing maplet with the given prefix name and answer this
48          mapping. If the prefix is the empty string, then this removes the default
49          namespace. If the prefix is not a legal prefix string, or is not present in
50          the mapping, nothing happens.
51          
52          <p>The reverse URI-to-prefix mapping is updated, but if there are
53          multiple prefixes for the removed URI it is unspecified which of them
54          will be chosen.
55          
56          @param prefix the prefix string to remove
57          @return this PrefixMapping
58       */
59      
60      PrefixMapping removeNsPrefix( String   prefix );
61      
62      /**
63          Copies the prefixes from other into this. Any existing binding of the
64          same prefix is lost.  The result is this same prefixMapping.
65  
66          @param other the PrefixMapping to add
67          @return this PrefixMapping
68      */
69      PrefixMapping setNsPrefixes( PrefixMapping other );
70      
71      /**
72          Copies the prefix mapping from other into this. Illegal prefix mappings
73          are detected. Existing binds of the same prefix are lost.  The result is this 
74          same prefixMapping.
75          
76          @param map the Map whose maplets are to be added
77          @return this PrefixMapping
78      */
79      PrefixMapping setNsPrefixes( Map map );
80      
81      /**
82           Update this PrefixMapping with the bindings in <code>map</code>, only
83           adding those (p, u) pairs for which neither p nor u appears in this mapping.
84           Answer this PrefixMapping.
85      */
86      PrefixMapping withDefaultMappings( PrefixMapping map );
87         
88      /**
89          Get the URI bound to a specific prefix, null if there isn't one.
90          
91          @param prefix the prefix name to be looked up
92          @return the most recent URI bound to that prefix name, null if none
93      */
94      String   getNsPrefixURI( String   prefix );
95      
96      /**
97          Answer the prefix for the given URI, or null if there isn't one.
98          If there is more than one, one of them will be picked. If possible,
99          it will be the most recently added prefix. (The cases where it's not
100         possible is when a binding has been removed.)
101         
102         @param uri the uri whose prefix is to be found
103         @return the prefix mapped to that uri, or null if there isn't one
104     */
105     String   getNsURIPrefix( String   uri );
106     
107     /**
108         Return a copy of the internal mapping from names to URI strings. Updating
109         this copy will have no effect on the PrefixMap.
110         
111         @return a copy of the internal String -> String mapping 
112     */
113     Map getNsPrefixMap();
114     
115     /**
116         Expand the uri using the prefix mappings if possible. If prefixed has the
117         form Foo:Bar, and Foo is a prefix bound to FooURI, return FooURI+Bar.
118         Otherwise return prefixed unchanged. 
119         
120         @param prefixed a QName or URI
121         @return the expanded string if possible, otherwise the original string
122     */
123     String   expandPrefix( String   prefixed );
124     
125     /**
126         Compress the URI using the prefix mappings if possible. If there is a
127         prefix mapping Name -> URIStart, and uri is URIStart+Tail, return Name:Tail;
128         otherwise return uri unchanged. If there are multiple applicable mappings
129         available, the "most recent" is chosen if that is possible, otherwise
130         one is picked "at random".
131     <p>    
132         The result is primarily intended for human convenience: it is <i>not</i> 
133         necessarily a legal QName, as Tail need not be a legal NCName; and there's
134         no way to tell a shortened name from a URI with an unusual scheme.
135         
136         @param uri the URI string to try and prefix-compress
137         @return the shortened form if possible, otherwise the unchanged argument
138     */
139     String   shortForm( String   uri );
140     
141     /**
142         Old name for shortForm.
143         @deprecated - use shortForm
144     */
145     String   usePrefix( String   uri );
146     
147     /**
148         Answer a qname with the expansion of the given uri, or null if no such qname
149         can be constructed using the mapping's prefixes.
150     */
151     String   qnameFor( String   uri );
152     
153     /**
154         Lock the PrefixMapping so that changes can no longer be made to it.
155         Primarily intended to lock Standard against mutation.
156         
157          @return this mapping, locked against changes 
158     */
159     PrefixMapping lock();
160     
161     /**
162         Exception to throw when the prefix argument to setNsPrefix is
163         illegal for some reason.
164     */
165     public static class IllegalPrefixException extends JenaException
166         {
167         public IllegalPrefixException( String   prefixName ) { super( prefixName ); }     
168         }
169         
170     /**
171         Exception to throw when trying to update a locked PrefixMapping.
172     */
173     public static class JenaLockedException extends JenaException
174         {
175         public JenaLockedException( PrefixMapping pm ) { super( pm.toString() ); }
176         }
177         
178     /**
179         Factory class to create an unspecified kind of PrefixMapping.
180     */
181     public static class Factory
182         { public static PrefixMapping create() { return new PrefixMappingImpl(); } }     
183 
184     /**
185         A PrefixMapping that contains the "standard" prefixes we know about,
186         viz rdf, rdfs, dc, rss, vcard, and owl.
187     */
188     public static final PrefixMapping Standard = PrefixMapping.Factory.create()
189         .setNsPrefix( "rdfs", RDFS.getURI() )
190         .setNsPrefix( "rdf", RDF.getURI() )
191         .setNsPrefix( "dc", DC.getURI() )
192         .setNsPrefix( "daml", DAMLVocabulary.NAMESPACE_DAML_2001_03_URI )
193         .setNsPrefix( "owl", OWL.getURI() )
194         .setNsPrefix( "xsd", "http://www.w3.org/2001/XMLSchema#" )
195         .lock()
196         ;   
197     
198     /**
199          A PrefixMapping built on Standard with some extras
200     */    
201     public static final PrefixMapping Extended = PrefixMapping.Factory.create()
202         .setNsPrefixes( Standard )
203         .setNsPrefix( "rss", RSS.getURI() )
204         .setNsPrefix( "vcard", VCARD.getURI() )
205         .setNsPrefix( "jms", JenaModelSpec.getURI() )
206         .setNsPrefix( "eg", "http://www.example.org/" )
207         .lock()
208         ;   
209     }
210 
211 /*
212     (c) Copyright 2004, 2005 Hewlett-Packard Development Company, LP
213     All rights reserved.
214 
215     Redistribution and use in source and binary forms, with or without
216     modification, are permitted provided that the following conditions
217     are met:
218 
219     1. Redistributions of source code must retain the above copyright
220        notice, this list of conditions and the following disclaimer.
221 
222     2. Redistributions in binary form must reproduce the above copyright
223        notice, this list of conditions and the following disclaimer in the
224        documentation and/or other materials provided with the distribution.
225 
226     3. The name of the author may not be used to endorse or promote products
227        derived from this software without specific prior written permission.
228 
229     THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
230     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
231     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
232     IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
233     INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
234     NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
235     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
236     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
237     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
238     THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
239 */
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags