LocalFileResolver (Media Authoring with Java API)
Date: 2016-02-05

tv.amwa.maj.industry

## Class LocalFileResolver

- java.lang.Object
- - tv.amwa.maj.industry.LocalFileResolver

- All Implemented Interfaces:
    StreamResolver

      public class LocalFileResolver
      extends Object
      implements StreamResolver

  Default implementation of a stream resolver that resolves URIs for streams to stream access to local files.

  The local file resolver can handle the following types of local streams:

  - wrapped inside AAF structured storage files;
  - wrapped as body streams inside MXF files;
  - referenced raw essence streams from XML files;
  - raw essence streams as unwrapped files;
  - memory resident streams.

  This implementation is fairly dumb, returns the first location that it finds and pays little attention to accept criteria, except as noted in `resolveStream(URI, String)`.

  See Also:
    `MediaEngine.getStreamResolver()`, `MediaEngine.changeStreamResolver(StreamResolver)`, `TypeDefinitionStream`, `EssenceData.getEssenceStream()`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `LocalFileResolver()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `cacheStream(Stream stream)` Caches the lookup of a location-specific URI to a stream.
    `void` | `clearStreamCacheFiles()` Clear the internal stream cache of this local file resolver of all file references.
    `URI` | `makeSpecific(URI streamReference, String accept)` Make a canonical URI local and file-type specific using the registered mappings of this resolver and the HTTP-like accept criteria provided.
    `void` | `registerMapping(URI canonicalForm, URI location)` Register a mapping between the canonical form of a URI for a stream and a location and file-type specific form.
    `boolean` | `removeLocation(URI identifier)` Remove a canonical identifier or a specific location identifier as a possible stream resolution source.
    `Stream` | `resolveStream(URI streamReference)` Resolve the given URI to a stream that can be used to access the data at that URI according to resolver policy.
    `Stream` | `resolveStream(URI streamReference, String accept)` Resolve the given URI to a stream that can be used to access the data at the URI in a form that matches the given HTTP-like accept criteria.

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

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

- - ### Constructor Detail

    - #### LocalFileResolver

          public LocalFileResolver()

  - ### Method Detail

    - #### makeSpecific

          public URI makeSpecific(URI streamReference,
                                  String accept)
                           throws NullPointerException,
                                  IllegalArgumentException

      Description copied from interface: `StreamResolver`

      Make a canonical URI local and file-type specific using the registered mappings of this resolver and the HTTP-like accept criteria provided. This method is similar to `StreamResolver.resolveStream(URI, String)` except that it does not carry out the final step of resolving the provided URI to a stream. Instead, it provides the specific URI that would be used to provide access to the stream.

      URIs that are already specific should be passed straight through.

      Specified by:
        `makeSpecific` in interface `StreamResolver`
      Parameters:
        `streamReference` - Identifier for the stream to resolve.
        `accept` - Hint for the resolver as to the acceptable kinds of stream for the calling client.
      Returns:
        Location and file-type specific URI for accessing the stream.
      Throws:
        `NullPointerException`
        `IllegalArgumentException`
      See Also:
        `Cannot resolve a `null` URI and/or deal with a `null` accept header.`, `The given accept header is not valid.`, `StreamResolver.resolveStream(URI, String)`, `MediaEngine.makeSpecific(URI, String)`, `URI.create(String)`

    - #### registerMapping

          public void registerMapping(URI canonicalForm,
                                      URI location)
                               throws NullPointerException,
                                      IllegalArgumentException

      Description copied from interface: `StreamResolver`

      Register a mapping between the canonical form of a URI for a stream and a location and file-type specific form. This mapping may be used by future resolutions from identifier to streams made by this resolver.

      Specified by:
        `registerMapping` in interface `StreamResolver`
      Parameters:
        `canonicalForm` - Canonical representation of an identifier for a stream.
        `location` - One possible location and file-type specific identifier for the stream.
      Throws:
        `NullPointerException` - One or both is the arguments is/are `null`.
        `IllegalArgumentException` - The given canonical identifier is location specific and/or the given location identifier is not specific enough.
      See Also:
        `StreamResolver.resolveStream(URI)`, `StreamResolver.resolveStream(URI, String)`, `StreamResolver.makeSpecific(URI, String)`, `MediaEngine.registerMapping(URI, URI)`, `URI.create(String)`

    - #### removeLocation

          public boolean removeLocation(URI identifier)
                                 throws NullPointerException

      Description copied from interface: `StreamResolver`

      Remove a canonical identifier or a specific location identifier as a possible stream resolution source. If the location is canonical, all location-specific identifiers for that identifier may also be removed.

      Specified by:
        `removeLocation` in interface `StreamResolver`
      Parameters:
        `identifier` - Identifier to remove from this resolved.
      Returns:
        Has the identifier been successfully removed? Note that `false` is returned if the identifier is not known to this resolver.
      Throws:
        `NullPointerException` - Cannot remove a `null` identifier.
      See Also:
        `MediaEngine.removeLocation(URI)`

    - #### resolveStream

          public Stream resolveStream(URI streamReference)
                               throws NullPointerException

      Description copied from interface: `StreamResolver`

      Resolve the given URI to a stream that can be used to access the data at that URI according to resolver policy. The URI may be location and file-type specific, or it may be a canonical identifier for which a specific location has already been registered. If a canonical identifier, the resolver should use a local policy to determine which location to return as a stream.

      Specified by:
        `resolveStream` in interface `StreamResolver`
      Parameters:
        `streamReference` - Identifier for the stream to resolve.
      Returns:
        Stream that can be used to read and write data, or `null` if the given URI cannot be resolved.
      Throws:
        `NullPointerException` - Cannot resolve a `null` URI.
      See Also:
        `StreamResolver.resolveStream(URI)`, `MediaEngine.resolveStream(URI)`, `URI.create(String)`

    - #### resolveStream

          public Stream resolveStream(URI streamReference,
                                      String accept)
                               throws NullPointerException,
                                      IllegalArgumentException

      Description copied from interface: `StreamResolver`

      Resolve the given URI to a stream that can be used to access the data at the URI in a form that matches the given HTTP-like accept criteria. The accept criteria provide a list of MIME types and quality parameters that indicate types of data acceptable to the caller, in order of preference. The resolver may choose to use the accept criteria when selecting a stream to access, according to local resolver policy. The format of an HTTP accept criteria is defined to be the same as an HTTP accept header, which can be found in section 14 of HTTP 1.1.

      The calling client should look at the URI of the stream returned using Stream.getStreamURI() to see if their accept request has been observed. Note that two calls to this method with the same identifier may resolve to different streams according to the policy of the local resolved, for example to handle network routing failures.

      Specified by:
        `resolveStream` in interface `StreamResolver`
      Parameters:
        `streamReference` - Identifier for the stream to resolve.
        `accept` - Hint for the resolver as to the acceptable kinds of stream for the calling client. An accept header must be provided and should be set to "`*/*`" to get the same behaviour as for `StreamResolver.resolveStream(URI)`.
      Returns:
        Stream that can be used to read and write data, or `null` if the given URI cannot be resolved.
      Throws:
        `NullPointerException`
        `IllegalArgumentException`
      See Also:
        `Cannot resolve a `null` URI and/or deal with a `null` accept header.`, `The given accept header is not valid.`, `StreamResolver.resolveStream(URI)`, `StreamResolver.makeSpecific(URI, String)`, `MediaEngine.resolveStream(URI, String)`, `URI.create(String)`

    - #### clearStreamCacheFiles

          public void clearStreamCacheFiles()

      Clear the internal stream cache of this local file resolver of all file references. This may be useful if the resolver is producing unexpected results or after a file system outage. Memory resident streams are not cleared as this could cause them to be lost all together.

    - #### cacheStream

          public void cacheStream(Stream stream)
                           throws NullPointerException,
                                  IllegalArgumentException

      Description copied from interface: `StreamResolver`

      Caches the lookup of a location-specific URI to a stream. This saves the resolver from having to construct a new stream for the URI from scratch. The location of the stream is found with a call to `Stream.getStreamURI()`.

      Specified by:
        `cacheStream` in interface `StreamResolver`
      Parameters:
        `stream` - Actual stream to cache.
      Throws:
        `NullPointerException` - Cannot cache a `null` stream.
        `IllegalArgumentException`

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.