com.jogamp.common.net

## Class AssetURLContext

- java.lang.Object
- - com.jogamp.common.net.AssetURLContext

- All Implemented Interfaces:
    PiggybackURLContext

      public abstract class AssetURLContext
      extends Object
      implements PiggybackURLContext

  See `PiggybackURLConnection` for description and examples.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `asset_protocol` The asset URL protocol name `asset`
    `static String` | `asset_protocol_prefix` The asset URL protocol prefix `asset:`
    `static String` | `assets_folder` The optional asset folder name with ending slash `assets/`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AssetURLContext()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static AssetURLContext` | `create(ClassLoader cl)`
    `static AssetURLStreamHandler` | `createHandler(ClassLoader cl)`
    `static URL` | `createURL(String path)` Create an asset URL, suitable only with the registered asset URLStreamHandler.
    `static URL` | `createURL(String path, ClassLoader cl)` Create an asset URL, suitable even w/o the registered asset URLStreamHandler.
    `abstract ClassLoader` | `getClassLoader()` Returns an asset aware ClassLoader.
    `String` | `getImplementedProtocol()` Returns the specific protocol, constant for this implementation.
    `static URLStreamHandler` | `getRegisteredHandler()` Returns the asset handler previously set via `registerHandler(ClassLoader)`, or null if none was set.
    `static boolean` | `registerHandler(ClassLoader cl)` Registers the generic URLStreamHandlerFactory via `GenericURLStreamHandlerFactory.register()` and if successful sets the asset `handler` for the given ClassLoader `cl`.
    `URLConnection` | `resolve(String path)` Resolving path to a URL sub protocol and return it's open URLConnection
    `static URLConnection` | `resolve(String path, ClassLoader cl)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### asset_protocol

          public static final String asset_protocol

      The asset URL protocol name `asset`
      See Also:
        Constant Field Values

    - #### asset_protocol_prefix

          public static final String asset_protocol_prefix

      The asset URL protocol prefix `asset:`
      See Also:
        Constant Field Values

    - #### assets_folder

          public static final String assets_folder

      The optional asset folder name with ending slash `assets/`.

      Note that the asset folder is not used on all platforms using the asset protocol and you should not rely on it, use `AssetURLConnection.getEntryName()`.

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### AssetURLContext

          public AssetURLContext()

  - ### Method Detail

    - #### create

          public static AssetURLContext create(ClassLoader cl)

    - #### createHandler

          public static AssetURLStreamHandler createHandler(ClassLoader cl)

    - #### createURL

          public static URL createURL(String path,
                      ClassLoader cl)
                               throws MalformedURLException

      Create an asset URL, suitable even w/o the registered asset URLStreamHandler.

      This is equivalent with:

             return new URL(null, path.startsWith("asset:") ? path : "asset:" + path, new AssetURLStreamHandler(cl));

      Parameters:
        `path` - resource path, with or w/o `asset:` prefix
        `cl` - the ClassLoader used to resolve the location, see `getClassLoader()`.
      Returns:
      Throws:
        `MalformedURLException`

    - #### createURL

          public static URL createURL(String path)
                               throws MalformedURLException

      Create an asset URL, suitable only with the registered asset URLStreamHandler.

      This is equivalent with:

             return new URL(path.startsWith("asset:") ? path : "asset:" + path);

      Parameters:
        `path` - resource path, with or w/o `asset:` prefix
      Returns:
      Throws:
        `MalformedURLException`

    - #### getRegisteredHandler

          public static URLStreamHandler getRegisteredHandler()

      Returns the asset handler previously set via `registerHandler(ClassLoader)`, or null if none was set.

    - #### registerHandler

          public static boolean registerHandler(ClassLoader cl)

      Registers the generic URLStreamHandlerFactory via `GenericURLStreamHandlerFactory.register()` and if successful sets the asset `handler` for the given ClassLoader `cl`.
      Returns:
        true if successful, otherwise false

    - #### getClassLoader

          public abstract ClassLoader getClassLoader()

      Returns an asset aware ClassLoader.

      The ClassLoader is required to find the asset resource via it's `URL findResource(String)` implementation.

      It's `URL findResource(String)` implementation shall return either an asset URL `asset:sub-protocol` or just the sub-protocol URL.

      For example, on Android, we redirect all `path` request to assets/`path`.

    - #### getImplementedProtocol

          public String getImplementedProtocol()

      Description copied from interface: `PiggybackURLContext`
      Returns the specific protocol, constant for this implementation.
      Specified by:
        `getImplementedProtocol` in interface `PiggybackURLContext`

    - #### resolve

          public URLConnection resolve(String path)
                                throws IOException

      Resolving path to a URL sub protocol and return it's open URLConnection

      This implementation attempts to resolve `path` in the following order:

      1. as a valid URL: `new URL(path)`, use sub-protocol if asset URL
      2. via ClassLoader: `getClassLoader()`.`getResource(path)`, use sub-protocol if asset URL
      3. as a File: `new File(path).toURI().toURL()`

      In case of using the ClassLoader (2) and if running on Android, the `assets_folder` is being prepended to `path` if missing.

      Specified by:
        `resolve` in interface `PiggybackURLContext`
      Throws:
        `IOException`

    - #### resolve

          public static URLConnection resolve(String path,
                              ClassLoader cl)
                                       throws IOException

      Throws:
        `IOException`