jena-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a...@apache.org
Subject jena git commit: JENA-833 : Javadoc for ConNeg
Date Sat, 20 Dec 2014 19:13:21 GMT
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 <andy@apache.org>
Authored: Sat Dec 20 19:13:02 2014 +0000
Committer: Andy Seaborne <andy@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)
     {


Mime
View raw message