Added javadoc and cleaning

Miel Vander Sande · Miel Vander Sande · commit 2846239b71c5 · 2016-01-12T10:13:09.000+01:00
diff --git a/src/org/linkeddatafragments/datasource/DataSourceBase.java b/src/org/linkeddatafragments/datasource/DataSourceBase.java
@@ -2,7 +2,7 @@
 
 /**
  *
- * @author mielvandersande
+ * @author Miel Vander Sande
  * @author Bart Hanssens
  */
 public abstract class DataSourceBase implements IDataSource {
diff --git a/src/org/linkeddatafragments/exceptions/DataSourceCreationException.java b/src/org/linkeddatafragments/exceptions/DataSourceCreationException.java
@@ -2,7 +2,7 @@
 
 /**
  *
- * @author mielvandersande
+ * @author Miel Vander Sande
  */
 public class DataSourceCreationException extends DataSourceException {
 
diff --git a/src/org/linkeddatafragments/exceptions/DataSourceException.java b/src/org/linkeddatafragments/exceptions/DataSourceException.java
@@ -4,7 +4,7 @@
 
 /**
  *
- * @author mielvandersande
+ * @author Miel Vander Sande
  */
 abstract public class DataSourceException extends Exception {
 
diff --git a/src/org/linkeddatafragments/exceptions/DataSourceNotFoundException.java b/src/org/linkeddatafragments/exceptions/DataSourceNotFoundException.java
@@ -2,7 +2,7 @@
 
 /**
  *
- * @author mielvandersande
+ * @author Miel Vander Sande
  */
 public class DataSourceNotFoundException extends DataSourceException {
 
diff --git a/src/org/linkeddatafragments/exceptions/NoRegisteredMimeTypesException.java b/src/org/linkeddatafragments/exceptions/NoRegisteredMimeTypesException.java
@@ -2,7 +2,7 @@
 
 /**
  *
- * @author mielvandersande
+ * @author Miel Vander Sande
  */
 public class NoRegisteredMimeTypesException extends Exception {
 
diff --git a/src/org/linkeddatafragments/exceptions/UnknownDataSourceTypeException.java b/src/org/linkeddatafragments/exceptions/UnknownDataSourceTypeException.java
@@ -2,7 +2,7 @@
 
 /**
  *
- * @author mielvandersande
+ * @author Miel Vander Sande
  */
 public class UnknownDataSourceTypeException extends DataSourceCreationException {
     
diff --git a/src/org/linkeddatafragments/fragments/ILinkedDataFragment.java b/src/org/linkeddatafragments/fragments/ILinkedDataFragment.java
@@ -1,13 +1,15 @@
 package org.linkeddatafragments.fragments;
 
+import java.io.Closeable;
+
 import com.hp.hpl.jena.rdf.model.StmtIterator;
 
 /**
  * Represents any possible Linked Data Fragment.
  *
  * @author <a href="http://olafhartig.de">Olaf Hartig</a>
  */
-public interface ILinkedDataFragment
+public interface ILinkedDataFragment extends Closeable
 {
     /**
      * Returns an iterator over the RDF data of this fragment (possibly only
diff --git a/src/org/linkeddatafragments/fragments/LinkedDataFragmentBase.java b/src/org/linkeddatafragments/fragments/LinkedDataFragmentBase.java
@@ -35,6 +35,14 @@ protected LinkedDataFragmentBase( final String fragmentURL,
         this.isLastPage = isLastPage;
     }
 
+    /**
+     * Does nothing. May be overridden by subclasses that hold some objects
+     * that need to be closed (such as iterators from the underlying data
+     * source).
+     */
+    @Override
+    public void close() {}
+
     @Override
     public boolean isPageOnly() {
         return true;
diff --git a/src/org/linkeddatafragments/servlet/LinkedDataFragmentServlet.java b/src/org/linkeddatafragments/servlet/LinkedDataFragmentServlet.java
@@ -137,16 +137,18 @@ private IDataSource getDataSource(HttpServletRequest request) throws DataSourceN
 
     @Override
     public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException {
+        ILinkedDataFragment fragment = null;
         try {
 
             // do conneg
             String bestMatch = MIMEParse.bestMatch(request.getHeader("Accept"));
 
-            // serialize the output
+            // set additional response headers
             response.setHeader("Server", "Linked Data Fragments Server");
             response.setContentType(bestMatch);
             response.setCharacterEncoding("utf-8");
             
+            // create a writer depending on the best matching mimeType
             ILinkedDataFragmentWriter writer = LinkedDataFragmentWriterFactory.create(config.getPrefixes(), dataSources, bestMatch);
             
             try {
@@ -157,8 +159,7 @@ public void doGet(HttpServletRequest request, HttpServletResponse response) thro
                         dataSource.getRequestParser()
                                   .parseIntoFragmentRequest( request, config );
 
-                final ILinkedDataFragment fragment =
-                        dataSource.getRequestProcessor()
+                fragment = dataSource.getRequestProcessor()
                                   .createRequestedFragment( ldfRequest );
 
                 writer.writeFragment(response.getOutputStream(), dataSource, fragment, ldfRequest);
@@ -171,14 +172,24 @@ public void doGet(HttpServletRequest request, HttpServletResponse response) thro
                     throw new ServletException(ex1);
                 }
             } catch (Exception e) {
-                e.printStackTrace();
                 response.setStatus(500);
                 writer.writeError(response.getOutputStream(), e);
             }
           
         } catch (Exception e) {
             throw new ServletException(e);
         }
+        finally {
+            // close the fragment
+            if ( fragment != null ) {
+                try {
+                    fragment.close();
+                }
+                catch ( Exception e ) {
+                    // ignore
+                }
+            }
+        }
     }
 
 }
diff --git a/src/org/linkeddatafragments/util/CommonResources.java b/src/org/linkeddatafragments/util/CommonResources.java
@@ -4,6 +4,9 @@
 import com.hp.hpl.jena.rdf.model.ResourceFactory;
 
 @SuppressWarnings("javadoc")
+/**
+ * All common URIs needed for parsing and serializations
+ */
 public class CommonResources {
     public final static String RDF = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
     public final static Property RDF_TYPE = createProperty(RDF + "type");
diff --git a/src/org/linkeddatafragments/views/HtmlTriplePatternFragmentWriterImpl.java b/src/org/linkeddatafragments/views/HtmlTriplePatternFragmentWriterImpl.java
@@ -10,7 +10,6 @@
 import java.io.File;
 import java.io.IOException;
 import java.io.OutputStreamWriter;
-import java.io.Writer;
 import java.util.Date;
 import java.util.HashMap;
 import java.util.List;
@@ -21,13 +20,17 @@
 import org.linkeddatafragments.datasource.index.IndexDataSource;
 import org.linkeddatafragments.fragments.ILinkedDataFragment;
 import org.linkeddatafragments.fragments.ILinkedDataFragmentRequest;
+import org.linkeddatafragments.fragments.tpf.ITriplePatternFragment;
 import org.linkeddatafragments.fragments.tpf.ITriplePatternFragmentRequest;
 
+//TODO: Refactor to a composable & flexible architecture using DataSource types, fragments types and request types
+
 /**
+ * Serializes an {@link ILinkedDataFragment} to the HTML format
  *
- * @author mielvandersande
+ * @author Miel Vander Sande
  */
-public class HtmlWriterImpl extends LinkedDataFragmentWriterBase implements ILinkedDataFragmentWriter {
+public class HtmlTriplePatternFragmentWriterImpl extends TriplePatternFragmentWriterBase implements ILinkedDataFragmentWriter {
     private final Configuration cfg;
     
     private final Template indexTemplate;
@@ -39,7 +42,7 @@ public class HtmlWriterImpl extends LinkedDataFragmentWriterBase implements ILin
     private final String VOID = "http://rdfs.org/ns/void#"; 
     
 
-    public HtmlWriterImpl(Map<String, String> prefixes, HashMap<String, IDataSource> datasources) throws IOException {
+    public HtmlTriplePatternFragmentWriterImpl(Map<String, String> prefixes, HashMap<String, IDataSource> datasources) throws IOException {
         super(prefixes, datasources);
         
         cfg = new Configuration(Configuration.VERSION_2_3_22);
@@ -52,9 +55,9 @@ public HtmlWriterImpl(Map<String, String> prefixes, HashMap<String, IDataSource>
         notfoundTemplate = cfg.getTemplate("notfound.ftl.html");
         errorTemplate = cfg.getTemplate("error.ftl.html");
     }
-   
+    
     @Override
-    public void writeFragment(ServletOutputStream outputStream, IDataSource datasource, ILinkedDataFragment fragment,  ILinkedDataFragmentRequest ldfRequest) throws IOException, TemplateException{
+    public void writeFragment(ServletOutputStream outputStream, IDataSource datasource, ITriplePatternFragment fragment,  ITriplePatternFragmentRequest tpfRequest) throws IOException, TemplateException{
         Map data = new HashMap();
         
         // base.ftl.html
@@ -63,9 +66,10 @@ public void writeFragment(ServletOutputStream outputStream, IDataSource datasour
         data.put("date", new Date());
         
         // fragment.ftl.html
-        data.put("datasourceUrl", ldfRequest.getDatasetURL());
+        data.put("datasourceUrl", tpfRequest.getDatasetURL());
         data.put("datasource", datasource);
         
+        // Parse controls to template variables
         StmtIterator controls = fragment.getControls();
         while (controls.hasNext()) {
             Statement control = controls.next();
@@ -78,41 +82,32 @@ public void writeFragment(ServletOutputStream outputStream, IDataSource datasour
             }
         }
         
-        StmtIterator metadata = fragment.getMetadata();
-        while (metadata.hasNext()) {
-            Statement item = metadata.next();
-            String predicate = item.getPredicate().getURI();
-            
-            if (predicate.equals(HYDRA + "totalItems") || predicate.equals( VOID + "triples")) {
-                data.put("totalEstimate", item.getObject().asLiteral().getLong());
-                break;
-            }
-        }
+        // Add metadata
+        data.put("totalEstimate", fragment.getTotalSize());
         data.put("itemsPerPage", fragment.getMaxPageSize());
         
+        // Add triples and datasources
         List<Statement> triples = fragment.getTriples().toList();
         data.put("triples", triples);
         data.put("datasources", getDatasources());
-         
-        Map query = new HashMap();
-        ITriplePatternFragmentRequest tpfRequest = (ITriplePatternFragmentRequest) ldfRequest;
         
+        // Calculate start and end triple number
         Long start = ((tpfRequest.getPageNumber() - 1) * fragment.getMaxPageSize()) + 1;
         data.put("start", start);
         data.put("end", start + (triples.size() < fragment.getMaxPageSize() ? triples.size() : fragment.getMaxPageSize()));
-    
         
+        // Compose query object
+        Map query = new HashMap();
         query.put("subject", !tpfRequest.getSubject().isVariable() ? tpfRequest.getSubject().asConstantTerm() : "");
         query.put("predicate", !tpfRequest.getPredicate().isVariable() ? tpfRequest.getPredicate().asConstantTerm() : "");
         query.put("object", !tpfRequest.getObject().isVariable() ? tpfRequest.getObject().asConstantTerm() : "");
         data.put("query", query);
        
-        /* Get the template (uses cache internally) */
+        // Get the template (uses cache internally)
         Template temp = datasource instanceof IndexDataSource ? indexTemplate : datasourceTemplate;
 
-        /* Merge data-model with template */
-        Writer out = new OutputStreamWriter(outputStream);
-        temp.process(data, out);
+        // Merge data-model with template
+        temp.process(data, new OutputStreamWriter(outputStream));
     }
 
     @Override
@@ -123,8 +118,7 @@ public void writeNotFound(ServletOutputStream outputStream, HttpServletRequest r
         data.put("date", new Date());
         data.put("url", request.getRequestURL().toString());
         
-        Writer out = new OutputStreamWriter(outputStream);
-        notfoundTemplate.process(data, out);
+        notfoundTemplate.process(data, new OutputStreamWriter(outputStream));
     }
 
     @Override
@@ -133,8 +127,7 @@ public void writeError(ServletOutputStream outputStream, Exception ex)  throws E
         data.put("assetsPath", "assets/");
         data.put("date", new Date());
         data.put("error", ex);
-        
-        Writer out = new OutputStreamWriter(outputStream);
-        errorTemplate.process(data, out);
+
+        errorTemplate.process(data, new OutputStreamWriter(outputStream));
     }
 }
diff --git a/src/org/linkeddatafragments/views/ILinkedDataFragmentWriter.java b/src/org/linkeddatafragments/views/ILinkedDataFragmentWriter.java
@@ -7,11 +7,37 @@
 import org.linkeddatafragments.fragments.ILinkedDataFragmentRequest;
 
 /**
- *
- * @author mielvandersande
+ * Represents a possible writer to serialize an {@link ILinkedDataFragment} object
+ * 
+ * @author Miel Vander Sande
  */
 public interface ILinkedDataFragmentWriter {
+    /**
+     * Writes a 404 Not Found error
+     * 
+     * @param outputStream The response stream to write to
+     * @param request Request that is unable to answer
+     * @throws Exception Error that occurs while serializing
+     */
     public void writeNotFound(ServletOutputStream outputStream, HttpServletRequest request) throws Exception;
+    
+    /**
+     * Writes a 5XX error
+     * 
+     * @param outputStream The response stream to write to
+     * @param ex Exception that occurred
+     * @throws Exception Error that occurs while serializing
+     */
     public void writeError(ServletOutputStream outputStream, Exception ex) throws Exception;
+    
+    /**
+     * Serializes and writes a {@link ILinkedDataFragment}
+     * 
+     * @param outputStream The response stream to write to
+     * @param datasource
+     * @param fragment
+     * @param ldfRequest Parsed request for fragment
+     * @throws Exception Error that occurs while serializing
+     */
     public void writeFragment(ServletOutputStream outputStream, IDataSource datasource, ILinkedDataFragment fragment,  ILinkedDataFragmentRequest ldfRequest) throws Exception;
 }
diff --git a/src/org/linkeddatafragments/views/LinkedDataFragmentWriterBase.java b/src/org/linkeddatafragments/views/LinkedDataFragmentWriterBase.java
@@ -5,8 +5,9 @@
 import org.linkeddatafragments.datasource.IDataSource;
 
 /**
+ * Base class of any implementation of {@link ILinkedDataFragmentWriter}.
  *
- * @author mielvandersande
+ * @author Miel Vander Sande
  */
 public abstract class LinkedDataFragmentWriterBase implements ILinkedDataFragmentWriter {
     private final Map<String, String> prefixes;
diff --git a/src/org/linkeddatafragments/views/LinkedDataFragmentWriterFactory.java b/src/org/linkeddatafragments/views/LinkedDataFragmentWriterFactory.java
@@ -6,18 +6,27 @@
 import org.linkeddatafragments.datasource.IDataSource;
 
 /**
- *
- * @author mielvandersande
+ * A factory for {@link ILinkedDataFragmentWriter}s. 
+ * 
+ * @author Miel Vander Sande
  */
 public class LinkedDataFragmentWriterFactory {
     
     private final static String HTML = "text/html";
     
-    
+    /**
+     * Creates {@link ILinkedDataFragmentWriter} for a given mimeType
+     * 
+     * @param prefixes Configured prefixes to be used in serialization
+     * @param datasources Configured datasources
+     * @param mimeType mimeType to create writer for
+     * @return created writer
+     * @throws IOException 
+     */
     public static ILinkedDataFragmentWriter create(Map <String, String> prefixes, HashMap<String, IDataSource> datasources, String mimeType) throws IOException {
         switch (mimeType) {
             case HTML:
-                return new HtmlWriterImpl(prefixes, datasources);
+                return new HtmlTriplePatternFragmentWriterImpl(prefixes, datasources);
             default:
                 return new RdfWriterImpl(prefixes, datasources, mimeType);
         }
diff --git a/src/org/linkeddatafragments/views/RdfWriterImpl.java b/src/org/linkeddatafragments/views/RdfWriterImpl.java
@@ -15,8 +15,9 @@
 import org.linkeddatafragments.fragments.ILinkedDataFragmentRequest;
 
 /**
- *
- * @author mielvandersande
+ *  Serializes an {@link ILinkedDataFragment} to an RDF format
+ * 
+ * @author Miel Vander Sande
  */
 class RdfWriterImpl extends LinkedDataFragmentWriterBase implements ILinkedDataFragmentWriter {
 
diff --git a/src/org/linkeddatafragments/views/TriplePatternFragmentWriterBase.java b/src/org/linkeddatafragments/views/TriplePatternFragmentWriterBase.java

Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,7 @@`
`2`	`2`
`3`	`3`	`/**`
`4`	`4`	`*`
`5`		`- * @author mielvandersande`
	`5`	`+ * @author Miel Vander Sande`
`6`	`6`	`* @author Bart Hanssens`
`7`	`7`	`*/`
`8`	`8`	`public abstract class DataSourceBase implements IDataSource {`
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@`
`4`	`4`
`5`	`5`	`/**`
`6`	`6`	`*`
`7`		`- * @author mielvandersande`
	`7`	`+ * @author Miel Vander Sande`
`8`	`8`	`*/`
`9`	`9`	`abstract public class DataSourceException extends Exception {`
`10`	`10`