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

tv.amwa.maj.industry

## Interface StreamResolver

- All Known Implementing Classes:
    LocalFileResolver

      public interface StreamResolver

  Specifies a means for an application to resolve a URI reference to a stream to a means to read and write the data in that stream. The URI may be a globally unique canonical identifier for the stream or a very specific location, such as the location of an MXF file on a local disk and the body stream identifier for the internal data.

  The methods of this interface are statically implemented by the media engine to provide a per-virtual-machine stream resolution strategy that is used by default for all properties of stream type. The strategy can be replaced by changing the stream resolver used by the media engine by calling `MediaEngine.changeStreamResolver(StreamResolver)`.

  The MAJ API has a default local file resolver that is used to provide access to streams that are currently accessible as local files. These are often the same MXF or AAF files that wrap the stream data with its associated metadata.

  See Also:
    `Stream`, `MemoryResidentStream`, `LocalFileResolver`, `EssenceData.getEssenceStream()`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `cacheStream(Stream stream)` Caches the lookup of a location-specific URI to a stream.
    `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.

- - ### Method Detail

    - #### resolveStream

          Stream resolveStream(URI streamReference)
                        throws NullPointerException

      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.

      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:
        `resolveStream(URI)`, `MediaEngine.resolveStream(URI)`, `URI.create(String)`

    - #### resolveStream

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

      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.

      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 `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.`, `resolveStream(URI)`, `makeSpecific(URI, String)`, `MediaEngine.resolveStream(URI, String)`, `URI.create(String)`

    - #### makeSpecific

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

      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 `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.

      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.`, `resolveStream(URI, String)`, `MediaEngine.makeSpecific(URI, String)`, `URI.create(String)`

    - #### registerMapping

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

      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.

      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:
        `resolveStream(URI)`, `resolveStream(URI, String)`, `makeSpecific(URI, String)`, `MediaEngine.registerMapping(URI, URI)`, `URI.create(String)`

    - #### removeLocation

          boolean removeLocation(URI identifier)
                          throws NullPointerException

      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.

      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)`

    - #### cacheStream

          void cacheStream(Stream stream)
                    throws NullPointerException,
                           IllegalArgumentException

      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()`.

      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.