From 235f8b1cbff8ed13071d5c19c0be492c0b25cb78 Mon Sep 17 00:00:00 2001
From: Sven Gothel <sgothel@jausoft.com>
Date: Sat, 17 Mar 2012 21:15:49 +0100
Subject: Add 'asset' URLConnection; IOUtil uses URLConnection / incr.
 effeciency; Android ClassLoaderUtil cleanup;

- Add 'asset' URLConnection
  - Please read API doc 'PiggybackURLConnection' and 'AssetURLConnection'

  - Solves generic resource handling where platform locations may differ,
    ie ClassLoader lookup on Android in the 'assets/' subfolder.

  - New Android 'AssetDexClassLoader' uses 'assets/' folder for findResource(..)

  - aapt.signed (our APK ant task)
    - uses 'assets/' folder

    - adds the 'assetsdir' attribute allowing to copy other assets into the APK

- IOUtil uses URLConnection / incr. effeciency
  - using URLConnection on all getResource(..) since URL
    is connected anyways for validation and URLConnection can be used by caller right away

  - String getRelativeOf(URL, String) -> URL getRelativeOf(URL, String)
    - preserves scheme, authority, etc
    - simple parentOf handling, more efficient

  - reusing new 'asset' protocol impl.

- Android ClassLoaderUtil cleanup;
  - Use createClassLoader(..) impl for build-in static jogamp and user APKs,
    which removes code redundancy

Tests: New code path, especially 'assets' are covered by new unit tests, no regressions on Linux.
---
 .../com/jogamp/common/net/AssetURLConnection.java  | 98 ++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 src/java/com/jogamp/common/net/AssetURLConnection.java

(limited to 'src/java/com/jogamp/common/net/AssetURLConnection.java')

diff --git a/src/java/com/jogamp/common/net/AssetURLConnection.java b/src/java/com/jogamp/common/net/AssetURLConnection.java
new file mode 100644
index 0000000..f2a5a01
--- /dev/null
+++ b/src/java/com/jogamp/common/net/AssetURLConnection.java
@@ -0,0 +1,98 @@
+package com.jogamp.common.net;
+
+import java.io.IOException;
+import java.net.JarURLConnection;
+import java.net.URL;
+
+/**
+ * See base class {@link PiggybackURLConnection} for motivation.
+ * 
+ * <p>
+ * <i>asset</i> resource location protocol connection.
+ * </p>
+ * 
+ * <p>
+ * See {@link AssetURLContext#resolve(String)} how resources are being resolved.
+ * </p>
+ *
+ * <h3>Example:</h3>
+ * 
+ * Assuming the plain <i>asset entry</i> <b><code>test/lala.txt</code></b> is being resolved by
+ * a class <code>test.LaLaTest</code>, ie. using the <i>asset aware</i> ClassLoader,
+ * one would use the following <i>asset</i> aware filesystem layout: 
+ * 
+ * <pre>
+ *  test/LaLaTest.class
+ *  assets/test/lala.txt
+ * </pre>
+ * 
+ * The above maybe on a plain filesystem, or within a JAR or an APK file, 
+ * e.g. <code>jogamp.test.apk</code>.
+ * 
+ * The above would result in the following possible URLs
+ * reflecting the plain and resolved state of the <i>asset URL</i>:  
+ * <pre>
+ *  0 Entry          test/lala.txt
+ *  1 Plain    asset:test/lala.txt
+ *  2 Resolved asset:jar:file:/data/app/jogamp.test.apk!/assets/test/lala.txt
+ * </pre>
+ *
+ * <p>
+ * The sub protocol URL of the resolved <i>asset</i>  
+ * <pre>
+ *  3 Sub-URL        jar:file:/data/app/jogamp.test.apk!/assets/test/lala.txt
+ * </pre>
+ * can be retrieved using {@link #getSubProtocol()}.
+ * </p>
+ *  
+ * In all above cases, the <i>asset entry</i> is <b><code>test/lala.txt</code></b>,
+ * which can be retrieved via {@link #getEntryName()}.
+ * 
+ * <p>
+ * <h3>General Implementation Notes:</h3>
+ * An <i>asset</i> URL is resolved using {@link AssetURLContext#getClassLoader()}.{@link ClassLoader#getResource(String) getResource(String)},
+ * hence the only requirement for an implementation is to have an <i>asset</i> aware ClassLoader
+ * as described in  {@link AssetURLContext#getClassLoader()}.
+ * </p>
+ * <p>
+ * <h3>Warning:</h3>
+ * Since the <i>asset</i> protocol is currently not being implemented 
+ * on all platform with an appropriate ClassLoader, a user shall not create the <i>asset</i> URL manually.<br>
+ * </p>
+ * 
+ * <h3>Android Implementation Notes:</h3>
+ * <p>
+ * The Android ClassLoader {@link jogamp.android.launcher.AssetDexClassLoader} 
+ * resolves the resource as an <i>asset</i> URL in it's {@link ClassLoader#findResource(String)} implementation.</p>
+ * <p>
+ * Currently we attach our <i>asset</i> {@link java.net.URLStreamHandlerFactory} 
+ * to allow {@link java.net.URL} to handle <i>asset</i> URLs via our <i>asset</i> {@link java.net.URLStreamHandler} implementation.
+ * </p>
+ */
+public class AssetURLConnection extends PiggybackURLConnection<AssetURLContext> {
+    
+    public AssetURLConnection(URL url, AssetURLContext implHelper) {
+        super(url, implHelper);
+    }
+    
+    @Override
+    public String getEntryName() throws IOException {
+        if(!connected) {
+            throw new IOException("not connected");
+        }
+        
+        final String urlPath ;
+        if(subConn instanceof JarURLConnection) {
+            urlPath = ((JarURLConnection)subConn).getEntryName();
+        } else {
+            urlPath = subConn.getURL().getPath();
+        }
+        
+        if(urlPath.startsWith(AssetURLContext.assets_folder)) {
+            return urlPath.substring(AssetURLContext.assets_folder.length());
+        } else {
+            return urlPath;
+        }
+    }
+    
+}
-- 
cgit v1.2.3