jena-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a...@apache.org
Subject [2/2] git commit: Port comments provided in JENA-799 to Fuseki2.
Date Sun, 12 Oct 2014 09:59:12 GMT
Port comments provided in JENA-799 to Fuseki2.

Project: http://git-wip-us.apache.org/repos/asf/jena/repo
Commit: http://git-wip-us.apache.org/repos/asf/jena/commit/edae58f2
Tree: http://git-wip-us.apache.org/repos/asf/jena/tree/edae58f2
Diff: http://git-wip-us.apache.org/repos/asf/jena/diff/edae58f2

Branch: refs/heads/master
Commit: edae58f291eb26cbf2709b3559dcafb9a5a8869f
Parents: 053b432
Author: Andy Seaborne <andy@apache.org>
Authored: Sun Oct 12 10:59:02 2014 +0100
Committer: Andy Seaborne <andy@apache.org>
Committed: Sun Oct 12 10:59:02 2014 +0100

----------------------------------------------------------------------
 .../apache/jena/fuseki/servlets/ActionBase.java | 49 +++++++++++++--
 .../apache/jena/fuseki/servlets/ActionLib.java  | 18 ++++--
 .../jena/fuseki/servlets/ActionSPARQL.java      | 33 +++++++++-
 .../apache/jena/fuseki/servlets/HttpAction.java | 66 +++++++++++++++++---
 .../jena/fuseki/servlets/SPARQL_Query.java      | 58 ++++++++++++++---
 .../jena/fuseki/servlets/ServletBase.java       |  4 +-
 6 files changed, 196 insertions(+), 32 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/jena/blob/edae58f2/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ActionBase.java
----------------------------------------------------------------------
diff --git a/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ActionBase.java b/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ActionBase.java
index 7f59c12..6bfd25b 100644
--- a/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ActionBase.java
+++ b/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ActionBase.java
@@ -55,9 +55,12 @@ public abstract class ActionBase extends ServletBase
         //super.init() ;
     }
     
-    // Common framework for handling HTTP requests
+    /**
+     * Common framework for handling HTTP requests.
+     * @param request
+     * @param response
+     */
     protected void doCommon(HttpServletRequest request, HttpServletResponse response)
-    //throws ServletException, IOException
     {
         try {
             long id = allocRequestId(request, response);
@@ -105,26 +108,46 @@ public abstract class ActionBase extends ServletBase
 
     // ---- Operation lifecycle
 
-    /** Return a fresh WebAction for this request */
+    /**
+     * Returns a fresh HTTP Action for this request.
+     * @param id the Request ID
+     * @param request HTTP request
+     * @param response HTTP response
+     * @return a new HTTP Action
+     */
     protected HttpAction allocHttpAction(long id, HttpServletRequest request, HttpServletResponse
response) {
         // Need a way to set verbose logging on a per servlet and per request basis. 
         return new HttpAction(id, log, request, response, Fuseki.verboseLogging) ;
     }
 
-    // Default start/finish steps. 
+    /**
+     * Begin handling an {@link HttpAction}  
+     * @param action
+     */
     protected final void startRequest(HttpAction action) {
         action.startRequest() ;
     }
     
+    /**
+     * Stop handling an {@link HttpAction}  
+     */
     protected final void finishRequest(HttpAction action) {
         action.finishRequest() ;
     }
     
+    /**
+     * Archives the HTTP Action.
+     * @param action HTTP Action
+     * @see HttpAction#minimize()
+     */
     private void archiveHttpAction(HttpAction action) {
         action.minimize() ;
     }
 
-    /** execution point */
+    /**
+     * Execute this request, which maybe a admin operation or a client request. 
+     * @param action HTTP Action
+     */
     protected abstract void execCommonWorker(HttpAction action) ;
     
     /** Extract the name after the container name (serverlet name).
@@ -211,6 +234,22 @@ public abstract class ActionBase extends ServletBase
             log.info(String.format("[%d] %d %s (%s) ", action.id, action.statusCode, action.message,
timeStr)) ;
     }
 
+    /**
+     * <p>Given a time point, return the time as a milli second string if it is less
than 1000,
+     * otherwise return a seconds string.</p>
+     * <p>It appends a 'ms' suffix when using milli seconds,
+     *  and <i>s</i> for seconds.</p>
+     * <p>For instance: </p>
+     * <ul>
+     * <li>10 emits 10 ms</li>
+     * <li>999 emits 999 ms</li>
+     * <li>1000 emits 1.000 s</li>
+     * <li>10000 emits 10.000 s</li>
+     * </ul>
+     * @param time the time in milliseconds
+     * @return the time as a display string
+     */
+
     private static String fmtMillis(long time) {
         // Millis only? seconds only?
         if ( time < 1000 )

http://git-wip-us.apache.org/repos/asf/jena/blob/edae58f2/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ActionLib.java
----------------------------------------------------------------------
diff --git a/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ActionLib.java b/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ActionLib.java
index 6d0ed79..182b46e 100644
--- a/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ActionLib.java
+++ b/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ActionLib.java
@@ -30,10 +30,15 @@ import org.apache.jena.fuseki.server.DataAccessPointRegistry ;
 /** Operations related to servlets */
 
 public class ActionLib {
-    public static String mapRequestToDataset(HttpAction action) {
-        String uri = action.getActionURI() ;
-        return mapActionRequestToDataset(uri) ;
-    }
+    /**
+     * A possible implementation for {@link ActionSPARQL#mapRequestToDataset}
+     * that assumes the form /dataset/service.
+     * @param action the request
+     * @return the dataset
+     */    public static String mapRequestToDataset(HttpAction action) {
+         String uri = action.getActionURI() ;
+         return mapActionRequestToDataset(uri) ;
+     }
     
     /** Map request to uri in the registry.
      *  A possible implementation for mapRequestToDataset(String)
@@ -101,6 +106,11 @@ public class ActionLib {
         return ds ;
     }
 
+    /** Calculate the fill URL including query string
+     * for the HTTP request. This may be quite long.
+     * @param request HttpServletRequest
+     * @return String The full URL, including query string.
+     */
     public static String wholeRequestURL(HttpServletRequest request) {
         StringBuffer sb = request.getRequestURL() ;
         String queryString = request.getQueryString() ;

http://git-wip-us.apache.org/repos/asf/jena/blob/edae58f2/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ActionSPARQL.java
----------------------------------------------------------------------
diff --git a/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ActionSPARQL.java
b/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ActionSPARQL.java
index a0aa32c..08cf565 100644
--- a/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ActionSPARQL.java
+++ b/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ActionSPARQL.java
@@ -44,6 +44,12 @@ public abstract class ActionSPARQL extends ActionBase
     protected abstract void validate(HttpAction action) ;
     protected abstract void perform(HttpAction action) ;
 
+    /**
+     * Executes common tasks, including mapping the request to the right dataset, setting
the dataset into the HTTP
+     * action, and retrieving the service for the dataset requested. Finally, it calls the
+     * {@link #executeAction(HttpAction)} method, which executes the HTTP Action life cycle.
+     * @param action HTTP Action
+     */
     @Override
     protected void execCommonWorker(HttpAction action) {
         DataAccessPoint dataAccessPoint ;
@@ -77,11 +83,27 @@ public abstract class ActionSPARQL extends ActionBase
         executeAction(action) ;
     }
 
-    // Execute - allow interception before stats added.
+    /** Execute a SPARQL request. Statistics have not been adjusted at this point.
+     * 
+     * @param action
+     */
     protected void executeAction(HttpAction action) {
         executeLifecycle(action) ;
     }
     
+    /** 
+     * Standard execution lifecycle for a SPARQL Request.
+     * <ul>
+     * <li>{@link #startRequest(HttpAction)}</li>
+     * <li>initial statistics,</li>
+     * <li>{@link #validate(HttpAction)} request,</li>
+     * <li>{@link #perform(HttpAction)} request,</li>
+     * <li>completion/error statistics,</li>
+     * <li>{@link #finishRequest(HttpAction)}
+     * </ul>
+     * 
+     * @param action
+     */
     // This is the service request lifecycle.
     final
     protected void executeLifecycle(HttpAction action) {
@@ -118,8 +140,11 @@ public abstract class ActionSPARQL extends ActionBase
         }
     }
     
-    /** Map request to uri in the registry.
-     *  null means no mapping done (passthrough). 
+    /**
+     * Map request {@link HttpAction} to uri in the registry.
+     * A return of ull means no mapping done (passthrough).
+     * @param uri the URI
+     * @return the dataset
      */
     protected String mapRequestToDataset(HttpAction action) {
         return ActionLib.mapRequestToDataset(action) ;
@@ -133,11 +158,13 @@ public abstract class ActionSPARQL extends ActionBase
         return ActionLib.mapRequestToOperation(action, dataAccessPoint) ;
     }
 
+    /** Increment counter */
     protected static void incCounter(Counters counters, CounterName name) {
         if ( counters == null ) return ;
         incCounter(counters.getCounters(), name) ; 
     }
     
+    /** Decrement counter */
     protected static void decCounter(Counters counters, CounterName name) {
         if ( counters == null ) return ;
         decCounter(counters.getCounters(), name) ; 

http://git-wip-us.apache.org/repos/asf/jena/blob/edae58f2/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/HttpAction.java
----------------------------------------------------------------------
diff --git a/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/HttpAction.java b/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/HttpAction.java
index 990e0a1..1086848 100644
--- a/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/HttpAction.java
+++ b/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/HttpAction.java
@@ -30,10 +30,7 @@ import javax.servlet.http.HttpServletResponse ;
 import org.apache.jena.atlas.logging.Log ;
 import org.apache.jena.fuseki.Fuseki ;
 import org.apache.jena.fuseki.FusekiException ;
-import org.apache.jena.fuseki.server.DataAccessPoint ;
-import org.apache.jena.fuseki.server.DataService ;
-import org.apache.jena.fuseki.server.Endpoint ;
-import org.apache.jena.fuseki.server.RequestLog ;
+import org.apache.jena.fuseki.server.* ;
 import org.slf4j.Logger ;
 
 import com.hp.hpl.jena.query.ReadWrite ;
@@ -43,6 +40,10 @@ import com.hp.hpl.jena.sparql.core.DatasetGraphWithLock ;
 import com.hp.hpl.jena.sparql.core.DatasetGraphWrapper ;
 import com.hp.hpl.jena.sparql.core.Transactional ;
 
+/**
+ * HTTP action that represents the user request lifecycle. Its state is handled in the
+ * {@link ActionSPARQL#executeAction(HttpAction)} method.
+ */
 public class HttpAction
 {
     public final long id ;
@@ -92,6 +93,15 @@ public class HttpAction
     private final String actionURI ;
     private final String contextPath ;
     
+    /**
+     * Creates a new HTTP Action, using the HTTP request and response, and a given ID.
+     *
+     * @param id given ID
+     * @param log Logger for this action 
+     * @param request HTTP request
+     * @param response HTTP response
+     * @param verbose verbose flag
+     */
     public HttpAction(long id, Logger log, HttpServletRequest request, HttpServletResponse
response, boolean verbose) {
         this.id = id ;
         this.log = log ;
@@ -104,7 +114,18 @@ public class HttpAction
         this.actionURI = ActionLib.actionURI(request) ;
     }
 
-    /** Initialization after action creation during lifecycle setup */
+    /** Initialization after action creation during lifecycle setup.
+     * <p>Sets the action dataset. Setting will replace any existing {@link DataAccessPoint}
and {@link DataService},
+     * as the {@link DatasetGraph} of the current HTTP Action.</p>
+     *
+     * <p>Once it has updated its members, the HTTP Action will change its transactional
state and
+     * {@link Transactional} instance according to its base dataset graph.</p>
+     *
+     * @param dataAccessPoint {@link DataAccessPoint}
+     * @param dService {@link DataService}
+     * @see Transactional
+     */
+    
     public void setRequest(DataAccessPoint dataAccessPoint, DataService dService) {
         this.dataAccessPoint = dataAccessPoint ;
         if ( dataAccessPoint != null )
@@ -139,11 +160,27 @@ public class HttpAction
         this.datasetName = datasetUri ;
     }
     
+    /**
+     * Returns <code>true</code> iff the given {@link DatasetGraph} is an instance
of {@link Transactional},
+     * <code>false otherwise</code>.
+     *
+     * @param dsg a {@link DatasetGraph}
+     * @return <code>true</code> iff the given {@link DatasetGraph} is an instance
of {@link Transactional},
+     * <code>false otherwise</code>
+     */
     private static boolean isTransactional(DatasetGraph dsg) {
         return (dsg instanceof Transactional) ;
     }
 
-    private static DatasetGraph unwrap(DatasetGraph dsg) {
+    /**
+     * A {@link DatasetGraph} may contain other <strong>wrapped DatasetGraph's</strong>.
This method will return
+     * the first instance (including the argument to this method) that <strong>is not</strong>
an instance of
+     * {@link DatasetGraphWrapper}.
+     *
+     * @param dsg a {@link DatasetGraph}
+     * @return the first found {@link DatasetGraph} that is not an instance of {@link DatasetGraphWrapper}
+     */
+   private static DatasetGraph unwrap(DatasetGraph dsg) {
         while (dsg instanceof DatasetGraphWrapper) {
             dsg = ((DatasetGraphWrapper)dsg).getWrapped() ;
         }
@@ -151,24 +188,29 @@ public class HttpAction
     }
         
     /** This is the requestURI with the context path removed.
-     * It should be used internally for dispatch
+     *  It should be used internally for dispatch.
      */
     public String getActionURI() {
         return actionURI ;
     }
     
-    /** This is the requestURI with the context path removed.
-     * It should be used internally for dispatch
+    /** Get the context path.
      */
     public String getContextPath() {
         return contextPath ;
     }
-
+    
+    
+    /** Set the endpoint and endpoint name that this is an action for. 
+     * @param srvRef {@link Endpoint}
+     * @param endpointName
+     */
     public void setEndpoint(Endpoint srvRef, String endpointName) {
         this.endpoint = srvRef ; 
         this.endpointName = endpointName ;
     }
     
+    /** Get the endpoint for the action (may be null) . */
     public Endpoint getEndpoint() {
         return endpoint ; 
     }
@@ -250,6 +292,10 @@ public class HttpAction
         }
     }
     
+    /** If inside the transaction for the action, return the active {@link DatasetGraph},
+     *  otherwise return null.
+     * @return Current active {@link DatasetGraph}
+     */
     public final DatasetGraph getActiveDSG() {
         return activeDSG ;
     }

http://git-wip-us.apache.org/repos/asf/jena/blob/edae58f2/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/SPARQL_Query.java
----------------------------------------------------------------------
diff --git a/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/SPARQL_Query.java
b/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/SPARQL_Query.java
index 4fdafe7..11917a1 100644
--- a/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/SPARQL_Query.java
+++ b/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/SPARQL_Query.java
@@ -59,6 +59,11 @@ import com.hp.hpl.jena.rdf.model.Model ;
 import com.hp.hpl.jena.sparql.core.Prologue ;
 import com.hp.hpl.jena.sparql.resultset.SPARQLResult ;
 
+/** Handle SPARQL Query requests overt eh SPARQL Protocol. 
+ * Subclasses provide this algorithm with the actual dataset to query, whether
+ * a dataset hosted by this server ({@link SPARQL_QueryDataset}) or 
+ * speciifed in the protocol request ({@link SPARQL_QueryGeneral}).   
+ */ 
 public abstract class SPARQL_Query extends SPARQL_Protocol
 {
     private static final String QueryParseBase = Fuseki.BaseParserSPARQL ;
@@ -121,7 +126,10 @@ public abstract class SPARQL_Query extends SPARQL_Protocol
                                                             paramQueryRef, paramStyleSheet,
paramAccept, paramOutput1,
                                                             paramOutput2, paramCallback,
paramForceAccept, paramTimeout) ;
 
-    /** Called to validate arguments */
+    /**
+     * Validate the request, checking HTTP method and HTTP Parameters.
+     * @param action HTTP Action
+     */
     @Override
     protected void validate(HttpAction action) {
         String method = action.request.getMethod().toUpperCase(Locale.ROOT) ;
@@ -144,10 +152,17 @@ public abstract class SPARQL_Query extends SPARQL_Protocol
         // Query not yet parsed.
     }
 
-    /** Validate the request after checking HTTP method and HTTP Parameters */
+    /**
+     * Validate the request after checking HTTP method and HTTP Parameters.
+     * @param action HTTP Action
+     */
     protected abstract void validateRequest(HttpAction action) ;
 
-    /** Helper for validating request */
+    /**
+     * Helper method for validating request.
+     * @param request HTTP request
+     * @param params parameters in a collection of Strings
+     */
     protected void validateParams(HttpAction action, Collection<String> params) {
         HttpServletRequest request = action.request ;
         ContentType ct = FusekiLib.getContentType(request) ;
@@ -254,18 +269,32 @@ public abstract class SPARQL_Query extends SPARQL_Protocol
     /**
      * Check the query - if unacceptable, throw ActionErrorException or call
      * super.error
+     * @param action HTTP Action
+     * @param query  SPARQL Query
      */
     protected abstract void validateQuery(HttpAction action, Query query) ;
 
+    /** Create the {@link QueryExecution} for this operation.
+     * @param query
+     * @param dataset
+     * @return QueryExecution
+     */
     protected QueryExecution createQueryExecution(Query query, Dataset dataset) {
         return QueryExecutionFactory.create(query, dataset) ;
     }
 
-    protected SPARQLResult executeQuery(HttpAction action, QueryExecution qExec, Query query,
String queryStringLog) {
-        setAnyTimeouts(qExec, action) ;
+    /** Perform the {@link QueryExecution} once.
+     * @param action
+     * @param queryExecution
+     * @param query
+     * @param queryStringLog Informational string created from the initial query. 
+     * @return
+     */
+    protected SPARQLResult executeQuery(HttpAction action, QueryExecution queryExecution,
Query query, String queryStringLog) {
+        setAnyTimeouts(queryExecution, action) ;
 
         if ( query.isSelectType() ) {
-            ResultSet rs = qExec.execSelect() ;
+            ResultSet rs = queryExecution.execSelect() ;
 
             // Force some query execution now.
             //
@@ -285,19 +314,19 @@ public abstract class SPARQL_Query extends SPARQL_Protocol
         }
 
         if ( query.isConstructType() ) {
-            Model model = qExec.execConstruct() ;
+            Model model = queryExecution.execConstruct() ;
             action.log.info(format("[%d] exec/construct", action.id)) ;
             return new SPARQLResult(model) ;
         }
 
         if ( query.isDescribeType() ) {
-            Model model = qExec.execDescribe() ;
+            Model model = queryExecution.execDescribe() ;
             action.log.info(format("[%d] exec/describe", action.id)) ;
             return new SPARQLResult(model) ;
         }
 
         if ( query.isAskType() ) {
-            boolean b = qExec.execAsk() ;
+            boolean b = queryExecution.execAsk() ;
             action.log.info(format("[%d] exec/ask", action.id)) ;
             return new SPARQLResult(b) ;
         }
@@ -332,8 +361,19 @@ public abstract class SPARQL_Query extends SPARQL_Protocol
             qexec.setTimeout(desiredTimeout) ;
     }
 
+    /** Choose the dataset for this SPARQL Query request. 
+     * @param action
+     * @param query
+     * @param queryStringLog 
+     * @return {@link Dataset}
+     */
     protected abstract Dataset decideDataset(HttpAction action, Query query, String queryStringLog)
;
 
+    /** Ship the results to the remote caller.
+     * @param action
+     * @param result
+     * @param qPrologue
+     */
     protected void sendResults(HttpAction action, SPARQLResult result, Prologue qPrologue)
{
         if ( result.isResultSet() )
             ResponseResultSet.doResponseResultSet(action, result.getResultSet(), qPrologue)
;

http://git-wip-us.apache.org/repos/asf/jena/blob/edae58f2/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ServletBase.java
----------------------------------------------------------------------
diff --git a/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ServletBase.java b/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ServletBase.java
index 902a6e3..4ac30be 100644
--- a/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ServletBase.java
+++ b/jena-fuseki2/src/main/java/org/apache/jena/fuseki/servlets/ServletBase.java
@@ -28,7 +28,9 @@ import org.apache.jena.atlas.lib.StrUtils ;
 import org.apache.jena.fuseki.Fuseki ;
 import org.apache.jena.riot.web.HttpNames ;
 
-// Move statics to a lib (ActionLib?)
+/**
+ * Addition HTTP Servlet operations. 
+ */
 public abstract class ServletBase extends HttpServlet {
     public static final String METHOD_DELETE    = "DELETE" ;
     public static final String METHOD_HEAD      = "HEAD" ;


Mime
View raw message