You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by an...@apache.org on 2014/12/20 20:13:21 UTC
jena git commit: JENA-833 : Javadoc for ConNeg
Repository: jena
Updated Branches:
refs/heads/master f1689a037 -> bc14bb549
JENA-833 : Javadoc for ConNeg
Project: http://git-wip-us.apache.org/repos/asf/jena/repo
Commit: http://git-wip-us.apache.org/repos/asf/jena/commit/bc14bb54
Tree: http://git-wip-us.apache.org/repos/asf/jena/tree/bc14bb54
Diff: http://git-wip-us.apache.org/repos/asf/jena/diff/bc14bb54
Branch: refs/heads/master
Commit: bc14bb54982bfdd84168589c87449d54b819ce8a
Parents: f1689a0
Author: Andy Seaborne <an...@apache.org>
Authored: Sat Dec 20 19:13:02 2014 +0000
Committer: Andy Seaborne <an...@apache.org>
Committed: Sat Dec 20 19:13:02 2014 +0000
----------------------------------------------------------------------
.../org/apache/jena/fuseki/conneg/ConNeg.java | 88 ++++++++++++++++++-
.../org/apache/jena/fuseki/conneg/ConNeg.java | 89 +++++++++++++++++++-
2 files changed, 171 insertions(+), 6 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/jena/blob/bc14bb54/jena-fuseki/src/main/java/org/apache/jena/fuseki/conneg/ConNeg.java
----------------------------------------------------------------------
diff --git a/jena-fuseki/src/main/java/org/apache/jena/fuseki/conneg/ConNeg.java b/jena-fuseki/src/main/java/org/apache/jena/fuseki/conneg/ConNeg.java
index 25e6a4f..b448c6c 100644
--- a/jena-fuseki/src/main/java/org/apache/jena/fuseki/conneg/ConNeg.java
+++ b/jena-fuseki/src/main/java/org/apache/jena/fuseki/conneg/ConNeg.java
@@ -28,26 +28,65 @@ import org.apache.jena.atlas.web.MediaType ;
import org.slf4j.Logger ;
import org.slf4j.LoggerFactory ;
+/**
+ * <p>Content negotiation is a mechanism defined in the HTTP specification
+ * that makes it possible to serve different versions of a document
+ * (or more generally, a resource representation) at the same URI, so that
+ * user agents can specify which version fit their capabilities the best.</p>
+ *
+ * <p>ConNeg is used in Fuseki to help matching the content media type requested
+ * by the user, against the list of offered media types.</p>
+ *
+ * @see <a href="http://en.wikipedia.org/wiki/Content_negotiation">http://en.wikipedia.org/wiki/Content_negotiation</a>
+ * @see <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1">http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1</a>
+ */
public class ConNeg
{
private static Logger log = LoggerFactory.getLogger(ConNeg.class) ;
// See riot.ContentNeg (client side).
// http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
+ /**
+ * Parses the content type. It splits the string by semi-colon and finds the
+ * other features such as the "q" quality factor. For a complete documentation
+ * on how the parsing happens, see
+ * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1">http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1</a>.
+ *
+ * @param contentType content type string
+ * @return parsed media type
+ */
static public MediaType parse(String contentType)
{
try {
return MediaType.create(contentType) ;
} catch (RuntimeException ex) { return null ; }
}
-
+
+ /**
+ * <p>Creates a {@link AcceptList} with the given HTTP header string and
+ * uses the {@link AcceptList#match(MediaType)} method to decide which
+ * media type matches the HTTP header string.</p>
+ *
+ * <p>The <em>q</em> quality factor is used to decide which choice is the best
+ * match.</p>
+ *
+ * @param headerString HTTP header string
+ * @param offerList accept list
+ * @return matched media type
+ */
static public MediaType match(String headerString, AcceptList offerList)
{
AcceptList l = new AcceptList(headerString) ;
return AcceptList.match(l, offerList) ;
}
- /** Match a single media type against a header string */
+ /**
+ * Match a single media type against a header string.
+ *
+ * @param headerString HTTP header string
+ * @param mediaRangeStr Semi-colon separated list of media types
+ * @return the matched media type or <code>null</code> if there was no match
+ */
public static String match(String headerString, String mediaRangeStr)
{
AcceptList l = new AcceptList(headerString) ;
@@ -57,7 +96,14 @@ public class ConNeg
return null ;
return m.toHeaderString() ;
}
-
+
+ /**
+ * Split and trims a string using a given regex.
+ *
+ * @param s string
+ * @param splitStr given regex
+ * @return an array with the trimmed strings found
+ */
/*package*/ static String[] split(String s, String splitStr)
{
String[] x = s.split(splitStr,2) ;
@@ -68,6 +114,16 @@ public class ConNeg
return x ;
}
+ /**
+ * <p>Chooses the charset by using the Accept-Charset HTTP header.</p>
+ *
+ * <p>See {@link ConNeg#choose(String, AcceptList, MediaType)}.</p>
+ *
+ * @param httpRequest HTTP request
+ * @param myPrefs accept list
+ * @param defaultMediaType default media type
+ * @return media type chosen
+ */
public static MediaType chooseCharset(HttpServletRequest httpRequest,
AcceptList myPrefs,
MediaType defaultMediaType)
@@ -84,6 +140,17 @@ public class ConNeg
return item ;
}
+ /**
+ * <p>Choose the content media type by extracting the Accept HTTP header from
+ * the HTTP request and choosing
+ * (see {@link ConNeg#choose(String, AcceptList, MediaType)}) a content media
+ * type that matches the header.</p>
+ *
+ * @param httpRequest HTTP request
+ * @param myPrefs accept list
+ * @param defaultMediaType default media type
+ * @return media type chosen
+ */
public static MediaType chooseContentType(HttpServletRequest httpRequest,
AcceptList myPrefs,
MediaType defaultMediaType)
@@ -100,6 +167,21 @@ public class ConNeg
return item ;
}
+ /**
+ * <p>This method receives a HTTP header string, an {@link AcceptList} and a
+ * default {@link MediaType}.</p>
+ *
+ * <p>If the header string is null, it returns the given default MediaType.</p>
+ *
+ * <p>Otherwise it builds an {@link AcceptList} object with the header string
+ * and uses it to match against the given MediaType.</p>
+ *
+ * @param headerString HTTP header string
+ * @param myPrefs accept list
+ * @param defaultMediaType default media type
+ * @return a media type or <code>null</code> if none matched or if the
+ * HTTP header string and the default media type are <code>null</code>.
+ */
private static MediaType choose(String headerString, AcceptList myPrefs,
MediaType defaultMediaType)
{
http://git-wip-us.apache.org/repos/asf/jena/blob/bc14bb54/jena-fuseki2/src/main/java/org/apache/jena/fuseki/conneg/ConNeg.java
----------------------------------------------------------------------
diff --git a/jena-fuseki2/src/main/java/org/apache/jena/fuseki/conneg/ConNeg.java b/jena-fuseki2/src/main/java/org/apache/jena/fuseki/conneg/ConNeg.java
index 41cfd07..672d2b9 100644
--- a/jena-fuseki2/src/main/java/org/apache/jena/fuseki/conneg/ConNeg.java
+++ b/jena-fuseki2/src/main/java/org/apache/jena/fuseki/conneg/ConNeg.java
@@ -28,26 +28,66 @@ import org.apache.jena.atlas.web.MediaType ;
import org.slf4j.Logger ;
import org.slf4j.LoggerFactory ;
+/**
+ * <p>Content negotiation is a mechanism defined in the HTTP specification
+ * that makes it possible to serve different versions of a document
+ * (or more generally, a resource representation) at the same URI, so that
+ * user agents can specify which version fit their capabilities the best.</p>
+ *
+ * <p>ConNeg is used in Fuseki to help matching the content media type requested
+ * by the user, against the list of offered media types.</p>
+ *
+ * @see <a href="http://en.wikipedia.org/wiki/Content_negotiation">http://en.wikipedia.org/wiki/Content_negotiation</a>
+ * @see <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1">http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1</a>
+ */
public class ConNeg
{
+ // Logger
private static Logger log = LoggerFactory.getLogger(ConNeg.class) ;
// See riot.ContentNeg (client side).
// http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
+ /**
+ * Parses the content type. It splits the string by semi-colon and finds the
+ * other features such as the "q" quality factor. For a complete documentation
+ * on how the parsing happens, see
+ * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1">http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1</a>.
+ *
+ * @param contentType content type string
+ * @return parsed media type
+ */
static public MediaType parse(String contentType)
{
try {
return MediaType.create(contentType) ;
} catch (RuntimeException ex) { return null ; }
}
-
+
+ /**
+ * <p>Creates a {@link AcceptList} with the given HTTP header string and
+ * uses the {@link AcceptList#match(MediaType)} method to decide which
+ * media type matches the HTTP header string.</p>
+ *
+ * <p>The <em>q</em> quality factor is used to decide which choice is the best
+ * match.</p>
+ *
+ * @param headerString HTTP header string
+ * @param offerList accept list
+ * @return matched media type
+ */
static public MediaType match(String headerString, AcceptList offerList)
{
AcceptList l = new AcceptList(headerString) ;
return AcceptList.match(l, offerList) ;
}
- /** Match a single media type against a header string */
+ /**
+ * Match a single media type against a header string.
+ *
+ * @param headerString HTTP header string
+ * @param mediaRangeStr Semi-colon separated list of media types
+ * @return the matched media type or <code>null</code> if there was no match
+ */
public static String match(String headerString, String mediaRangeStr)
{
AcceptList l = new AcceptList(headerString) ;
@@ -57,7 +97,14 @@ public class ConNeg
return null ;
return m.toHeaderString() ;
}
-
+
+ /**
+ * Split and trims a string using a given regex.
+ *
+ * @param s string
+ * @param splitStr given regex
+ * @return an array with the trimmed strings found
+ */
/*package*/ static String[] split(String s, String splitStr)
{
String[] x = s.split(splitStr,2) ;
@@ -68,6 +115,16 @@ public class ConNeg
return x ;
}
+ /**
+ * <p>Chooses the charset by using the Accept-Charset HTTP header.</p>
+ *
+ * <p>See {@link ConNeg#choose(String, AcceptList, MediaType)}.</p>
+ *
+ * @param httpRequest HTTP request
+ * @param myPrefs accept list
+ * @param defaultMediaType default media type
+ * @return media type chosen
+ */
public static MediaType chooseCharset(HttpServletRequest httpRequest,
AcceptList myPrefs,
MediaType defaultMediaType)
@@ -84,6 +141,17 @@ public class ConNeg
return item ;
}
+ /**
+ * <p>Choose the content media type by extracting the Accept HTTP header from
+ * the HTTP request and choosing
+ * (see {@link ConNeg#choose(String, AcceptList, MediaType)}) a content media
+ * type that matches the header.</p>
+ *
+ * @param httpRequest HTTP request
+ * @param myPrefs accept list
+ * @param defaultMediaType default media type
+ * @return media type chosen
+ */
public static MediaType chooseContentType(HttpServletRequest httpRequest,
AcceptList myPrefs,
MediaType defaultMediaType)
@@ -100,6 +168,21 @@ public class ConNeg
return item ;
}
+ /**
+ * <p>This method receives a HTTP header string, an {@link AcceptList} and a
+ * default {@link MediaType}.</p>
+ *
+ * <p>If the header string is null, it returns the given default MediaType.</p>
+ *
+ * <p>Otherwise it builds an {@link AcceptList} object with the header string
+ * and uses it to match against the given MediaType.</p>
+ *
+ * @param headerString HTTP header string
+ * @param myPrefs accept list
+ * @param defaultMediaType default media type
+ * @return a media type or <code>null</code> if none matched or if the
+ * HTTP header string and the default media type are <code>null</code>.
+ */
private static MediaType choose(String headerString, AcceptList myPrefs,
MediaType defaultMediaType)
{