svn commit: r1439472 - in /jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system: FastPrefixMap.java LightweightPrefixMap.java PrefixMap.java

[rv...@apache.org]

Author: rvesse
Date: Mon Jan 28 16:14:42 2013
New Revision: 1439472

URL: http://svn.apache.org/viewvc?rev=1439472&view=rev
Log:
Reformat code in FastPrefixMap, expand javadoc to explain when it should be used

Modified:
    jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system/FastPrefixMap.java
    jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system/LightweightPrefixMap.java
    jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system/PrefixMap.java

Modified: jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system/FastPrefixMap.java
URL: http://svn.apache.org/viewvc/jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system/FastPrefixMap.java?rev=1439472&r1=1439471&r2=1439472&view=diff
==============================================================================
--- jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system/FastPrefixMap.java (original)
+++ jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system/FastPrefixMap.java Mon Jan 28 16:14:42 2013
@@ -32,25 +32,49 @@ import org.apache.jena.iri.IRIFactory;
 import com.hp.hpl.jena.shared.PrefixMapping;
 
 /**
- * A fast prefix map
- * 
- * @author rvesse
- * 
+ * A prefix map implementation suited to output heavy workloads
+ * <p>
+ * This is an alternative implementation of the {@link LightweightPrefixMap}
+ * interface, it is broadly similar to the default {@link PrefixMap}
+ * implementation but is faster in output heavy workloads. If you are calling
+ * the {@link LightweightPrefixMap#expand(String)} or
+ * {@link LightweightPrefixMap#expand(String, String)} methods a lot then you
+ * should be using this implementation.
+ * </p>
+ * <p>
+ * To improve on output performance this implementation maintains a {@link Trie}
+ * mapping namespace IRIs to their prefixes as well as a normal mapping.
+ * Therefore IRI abbreviation can be done as an approximately O(1) operation in
+ * the worst case (ignoring the vagaries of {@link HashMap} performance since
+ * that underpins the {@link Trie} implementation). If you contrast this with
+ * the abbreviation performance of the default {@link PrefixMap} which is worst
+ * case O(n) then this is a substantial saving in scenarios where you primarily
+ * use a prefix map for output.
+ * </p>
+ * <p>
+ * Generally speaking all other operations should be roughly equivalent to the
+ * default {@link PrefixMap} though the memory overhead of this implementation
+ * will be marginally higher due to the extra information maintained in the
+ * {@link Trie}.
+ * </p>
  */
 public class FastPrefixMap extends LightweightPrefixMapBase {
 
     private Map<String, IRI> prefixes = new HashMap<String, IRI>();
     private Map<String, IRI> prefixesView = Collections.unmodifiableMap(this.prefixes);
     private Trie<String> abbrevs = new Trie<String>();
-    
+
     /**
      * Create a new fast prefix map
      */
-    public FastPrefixMap() { }
-    
+    public FastPrefixMap() {
+    }
+
     /**
      * Create a new prefix map which copies mappings from an existing map
-     * @param pmap Prefix Map
+     * 
+     * @param pmap
+     *            Prefix Map
      */
     public FastPrefixMap(LightweightPrefixMap pmap) {
         this.putAll(pmap);
@@ -145,9 +169,10 @@ public class FastPrefixMap extends Light
     @Override
     public void delete(String prefix) {
         prefix = canonicalPrefix(prefix);
-        
+
         IRI iri = this.prefixes.get(prefix);
-        if (iri == null) return;
+        if (iri == null)
+            return;
 
         // Delete the abbreviation mapping
         this.abbrevs.remove(iri.toString());
@@ -195,10 +220,12 @@ public class FastPrefixMap extends Light
         if (abbrevKey != null) {
             // Suitable for trie based lookup
             String prefix = this.abbrevs.get(abbrevKey);
-            if (prefix == null) return null;
-            
+            if (prefix == null)
+                return null;
+
             String ln = uriStr.substring(this.prefixes.get(prefix).toString().length());
-            if (!turtleSafe || isTurtleSafe(ln)) return Pair.create(prefix, ln);
+            if (!turtleSafe || isTurtleSafe(ln))
+                return Pair.create(prefix, ln);
             return null;
         } else {
             // Not suitable for trie based lookup so trie the brute force

Modified: jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system/LightweightPrefixMap.java
URL: http://svn.apache.org/viewvc/jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system/LightweightPrefixMap.java?rev=1439472&r1=1439471&r2=1439472&view=diff
==============================================================================
--- jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system/LightweightPrefixMap.java (original)
+++ jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system/LightweightPrefixMap.java Mon Jan 28 16:14:42 2013
@@ -33,6 +33,16 @@ import com.hp.hpl.jena.shared.PrefixMapp
  * unlike the Jena Core {@link PrefixMapping} which require validation of
  * prefixes.
  * </p>
+ * <h3>Implementations</h3>
+ * <p>
+ * For input dominated workloads where you are primarily calling
+ * {@link #expand(String)} or {@link #expand(String, String)} it is best to use
+ * the default implementation - {@link PrefixMap}. For output dominated
+ * workloads where you are primarily calling {@link #abbrev(String)} or
+ * {@link #abbreviate(String)} it is better to use the {@link FastPrefixMap}
+ * implementation.  See the javadoc for those classes for more explanation
+ * of their differences.
+ * </p>
  * 
  */
 public interface LightweightPrefixMap {

Modified: jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system/PrefixMap.java
URL: http://svn.apache.org/viewvc/jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system/PrefixMap.java?rev=1439472&r1=1439471&r2=1439472&view=diff
==============================================================================
--- jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system/PrefixMap.java (original)
+++ jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/system/PrefixMap.java Mon Jan 28 16:14:42 2013
@@ -37,7 +37,7 @@ import com.hp.hpl.jena.shared.PrefixMapp
  * <p>
  * If you are using this primarily to abbreviate URIs for output consider using
  * the {@link FastPrefixMap} instead which offers much better abbreviation
- * performance
+ * performance.
  */
 public class PrefixMap extends LightweightPrefixMapBase {
     final Map<String, IRI> prefixes = new HashMap<String, IRI>();