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.
| 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.
|
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.
streamReference - Identifier for the stream to resolve.null if
the given URI cannot be resolved.NullPointerException - Cannot resolve a null URI.resolveStream(URI),
MediaEngine.resolveStream(URI),
URI.create(String)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.
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).null if
the given URI cannot be resolved.NullPointerExceptionIllegalArgumentExceptionCannot 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)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.
streamReference - Identifier for the stream to resolve.accept - Hint for the resolver as to the acceptable kinds of stream for the
calling client.NullPointerExceptionIllegalArgumentExceptionCannot 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)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.
canonicalForm - Canonical representation of an identifier for a stream.location - One possible location and file-type specific identifier for
the stream.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.resolveStream(URI),
resolveStream(URI, String),
makeSpecific(URI, String),
MediaEngine.registerMapping(URI, URI),
URI.create(String)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.
identifier - Identifier to remove from this resolved.false is
returned if the identifier is not known to this resolver.NullPointerException - Cannot remove a null identifier.MediaEngine.removeLocation(URI)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().
stream - Actual stream to cache.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.