com.jogamp.common.net.AssetURLConnection Maven / Gradle / Ivy

package com.jogamp.common.net;

import java.io.IOException;
import java.net.JarURLConnection;
import java.net.URL;

/**
 * See base class {@link PiggybackURLConnection} for motivation.
 *
 * 
 * asset resource location protocol connection.
 * 
 *
 * 
 * See {@link AssetURLContext#resolve(String)} how resources are being resolved.
 * 
 *
 * Example:
 *
 * Assuming the plain asset entry test/lala.txt is being resolved by
 * a class test.LaLaTest, ie. using the asset aware ClassLoader,
 * one would use the following asset aware filesystem layout:
 *
 *  *  test/LaLaTest.class
 *  assets/test/lala.txt
 * 
 *
 * The above maybe on a plain filesystem, or within a JAR or an APK file,
 * e.g. jogamp.test.apk.
 *
 * The above would result in the following possible URLs
 * reflecting the plain and resolved state of the asset URL:
 *  *  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
 * 
 *
 * 
 * The sub protocol URL of the resolved asset
 * 
 *  3 Sub-URL        jar:file:/data/app/jogamp.test.apk!/assets/test/lala.txt
 * 
 * can be retrieved using {@link #getSubProtocol()}.
 * 
 *
 * In all above cases, the asset entry is test/lala.txt,
 * which can be retrieved via {@link #getEntryName()}.
 *
 * 
 * 
General Implementation Notes:
 * An asset URL is resolved using {@link AssetURLContext#getClassLoader()}.{@link ClassLoader#getResource(String) getResource(String)},
 * hence the only requirement for an implementation is to have an asset aware ClassLoader
 * as described in  {@link AssetURLContext#getClassLoader()}.
 * 
 * 
 * 
Warning:
 * Since the asset protocol is currently not being implemented
 * on all platform with an appropriate ClassLoader, a user shall not create the asset URL manually.

 * 
 *
 * Android Implementation Notes:
 * 
 * The Android ClassLoader {@link jogamp.android.launcher.AssetDexClassLoader}
 * resolves the resource as an asset URL in it's {@link ClassLoader#findResource(String)} implementation.
 * 
 * Currently we attach our asset {@link java.net.URLStreamHandlerFactory}
 * to allow {@link java.net.URL} to handle asset URLs via our asset {@link java.net.URLStreamHandler} implementation.
 * 
 */
public class AssetURLConnection extends PiggybackURLConnection {

    public AssetURLConnection(final URL url, final 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;
        }
    }

}