001: /*
002: (c) Copyright 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
003: [See end of file]
004: $Id: PrefixMapping.java,v 1.38 2008/01/15 15:45:26 chris-dollin Exp $
005: */
006:
007: package com.hp.hpl.jena.shared;
008:
009: import java.util.*;
010:
011: import com.hp.hpl.jena.assembler.JA;
012: import com.hp.hpl.jena.shared.impl.*;
013: import com.hp.hpl.jena.vocabulary.*;
014:
015: /**
016: Methods for recording namepsace prefix mappings and applying and
017: unapplying them to URIs.
018: <p>
019: Note that a Model *is* a PrefixMapping, so all the PrefixMapping
020: operations apply to Models, and a Model can be used to supply
021: the PrefixMapping argument to setNsPrefixes.
022:
023: @author kers
024: */
025:
026: public interface PrefixMapping {
027: /**
028: Specify the prefix name for a URI prefix string. Any existing use of
029: that prefix name is overwritten. The result is this same prefixMapping.
030: (The earlier restriction that adding second prefix for the same URI
031: caused the earlier binding to be deleted has been withdrawn.)
032: <p>
033: A prefix name must be a valid NCName, or the empty string. The empty string
034: is reserved to mean "the default namespace".
035: <p>
036: Need not check the RFC2396 validity of the URI. Bad URIs are either silently
037: ignored or behave as if they were good. The earlier restriction that the URI
038: should end with a non-NCName character has been removed.
039:
040: @param prefix the string to be used for the prefix.
041: @param uri the URI prefix to be named
042: @exception IllegalPrefixException if the prefix is not an XML NCName
043: @return this PrefixMapping
044: */
045: PrefixMapping setNsPrefix(String prefix, String uri);
046:
047: /**
048: Remove any existing maplet with the given prefix name and answer this
049: mapping. If the prefix is the empty string, then this removes the default
050: namespace. If the prefix is not a legal prefix string, or is not present in
051: the mapping, nothing happens.
052:
053: <p>The reverse URI-to-prefix mapping is updated, but if there are
054: multiple prefixes for the removed URI it is unspecified which of them
055: will be chosen.
056:
057: @param prefix the prefix string to remove
058: @return this PrefixMapping
059: */
060:
061: PrefixMapping removeNsPrefix(String prefix);
062:
063: /**
064: Copies the prefixes from other into this. Any existing binding of the
065: same prefix is lost. The result is this same prefixMapping.
066:
067: @param other the PrefixMapping to add
068: @return this PrefixMapping
069: */
070: PrefixMapping setNsPrefixes(PrefixMapping other);
071:
072: /**
073: Copies the prefix mapping from other into this. Illegal prefix mappings
074: are detected. Existing binds of the same prefix are lost. The result is this
075: same prefixMapping.
076:
077: @param map the Map whose maplets are to be added
078: @return this PrefixMapping
079: */
080: PrefixMapping setNsPrefixes(Map map);
081:
082: /**
083: Update this PrefixMapping with the bindings in <code>map</code>, only
084: adding those (p, u) pairs for which neither p nor u appears in this mapping.
085: Answer this PrefixMapping.
086: */
087: PrefixMapping withDefaultMappings(PrefixMapping map);
088:
089: /**
090: Get the URI bound to a specific prefix, null if there isn't one.
091:
092: @param prefix the prefix name to be looked up
093: @return the most recent URI bound to that prefix name, null if none
094: */
095: String getNsPrefixURI(String prefix);
096:
097: /**
098: Answer the prefix for the given URI, or null if there isn't one.
099: If there is more than one, one of them will be picked. If possible,
100: it will be the most recently added prefix. (The cases where it's not
101: possible is when a binding has been removed.)
102:
103: @param uri the uri whose prefix is to be found
104: @return the prefix mapped to that uri, or null if there isn't one
105: */
106: String getNsURIPrefix(String uri);
107:
108: /**
109: Return a copy of the internal mapping from names to URI strings. Updating
110: this copy will have no effect on the PrefixMap.
111:
112: @return a copy of the internal String -> String mapping
113: */
114: Map getNsPrefixMap();
115:
116: /**
117: Expand the uri using the prefix mappings if possible. If prefixed has the
118: form Foo:Bar, and Foo is a prefix bound to FooURI, return FooURI+Bar.
119: Otherwise return prefixed unchanged.
120:
121: @param prefixed a QName or URI
122: @return the expanded string if possible, otherwise the original string
123: */
124: String expandPrefix(String prefixed);
125:
126: /**
127: Compress the URI using the prefix mappings if possible. If there is a
128: prefix mapping Name -> URIStart, and uri is URIStart+Tail, return Name:Tail;
129: otherwise return uri unchanged. If there are multiple applicable mappings
130: available, the "most recent" is chosen if that is possible, otherwise
131: one is picked "at random".
132: <p>
133: The result is primarily intended for human convenience: it is <i>not</i>
134: necessarily a legal QName, as Tail need not be a legal NCName; and there's
135: no way to tell a shortened name from a URI with an unusual scheme.
136:
137: @param uri the URI string to try and prefix-compress
138: @return the shortened form if possible, otherwise the unchanged argument
139: */
140: String shortForm(String uri);
141:
142: /**
143: Answer a qname with the expansion of the given uri, or null if no such qname
144: can be constructed using the mapping's prefixes.
145: */
146: String qnameFor(String uri);
147:
148: /**
149: Lock the PrefixMapping so that changes can no longer be made to it.
150: Primarily intended to lock Standard against mutation.
151:
152: @return this mapping, locked against changes
153: */
154: PrefixMapping lock();
155:
156: /**
157: Exception to throw when the prefix argument to setNsPrefix is
158: illegal for some reason.
159: */
160: public static class IllegalPrefixException extends JenaException {
161: public IllegalPrefixException(String prefixName) {
162: super (prefixName);
163: }
164: }
165:
166: /**
167: Exception to throw when trying to update a locked PrefixMapping.
168: */
169: public static class JenaLockedException extends JenaException {
170: public JenaLockedException(PrefixMapping pm) {
171: super (pm.toString());
172: }
173: }
174:
175: /**
176: Factory class to create an unspecified kind of PrefixMapping.
177: */
178: public static class Factory {
179: public static PrefixMapping create() {
180: return new PrefixMappingImpl();
181: }
182: }
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
189: .create().setNsPrefix("rdfs", RDFS.getURI()).setNsPrefix(
190: "rdf", RDF.getURI()).setNsPrefix("dc", DC.getURI())
191: .setNsPrefix("owl", OWL.getURI()).setNsPrefix("xsd",
192: XSD.getURI()).lock();
193:
194: /**
195: A PrefixMapping built on Standard with some extras
196: */
197: public static final PrefixMapping Extended = PrefixMapping.Factory
198: .create().setNsPrefixes(Standard).setNsPrefix("daml",
199: DAMLVocabulary.NAMESPACE_DAML_2001_03_URI)
200: .setNsPrefix("rss", RSS.getURI()).setNsPrefix("vcard",
201: VCARD.getURI()).setNsPrefix("jms",
202: JenaModelSpec.getURI()).setNsPrefix("ja",
203: JA.getURI()).setNsPrefix("eg",
204: "http://www.example.org/").lock();
205:
206: /**
207: Answer true iff this prefix-mappings are equal, that is, map the same
208: prefixes to the same URIs; same as
209: <blockquote>
210: this.getNsPrefixMap().equals( other.getNsPrefixMap() )
211: </blockquote>
212: except that it may avoid unnecessary Map creations.
213: */
214: boolean samePrefixMappingAs(PrefixMapping other);
215: }
216:
217: /*
218: (c) Copyright 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
219: All rights reserved.
220:
221: Redistribution and use in source and binary forms, with or without
222: modification, are permitted provided that the following conditions
223: are met:
224:
225: 1. Redistributions of source code must retain the above copyright
226: notice, this list of conditions and the following disclaimer.
227:
228: 2. Redistributions in binary form must reproduce the above copyright
229: notice, this list of conditions and the following disclaimer in the
230: documentation and/or other materials provided with the distribution.
231:
232: 3. The name of the author may not be used to endorse or promote products
233: derived from this software without specific prior written permission.
234:
235: THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
236: IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
237: OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
238: IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
239: INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
240: NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
241: DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
242: THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
243: (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
244: THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
245: */
|