001: /*
002: * Copyright Aduna (http://www.aduna-software.com/) (c) 1997-2006.
003: *
004: * Licensed under the Aduna BSD-style license.
005: */
006: package org.openrdf.http.protocol;
007:
008: import org.openrdf.OpenRDFUtil;
009: import org.openrdf.model.Resource;
010: import org.openrdf.model.URI;
011: import org.openrdf.model.Value;
012: import org.openrdf.model.ValueFactory;
013: import org.openrdf.rio.ntriples.NTriplesUtil;
014:
015: public abstract class Protocol {
016:
017: /**
018: * Protocol version.
019: */
020: public static final String VERSION = "4";
021:
022: /**
023: * Parameter name for the 'subject' parameter of a statement query.
024: */
025: public static final String SUBJECT_PARAM_NAME = "subj";
026:
027: /**
028: * Parameter name for the 'predicate' parameter of a statement query.
029: */
030: public static final String PREDICATE_PARAM_NAME = "pred";
031:
032: /**
033: * Parameter name for the 'object' parameter of statement query.
034: */
035: public static final String OBJECT_PARAM_NAME = "obj";
036:
037: /**
038: * Parameter name for the 'includeInferred' parameter.
039: */
040: public static final String INCLUDE_INFERRED_PARAM_NAME = "infer";
041:
042: /**
043: * Parameter name for the context parameter.
044: */
045: public static final String CONTEXT_PARAM_NAME = "context";
046:
047: /**
048: * Parameter value for the NULL context.
049: */
050: public static final String NULL_PARAM_VALUE = "null";
051:
052: /**
053: * Parameter name for the base-URI parameter.
054: */
055: public static final String BASEURI_PARAM_NAME = "baseURI";
056:
057: /**
058: * Parameter name for the query parameter.
059: */
060: public static final String QUERY_PARAM_NAME = "query";
061:
062: /**
063: * Parameter name for the query language parameter.
064: */
065: public static final String QUERY_LANGUAGE_PARAM_NAME = "queryLn";
066:
067: /**
068: * Parameter name for the default graph URI parameter.
069: */
070: public static final String DEFAULT_GRAPH_PARAM_NAME = "default-graph-uri";
071:
072: /**
073: * Parameter name for the named graph URI parameter.
074: */
075: public static final String NAMED_GRAPH_PARAM_NAME = "named-graph-uri";
076:
077: /**
078: * Parameter name for the Accept parameter (may also be used as the name of
079: * the Accept HTTP header).
080: */
081: public static final String ACCEPT_PARAM_NAME = "Accept";
082:
083: /**
084: * Relative location of the protocol resource.
085: */
086: public static final String PROTOCOL = "protocol";
087:
088: /**
089: * Relative location of the config resource.
090: */
091: public static final String CONFIG = "config";
092:
093: /**
094: * Relative location of the repository list resource.
095: */
096: public static final String REPOSITORIES = "repositories";
097:
098: /**
099: * Relative location of the statement list resource of a repository.
100: */
101: public static final String STATEMENTS = "statements";
102:
103: /**
104: * Relative location of the context list resource of a repository.
105: */
106: public static final String CONTEXTS = "contexts";
107:
108: /**
109: * Relative location of the namespaces list resource of a repository.
110: */
111: public static final String NAMESPACES = "namespaces";
112:
113: /**
114: * Parameter prefix for query-external variable bindings.
115: */
116: public static final String BINDING_PREFIX = "$";
117:
118: /**
119: * Relative location of the 'size' resource of a repository.
120: */
121: public static final String SIZE = "size";
122:
123: /**
124: * MIME type for transactions: <tt>application/x-rdftransaction</tt>.
125: */
126: public static final String TXN_MIME_TYPE = "application/x-rdftransaction";
127:
128: /**
129: * MIME type for www forms: <tt>application/x-www-form-urlencoded</tt>.
130: */
131: public static final String FORM_MIME_TYPE = "application/x-www-form-urlencoded";
132:
133: private static String getServerDir(String serverLocation) {
134: if (serverLocation.endsWith("/")) {
135: return serverLocation;
136: } else {
137: return serverLocation + "/";
138: }
139: }
140:
141: /**
142: * Get the location of the protocol resource on the specified server.
143: *
144: * @param serverLocation
145: * the base location of a server implementing this REST protocol.
146: * @return the location of the protocol resource on the specified server
147: */
148: public static final String getProtocolLocation(String serverLocation) {
149: return getServerDir(serverLocation) + PROTOCOL;
150: }
151:
152: /**
153: * Get the location of the server configuration resource on the specified
154: * server.
155: *
156: * @param serverLocation
157: * the base location of a server implementing this REST protocol.
158: * @return the location of the server configuration resource on the specified
159: * server
160: */
161: public static final String getConfigLocation(String serverLocation) {
162: return getServerDir(serverLocation) + CONFIG;
163: }
164:
165: /**
166: * Get the location of the repository list resource on the specified server.
167: *
168: * @param serverLocation
169: * the base location of a server implementing this REST protocol.
170: * @return the location of the repository list resource on the specified
171: * server
172: */
173: public static final String getRepositoriesLocation(
174: String serverLocation) {
175: return getServerDir(serverLocation) + REPOSITORIES;
176: }
177:
178: /**
179: * Get the location of a specific repository resource on the specified
180: * server.
181: *
182: * @param serverLocation
183: * the base location of a server implementing this REST protocol.
184: * @param repositoryID
185: * the ID of the repository
186: * @return the location of a specific repository resource on the specified
187: * server
188: */
189: public static final String getRepositoryLocation(
190: String serverLocation, String repositoryID) {
191: return getRepositoriesLocation(serverLocation) + "/"
192: + repositoryID;
193: }
194:
195: /**
196: * Get the location of the statements resource for a specific repository.
197: *
198: * @param repositoryLocation
199: * the location of a repositor implementing this REST protocol.
200: * @return the location of the statements resource for the specified
201: * repository
202: */
203: public static final String getStatementsLocation(
204: String repositoryLocation) {
205: return repositoryLocation + "/" + STATEMENTS;
206: }
207:
208: /**
209: * Get the location of the contexts lists resource for a specific repository.
210: *
211: * @param repositoryLocation
212: * the location of a repository implementing this REST protocol.
213: * @return the location of the contexts lists resource for the specified
214: * repository
215: */
216: public static final String getContextsLocation(
217: String repositoryLocation) {
218: return repositoryLocation + "/" + CONTEXTS;
219: }
220:
221: /**
222: * Get the location of the namespaces lists resource for a specific
223: * repository on the specified server.
224: *
225: * @param serverLocation
226: * the base location of a server implementing this REST protocol.
227: * @param repositoryID
228: * the ID of the repository
229: * @return the location of the namespaces lists resource for a specific
230: * repository on the specified server
231: */
232: public static final String getNamespacesLocation(
233: String repositoryLocation) {
234: return repositoryLocation + "/" + NAMESPACES;
235: }
236:
237: /**
238: * Get the location of the namespace with the specified prefix for a specific
239: * repository on the specified server.
240: *
241: * @param serverLocation
242: * the base location of a server implementing this REST protocol.
243: * @param repositoryID
244: * the ID of the repository
245: * @param prefix
246: * the namespace prefix
247: * @return the location of the the namespace with the specified prefix for a
248: * specific repository on the specified server
249: */
250: public static final String getNamespacePrefixLocation(
251: String repositoryLocation, String prefix) {
252: return getNamespacesLocation(repositoryLocation) + "/" + prefix;
253: }
254:
255: /**
256: * Get the location of the 'size' resource for a specific repository on the
257: * specified server.
258: *
259: * @param serverLocation
260: * the base location of a server implementing this REST protocol.
261: * @param repositoryID
262: * the ID of the repository
263: * @return the location of the 'size' resource for a specific repository on
264: * the specified server
265: */
266: public static final String getSizeLocation(String repositoryLocation) {
267: return repositoryLocation + "/" + SIZE;
268: }
269:
270: /**
271: * Encodes a value for use in a URL.
272: *
273: * @param value
274: * The value to encode, possibly <tt>null</tt>.
275: * @return The N-Triples representation of the supplied value, or
276: * {@link #NULL_PARAM_VALUE} if the supplied value was <tt>null</tt>.
277: */
278: public static String encodeValue(Value value) {
279: return NTriplesUtil.toNTriplesString(value);
280: }
281:
282: /**
283: * Decode a previously encoded value.
284: *
285: * @param encodedValue
286: * the encoded value
287: * @param valueFactory
288: * the factory to use for constructing the Value
289: * @return the decoded Value
290: * @see encodeValue(org.openrdf.model.Value)
291: */
292: public static Value decodeValue(String encodedValue,
293: ValueFactory valueFactory) {
294: if (encodedValue != null) {
295: return NTriplesUtil.parseValue(encodedValue, valueFactory);
296: }
297:
298: return null;
299: }
300:
301: /**
302: * Decode a previously encoded Resource.
303: *
304: * @param encodedValue
305: * the encoded value
306: * @param valueFactory
307: * the factory to use for constructing the Resource
308: * @return the decoded Resource
309: * @see encodeValue(org.openrdf.model.Value)
310: */
311: public static Resource decodeResource(String encodedValue,
312: ValueFactory valueFactory) {
313: if (encodedValue != null) {
314: return NTriplesUtil.parseResource(encodedValue,
315: valueFactory);
316: }
317:
318: return null;
319: }
320:
321: /**
322: * Decode a previously encoded URI.
323: *
324: * @param encodedValue
325: * the encoded value
326: * @param valueFactory
327: * the factory to use for constructing the URI
328: * @return the decoded URI
329: * @see encodeValue(org.openrdf.model.Value)
330: */
331: public static URI decodeURI(String encodedValue,
332: ValueFactory valueFactory) {
333: if (encodedValue != null) {
334: return NTriplesUtil.parseURI(encodedValue, valueFactory);
335: }
336:
337: return null;
338: }
339:
340: /**
341: * Encodes a context resource for use in a URL.
342: *
343: * @param value
344: * The resource to encode, possibly <tt>null</tt>.
345: * @return The N-Triples representation of the supplied resource, or
346: * {@link #NULL_PARAM_VALUE} if the supplied value was <tt>null</tt>.
347: */
348: public static String encodeContext(Resource context) {
349: if (context == null) {
350: return Protocol.NULL_PARAM_VALUE;
351: } else {
352: return encodeValue(context);
353: }
354: }
355:
356: /**
357: * Decode a previously encoded context Resource.
358: *
359: * @param encodedValue
360: * the encoded value
361: * @param valueFactory
362: * the factory to use for constructing the Resource
363: * @return the decoded Resource, or null if the encoded values was null or
364: * equal to {@link #NULL_PARAM_VALUE}
365: */
366: public static Resource decodeContext(String encodedValue,
367: ValueFactory valueFactory) {
368: if (encodedValue == null) {
369: return null;
370: } else if (NULL_PARAM_VALUE.equals(encodedValue)) {
371: return null;
372: } else {
373: return decodeResource(encodedValue, valueFactory);
374: }
375: }
376:
377: /**
378: * Encode context resources for use in a URL.
379: *
380: * @param contexts
381: * the contexts to encode, must not be <tt>null</tt>.
382: * @return the encoded contexts
383: * @throws IllegalArgumentException
384: * If the <tt>contexts</tt> is <tt>null</tt>.
385: */
386: public static String[] encodeContexts(Resource... contexts) {
387: OpenRDFUtil.verifyContextNotNull(contexts);
388:
389: String[] result = new String[contexts.length];
390: for (int index = 0; index < contexts.length; index++) {
391: result[index] = encodeContext(contexts[index]);
392: }
393:
394: return result;
395: }
396:
397: /**
398: * Decode previously encoded contexts.
399: *
400: * @param encodedValues
401: * the encoded values
402: * @param valueFactory
403: * the factory to use for constructing the Resources
404: * @return the decoded Resources, or an empty array if the supplied
405: * <tt>encodedValues</tt> was <tt>null</tt>.
406: */
407: public static Resource[] decodeContexts(String[] encodedValues,
408: ValueFactory valueFactory) {
409: Resource[] result;
410:
411: if (encodedValues == null) {
412: result = new Resource[0];
413: } else {
414: result = new Resource[encodedValues.length];
415: for (int index = 0; index < encodedValues.length; index++) {
416: result[index] = decodeContext(encodedValues[index],
417: valueFactory);
418: }
419: }
420:
421: return result;
422: }
423: }
|