In most cases, you can rely on the Adaptive Media taglib to
display adapted images in your app.
This taglib uses the file version you give it to query Adaptive Media’s finder
API and display the adapted image appropriate for the device making the request.
If you need more control, however, you can write your own query with the API
instead of using the taglib. For example, if you have an app that needs a
specific image in a specific dimension, it’s best to query Adaptive Media’s
finder API directly. You can then display the image however you like (e.g., with
an HTML <img>
tag).
Adaptive Media’s finder API lets you write queries that get adapted images based on certain search criteria and filters. For example, you can get adapted images that match a file version or resolution, or are ordered by an attribute like image width. You can even get adapted images that match approximate attribute values (fuzzy attributes).
This tutorial shows you how to call Adaptive Media’s API to get adapted images in your app. First, you’ll learn how to construct such API calls.
Calling Adaptive Media’s API
The entry point to Adaptive Media’s API is
the AMImageFinder
interface.
To use it, you must first inject the OSGi component in your class, which must
also be an OSGi component, as follows:
@Reference
private AMImageFinder _amImageFinder;
This makes an AMImageFinder
instance available. It has one method,
getAdaptiveMediaStream
, that returns a stream of AdaptiveMedia
objects. This
method takes a Function
that creates an AMQuery
(the query for adapted
images) via AMImageQueryBuilder
, which can search adapted images based on
different attributes (e.g., width, height, order, etc.). The
AMImageQueryBuilder
methods you call depend on the exact query you want to
construct.
For example, here’s a general getAdaptiveMediaStream
call:
Stream<AdaptiveMedia<AMImageProcessor>> adaptiveMediaStream =
_amImageFinder.getAdaptiveMediaStream(
amImageQueryBuilder -> amImageQueryBuilder.methodToCall(arg).done());
The argument to getAdaptiveMediaStream
is a lambda expression that returns an
AMQuery
constructed via AMImageQueryBuilder
. Note that methodToCall(arg)
is a placeholder for the AMImageQueryBuilder
method you want to call and its
argument. The exact call depends on the criteria you want to use to select
adapted images. The done()
call that follows this, however, isn’t a
placeholder–it creates and returns the AMQuery
regardless of which
AMImageQueryBuilder
methods you call.
For more information on creating AMQuery
instances, see
the Javadoc for AMImageQueryBuilder
.
Next, you’ll see specific examples of constructing calls that get adapted images.
Getting Adapted Images for a Specific File Version
To get adapted images for a specific file version, you must call the
AMImageQueryBuilder
method forFileVersion
with a
FileVersion
object
as an argument:
Stream<AdaptiveMedia<AMImageProcessor>> adaptiveMediaStream =
_amImageFinder.getAdaptiveMediaStream(
amImageQueryBuilder -> amImageQueryBuilder.forFileVersion(fileVersion).done());
To get the adapted images for the latest approved file version, use the
forFileEntry
method with a
FileEntry
object:
Stream<AdaptiveMedia<AMImageProcessor>> adaptiveMediaStream =
_amImageFinder.getAdaptiveMediaStream(
amImageQueryBuilder -> amImageQueryBuilder.forFileEntry(fileEntry).done());
Note that these calls only return the adapted images for
enabled image resolutions.
Adapted images for disabled resolutions aren’t included in the stream. To
retrieve all adapted images regardless of any image resolution’s status, you
must also call the withConfigurationStatus
method with the constant
AMImageQueryBuilder.ConfigurationStatus.ANY
:
Stream<AdaptiveMedia<AMImageProcessor>> adaptiveMediaStream =
_amImageFinder.getAdaptiveMediaStream(
amImageQueryBuilder -> amImageQueryBuilder.forFileVersion(fileVersion)
.withConfigurationStatus(AMImageQueryBuilder.ConfigurationStatus.ANY).done());
To get adapted images for a specific file version when the image resolution is
disabled, make the same call but instead use the constant
AMImageQueryBuilder.ConfigurationStatus.DISABLED
:
Stream<AdaptiveMedia<AMImageProcessor>> adaptiveMediaStream =
_amImageFinder.getAdaptiveMediaStream(
amImageQueryBuilder -> amImageQueryBuilder.forFileVersion(fileVersion)
.withConfigurationStatus(AMImageQueryBuilder.ConfigurationStatus.DISABLED).done());
Next, you’ll learn how to get adapted images for a specific image resolution.
Getting the Adapted Images for a Specific Image Resolution
By providing an image resolution’s UUID to AMImageFinder
, you can get that
resolution’s adapted images. This UUID is defined when
adding the resolution
in the Adaptive Media app. To get a resolution’s adapted images, you must pass
that resolution’s UUID to the forConfiguration
method.
For example, this code gets the adapted images that match a file version, and
belong to an image resolution with the UUID hd-resolution
. It returns the
adapted images regardless of whether the resolution is enabled or disabled:
Stream<AdaptiveMedia<AMImageProcessor>> adaptiveMediaStream =
_amImageFinder.getAdaptiveMediaStream(
amImageQueryBuilder -> amImageQueryBuilder.forFileVersion(fileVersion)
.forConfiguration("hd-resolution").done());
Next, you’ll learn how to return adapted images in a specific order.
Getting Adapted Images in a Specific Order
It’s also possible to define the order in which getAdaptiveMediaStream
returns
adapted images. To do this, call the orderBy
method with your sort criteria
just before calling the done()
method. The orderBy
method takes two
arguments: the first specifies the image attribute to sort by (e.g.,
width/height), while the second specifies the sort order (e.g.,
ascending/descending).
For example, this code gets all the adapted images regardless of whether the image resolution is enabled, and puts them in ascending order by the image width:
Stream<AdaptiveMedia<AMImageProcessor>> adaptiveMediaStream =
_amImageFinderImpl.getAdaptiveMediaStream(
amImageQueryBuilder -> amImageQueryBuilder.forFileVersion(_fileVersion)
.withConfigurationStatus(AMImageQueryBuilder.ConfigurationStatus.ANY)
.orderBy(AMImageAttribute.AM_IMAGE_ATTRIBUTE_WIDTH, AMImageQueryBuilder.SortOrder.ASC)
.done());
The orderBy
arguments AMImageAttribute.AM_IMAGE_ATTRIBUTE_WIDTH
and
AMImageQueryBuilder.SortOrder.ASC
specify the image width and ascending sort,
respectively. You can alternatively use
AMImageAttribute.AM_IMAGE_ATTRIBUTE_HEIGHT
to sort by image height, and
AMImageQueryBuilder.SortOrder.DESC
to perform a descending sort.
Next, you’ll learn how to specify approximate attribute values when getting adapted images.
Getting Adapted Images with Fuzzy Attributes
Adaptive Media also lets you get adapted images that match fuzzy attributes (approximate attribute values). For example, fuzzy attributes let you ask for adapted images whose height is around 200px, or whose size is around 100kb. The API returns a stream with elements ordered by how close they are to the specified attribute. For example, imagine that there are four image resolutions that have adapted images with the heights 150px, 350px, 600px, and 900px. Searching for adapted images whose height is approximately 400px returns this order in the stream: 350px, 600px, 150px, 900px.
So how close, exactly, is close? It depends on the attribute. In the case of
width, height, and length, a numeric comparison orders the images. In the case
of content type, file name, or UUID, the comparison is more tricky because these
attributes are strings and thus delegated to
the Java String.compareTo
method.
To specify a fuzzy attribute, call the with
method with your search criteria
just before calling the done()
method. The with
method takes two arguments:
the image attribute, and that attribute’s approximate value. For example, this
code gets adapted images whose height
(AMImageAttribute.AM_IMAGE_ATTRIBUTE_HEIGHT
) is approximately 400px:
Stream<AdaptiveMedia<AMImageProcessor>> adaptiveMediaStream =
_amImageFinderImpl.getAdaptiveMediaStream(
amImageQueryBuilder -> amImageQueryBuilder.forFileVersion(_fileVersion)
.with(AMImageAttribute.AM_IMAGE_ATTRIBUTE_HEIGHT, 400).done());
To search for image width instead, use
AMImageAttribute.AM_IMAGE_ATTRIBUTE_WIDTH
as the first argument to the width
method.
Using the Adaptive Media Stream
Once you have the AdaptiveMedia
stream, you can get the information you need
from it. For example, this code prints the URI for each adapted image:
adaptiveMediaStream.forEach(
adaptiveMedia -> {
System.out.println(adaptiveMedia.getURI());
}
);
You can also get other values and attributes from the AdaptiveMedia
stream.
Here are a few examples:
// Get the InputStream
adaptiveMedia.getInputStream()
// Get the content length
adaptiveMedia.getValueOptional(AMAttribute.getContentLengthAMAttribute())
// Get the image height
adaptiveMedia.getValueOptional(AMImageAttribute.AM_IMAGE_ATTRIBUTE_HEIGHT)
Awesome! Now you know how to find and use adapted images.
Related Topics
Displaying Adapted Images in Your App