adobe/stock-api-libjava

Name: stock-api-libjava

Owner: Adobe Systems Incorporated

Description: Java implementation of the Stock APIs

Created: 2018-02-27 23:05:36.0

Updated: 2018-03-16 21:49:40.0

Pushed: 2018-03-16 21:49:39.0

Homepage:

Size: 1691

Language: Java

GitHub Committers

UserMost Recent Commit# Commits

Other Committers

UserEmailMost Recent Commit# Commits

README

Stock API Java SDK

Overview

This is a Java implementation of the various APIs provided by the Adobe Stock services.

Getting Started

This is a maven project. Following steps are needed for getting started with this project:

Clean
clean
Build

To build the project, you can run the below command on console -

package

The packages jar can be found at target/ folder with the name stockapissdk-<version>.jar. This will also download the depenedent jars into target/libs/ folder.

The above command will by default run the linting, test cases and the code coverage along with building the project. The linting results will be shown within the console output itself and if there are any issues the build will stop and fail instantly. If there are no linting issues found, the build will continue to build the project. It will also generate the detailed test case and coverage reports for you.

While running the above command if clean project is not run, it may throw some random errors. So it is advisable to run below command which does cleaning as well as building in the same step -

clean package
Lint with Checkstyle

This project uses Checkstyle for linting. By default, checkstyle offers two global check configurations -

We are using Sun Code Conventions here.

Linting checks are enforced with the build step itself. By default, the linting will run first and if there are any issues the build will fail. However, if you want to run the checkstyle checks separately, you can run below command to get the checkstyle results in console -

checkstyle:check

You can also generate the reports of the checkstyle results. For the reports, please run the regular site command -

site
Running Test Suites

However, the building project will run the tests automatically but if you need to run the tests separately, please run the below command in console -

test
Coverage

Just run the build project as mentioned above, it should generate the coverage reports along with the test results and building the project. As mentioned above coverage reports can be found at <project directory>/target/jacoco/index.html

Generate Maven Project Reports

To generate the maven project report, please run the below command -

site

For now, it should generate the Dependencies report and the checkstyle results reports for you.

Integration Guide

To start using Java SDK, you need to add stockapissdk-[version].jar into your project build path. You can download the source code and compile locally with maven command as mentioned in the Getting Started section above to generate the latest stockapissdk-[version].jar. (Please install maven if it's not already there.)

When you build the project, you will find the dependent jars in the target/libs/ folder. If these are not already in your environment, you'll need to add them to your build path. Below is the list of dependent jars -

Usage
StockConfig

StockConfig maintains the configuration of stock apis. In order to use the Stock APIs, one must create the object of StockConfig.

Methods Example

Below is the sample how you can instantiate the StockConfig and initialize it -

kConfig config = new StockConfig().setApiKey("TestApiKey").setProduct("TestProduct").setProductLocation("Libraries/1.0.0 ").setTargetEnvironment(Environment.PROD);
Accessing SearchFiles
SearchFiles

SearchFiles api class will allow you to access the Search/Files Stock Api. You can query Adobe Stock for assets that meet your specified search criteria. You can construct the SearchFilesRequest object to set filters, sort order, set search keywords etc. for the Search/Files api.

The SearchFiles provides paginated interface which allows you to call its methods (for e.g. getNextResponse, getPreviousResponse etc.) multiple times to retrieve the subsequent search results in order. It maintains the current state of searchFiles request and initially, the state is pointing invalid search files results. As soon as, the getNextReponse method is called, it makes Search/Files api call and returns the results with SearchFilesReponse object. The getNextResponse moves the state to next page and fetch the response for the same. Similarly, the getPreviousResponse and getResponsePage methods can be used to move one page behind and skip to a particular search page index respectively.

Instantiation

You can construct the object of this class with below arguments -

Example

Sample code to instantiate the SearchFiles Api -

ic static void main(String[] args) {
try {
    //List of result columns
    ResultColumn[] resultColumns = { ResultColumn.NB_RESULTS,
            ResultColumn.ID, ResultColumn.TITLE };

    //Instantiating and initializing StockConfig
    StockConfig config = new StockConfig().setApiKey("StockClientApiKey").setProduct(
            "Stock Client/1.0.0");

    //Constructing SearchParameters
    SearchParameters params = new SearchParameters()
                    .setWords("Tree House")
                    .setFilterOrientation(AssetOrientation.HORIZONTAL);

    //Constructing SearchFilesRequest
    SearchFilesRequest searchRequest = new SearchFilesRequest()
                        .setSearchParams(params)
                        .setResultColumns(resultColumns);

    //Getting hold of SearchFiles API object
    SearchFiles searchFiles = new SearchFiles(config, accessToken, searchRequest);

    //Now, you can call getNextResponse to get the search results
    SearchFilesResponse response = searchFiles.getNextReponse();

} catch (StockException e) {
    e.printStackTrace();
}

More examples can be found at the end of this document.

Methods SearchFilesRequest

In order to make SearchFiles API call, you need to create a SearchFileRequest object to define the search criterion for search files results. You can set the various search parameters, locale and required result columns supported by Stock Search/Files api here.

Here is the mapping of Search/Files api query parameters with the setters methods that you can use to set the corresponding parameters in Java Stock SDK -

|API URL Query Parameter| Setter Methods in SearchFilesRequest |Description| |—|—|—| |locale|setLocale|Sets location language code. For e.g. “en-US”, “fr-FR” etc.| |search_parameters[*]|setSearchParams|Sets An object of SearchParameters where one can set all supported search_parameters| |similar_image|setSimilarImage| Sets an image data for visual similarity search. It will only be considered if similar image in SearchParameters is set to true. | |result_columns[]| setResultColumns | Allows to set the list of result columns required in the search results. If you are not setting result columns, it will set all default columns in result_column array at api level. For more details, read Result Columns section below.|

SearchParameters

SearchParameters allows to set the various search_parameters (URL query parameters) supported by Search/Files Stock api. This is the class where you can actually set the search keywords, limit, sort order, filters, media_id etc.

Mapping of query parameter search_parameters[*] with SearchParameters class setter methods -

|Search Parameter| Setter Methods | Related Enums (If applicable) |Description| |—|—|—|—| |search_parameters[words]|setWords| |Allows to set the key words that you want to search| |search_parameters[limit]|setLimit| |Allows to set maximum number of assets to return in the call.| |search_parameters[offset]|setOffset| |Allows to set the start position in search results. | |search_parameters[order]|setOrder| AssetsOrder|Allows to set sorting order in which it will return found assets| |search_parameters[creator_id]|setCreatorId| |Allows to search by a specific asset creator's ID| |search_parameters[media_id]|setMediaId| |Allows to search for one specific asset by its unique identifier (media_id)| |search_parameters[model_id]|setModelId| |Allows to search for assets that portray a specific person (model) using the model's ID| |search_parameters[serie_id]|setSerieId| |Allows to search for assets in the specified series using the series ID| |search_parameters[gallery_id]|setGalleryId| |Allows to search with a specific galleryId filter| |search_parameters[similar]|setSimilar| |Allows to search for assets that are similar in appearance to an asset with a specific media ID| |search_parameters[similar_url]|setSimilarURL| |Allows to search for assets that are similar in appearance to an image at a specific URL| |search_parameters[category]|setCategory| |Allows to search for assets with a specific category ID| |search_parameters[thumbnail_size]|setThumbnailSize| AssetThumbSize|Allows to set the size of thumbnail(in pixels) to return for each found asset| |search_parameters[filters][area_pixels]|setFilterAreaPixels| |Allows to set image sizes in pixels for returned assets| |search_parameters[filters][3d_type_id][]|setFilter3DTypeIds|Asset3DType[]|Allows to set array specifying which 3D types to return| |search_parameters[filters][template_type_id][]|setFilterTemplateTypes | AssetTemplatesType[] | Allows to set array specifying which template types to return| |search_parameters[filters][template_category_id][]|setFilterTemplateCategoryIds| |Allows to set array specifying which template categories to return| |search_parameters[filters][has_releases]|setFilterHasReleases|AssetHasReleases|Allows to return only that assets which has model or property releases| |search_parameters[filters][content_type:photo]|setFilterContentTypePhoto| |Allows to include found assets that are photos| |search_parameters[filters][content_type:illustration]|setFilterContentTypeIllustration| |Allows to include found assets that are illustrations| |search_parameters[filters][content_type:vector]|setFilterContentTypeVector| |Allows to include found assets that are vectors| |search_parameters[filters][content_type:video]|setFilterContentTypeVideo| |Allows to include found assets that are videos| |search_parameters[filters][content_type:3d]|setFilterContentType3D| |Allows to include found assets that are 3D items| |search_parameters[similar_image]|setSimilarImage| |Allows to set whether to use similar_image data for visual similarity search| |search_parameters[filters][content_type:all]|setFilterContentTypeAll| |Allows to include found assets of all content_types| |search_parameters[filters][offensive:2]|setFilterOffensive2| |Allows to return found assets only if they are flagged as including Explicit/Nudity/Violence| |search_parameters[filters][isolated:on]|setFilterIsolatedOn| |Allows to return found assets only if the subject is isolated from the background by being on a uniformly colored background| |search_parameters[filters][panoramic:on]|setFilterPanoromicOn| |Allows to return found assets only if they are panoramic| |search_parameters[filters][orientation]|setFilterOrientation| AssetOrientation |Allows to return found assets of the specified orientation| |search_parameters[filters][age]|setFilterAge|AssetAge|Allows to return found assets of the specified age| |search_parameters[filters][video_duration]|setFilterVideoDuration|AssetVideoDuration|Alows to return videos whose duration is no longer than the specified duration in seconds| |search_parameters[filters][Premium]|setPremium|AssetPremiumCategory|Allows to return found assets with premium (pricing) level| |search_parameters[filters][colors]|setFilterColors| |Allows to return only found assets that contain the specified colors| |search_parameters[filters][Editorial]|setFilterEditorial| |Allows to return only found assets that are editorial| |search_parameters[filters][content_type:template]|setFilterContentTypeTemplate| |Allows to include found assets that are of template types|

Result Columns

You can create array of ResultColumn enums to define columns that you want to include in your search results.

Example 
ltColumn[] resultColumns = { ResultColumn.NB_RESULTS, ResultColumn.ID, ResultColumn.TITLE };
Note

If you are not setting result columns, it will set following columns in result_column array by default.

Making a SearchFilesRequest and Calling search files api

These are the complete examples showing how a search request is created and then search api is called, which in turn returns search results in the form of serchFileRequest.

ic static void main(String[] args) {
try {
    //List of result columns
    ResultColumn[] resultColumns = { ResultColumn.NB_RESULTS,
            ResultColumn.ID, ResultColumn.TITLE };

    //Instantiating and initializing StockConfig
    StockConfig config = new StockConfig().setApiKey("StockClientApiKey").setProduct(
            "Stock Client/1.0.0");

    //Constructing SearchParameters
    SearchParameters params = new SearchParameters()
                    .setWords("Tree House")
                    .setFilterOrientation(AssetOrientation.HORIZONTAL);

    //Constructing SearchFilesRequest
    SearchFilesRequest searchRequest = new SearchFilesRequest()
                        .setSearchParams(params)
                        .setResultColumns(resultColumns);

    //Getting hold of SearchFiles API object
    SearchFiles searchFiles = new SearchFiles(config, accessToken, searchRequest);

    //Now, you can call getNextResponse to get the search results
    SearchFilesResponse response = searchFiles.getNextReponse();

    //Now, you can use these results to access total number of results
    System.out.println(response.getNbResults());

    //or, you can get various  stock files information
    System.out.println(response.getFiles().get(0).getTitle());
    System.out.println(response.getFiles().get(0).getCategory());
    System.out.println(response.getFiles().get(0).getCreatorName());

} catch (StockException e) {
    e.printStackTrace();
}


ic static void main(String[] args) {
try {
    //List of result columns
    ResultColumn[] resultColumns = { ResultColumn.NB_RESULTS,
                    ResultColumn.ID, ResultColumn.THUMBNAIL_110_URL,
                    ResultColumn.THUMBNAIL_110_WIDTH };

    //Instantiating and initializing StockConfig
    StockConfig config = new StockConfig().setApiKey("StockClientApiKey").setProduct(
            "Stock Client/1.0.0");

    //Constructing SearchParameters
    SearchParameters params = new SearchParameters().setThumbnailSize(AssetThumbSize.BIG)
                    .setFilterContentTypePhoto(true);

    //Constructing SearchFilesRequest
    SearchFilesRequest searchRequest = new SearchFilesRequest()
                        .setSearchParams(params)
                        .setResultColumns(resultColumns);

    //Getting hold of SearchFiles API object
    SearchFiles searchFiles = new SearchFiles(config, accessToken, searchRequest);

    //Now, you can call getNextResponse to get the search results
    SearchFilesResponse response = searchFiles.getNextReponse();

    //Now, you can get various fields of stock files
    System.out.println(response.getFiles().get(0).getThumbnail110Url());

    //Now, you can call getNextResponse to get the next search results
    SearchFilesResponse response = searchFiles.getNextReponse();

    //Perform some operation

    //Now, you can call getPreviousResponse to get the previous search results
    SearchFilesResponse response = searchFiles.getPreviousResponse();

    //Now, you can use previous results for getting title or other info from stock file.
    System.out.println(response.getFiles().get(0).getIsLicensed());

} catch (StockException e) {
    e.printStackTrace();
}


ic static void main(String[] args) {
try {
    //List of result columns
    ResultColumn[] resultColumns = { ResultColumn.NB_RESULTS, ResultColumn.KEYWORDS,
                        ResultColumn.HAS_RELEASES, ResultColumn.COMP_URL};

    //Instantiating and initializing StockConfig
    StockConfig config = new StockConfig().setApiKey("StockClientApiKey").setProduct(
            "Stock Client/1.0.0");

    //Constructing SearchParameters
    SearchParameters params = new SearchParameters()
                    .setWords("City")
                    .setFilterContentTypeVector(true)
                    .setFilterHasReleases(AssetHasReleases.TRUE);

    //Constructing SearchFilesRequest
    SearchFilesRequest searchRequest = new SearchFilesRequest()
                        .setSearchParams(params)
                        .setResultColumns(resultColumns);

    //Getting hold of SearchFiles API object
    SearchFiles searchFiles = new SearchFiles(config, accessToken, searchRequest);

    //Now, you can call getResponsePage to skip to a specific search files response page
    SearchFilesResponse response = searchFiles.getResponsePage(2);

    //Now, you can use these results for getting various info from stock file.
    System.out.println(response.getFiles().get(0).getCompUrl());
    System.out.println(response.getFiles().get(0).getHasReleases());


} catch (StockException e) {
    e.printStackTrace();
}
Accessing SearchCategory
SearchCategory

SearchCategory API class allows you to access the Search/Category and Search/CategoryTree Stock APIs. Each stock asset is placed into a category that classifies the asset, such as “Travel” or “Hobbies and Leisure” and each category has a unique identifying number, a name, and a path that you can use to access other assets in the same category.

You can construct the SearchCategoryRequest object to set category identifier and locale information. Then you can call getCategory method to get information about a category of stock assets in the form of StockFileCategory object. You can also call getCategoryTree method to retrieve information for zero or more category identifiers in the form of list of StockFileCategory object.

Instantiation

You can construct the object of this class with below arguments -

Example

Sample code to instantiate the SearchCategory API -

ic static void main(String[] args) {
try {

    //Instantiating and initializing StockConfig
    StockConfig config = new StockConfig().setApiKey("AdobeStockClient1")
                .setProduct("Adobe Stock Lib/1.0.0");

    //Constructing SearchCategoryRequest
    SearchCategoryRequest request = new SearchCategoryRequest()
                .setCategoryId(1043);

    //Getting hold of SearchCategory API object
    SearchCategory searchCategory = new SearchCategory(config);

    //Now you can call getCategory to get category information
    StockFileCategory categoryResponse = searchCategory.getCategory(request);

    //You can also call getCategoryTree to get information about list of categories
    ArrayList<StockFileCategory> categoryTreeResponse = searchCategory
                .getCategoryTree(request);

} catch (StockException e) {
    e.printStackTrace();
}
Methods SearchCategoryRequest

In order to make SearchCategory/SearchCategoryTree API call, you need to create a SearchCategoryRequest object to define the search criterion for search category results. You can set category identifier and location language code supported by Stock Search Category/Category Tree API here.

Here is the mapping of Search Category/CategoryTree API query parameters with the setters methods that you can use to set the corresponding parameters in Java Stock SDK -

|API URL Query Parameter| Setter Methods in SearchCategoryRequest |Description| |—|—|—| |locale|setLocale|Sets location language code. For e.g. “en-US”, “fr-FR” etc.| |category_id|setCategoryId|Sets unique identifier for an existing category for e.g 1043|

StockFileCategory

It represents the search result returned from Stock Search/Category API. The SearchCategory class methods for e.g. getCategory returns the object of StockFileCategory initialized with the results returned from the Search/Category API. StockFileCategory allows you to -

Accessing License
License

License class allows you to purchase an asset, information about purchasing the asset, information about a user's licensing (entitlement) status, determine whether the user has an existing license for an asset,for notifying the system when a user abandons a licensing operation, request a license for an asset for that user if user have authorization for licensing assets and fetch the URL of the asset if it is already licensed.

Instantiation

You can construct the object of this class with below arguments -

License Request

In order to call License APIs you need to create LicenseRequest object for licensing assets, for getting licensing information about a specific asset for specific user, for notifying the system when a user abandons a licensing operation, for getting the licensing capabilities for a specific user.

|Request Parameter| Setter Methods | Related Enums (If applicable) |Description| |—|—|—|—| |content_id|setContentId| |Asset's unique identifer.You can get this from a Search response's id attribute| |license|setLicenseState|AssetLicenseState|Use only with Content/Info, Content/License, and Member/Profile. The Adobe Stock licensing state for the asset.| |locale |setLocale| |Use only with Member/Profile.Optional. Location language code for the API to use when returning localized messages. The API can usually get the user's default locale through the Authorization header. This value overrides that or provides a locale if not available through Authorization.| |state |setPurchaseState|AssetPurchaseState|Use only with Member/Abandon.The purchase_options.state from the Member/Profile results.| |cce_agency |setLicenseReference| |Array of license references of type LicenseReference. Use only with Content/License API.|

License State

Adobe Stock licensing state for the asset.

Purchase States

User's purchase relationship to an asset.

Creating License Request and Initializing Licensing API 
ic static void main(String args[]) {
    try {
        //Valid access token for stock files.
        String accessToken = "Ims Token";

        //Initialize config
        StockConfig config = new StockConfig()
                .setApiKey("AdobeStockClient1")
                .setProduct("Adobe Stock Lib/1.0.0");

        //Creating License Request
        LicenseRequest request = new LicenseRequest()
                .setContentId(84071201).setLicenseState(AssetLicenseState.STANDARD);

        //Initialize License Apis  
        License license = new License(config);

    } catch (Exception e) {
        e.printStackTrace();
    }
}
License Response

After calling various APIs in License class, reponse is returned in the form of LicenseResponse. It contains following fields. All class objects used in response are defined below.

|Request Parameter| Getter Methods | Related Class |Description| |—|—|—|—| |available_entitlement |getEntitlement|LicenseEntitlement|Information about licenses available for the user. See LicenseEntitlement| |purchase_options|getPurchaseOptions|LicensePurchaseOptions|Information about the user's purchasing options for the asset. See LicensePurchaseOptions| |member|getMemberinfo|LicenseMemberInfo|Information about the user. See LicenseMemberInfo| |license_references|getLicenseReferences|LicenseReferenceResponse|List of license references of the user. See LicenseReferenceResponse| |contents|getContentMap|LicenseContent|Mapping from Asset unique identifier to Asset Licensing information. See LicenseContent|

LicenseEntitlement LicensePurchaseOptions LicenseMemberInfo LicenseReferenceResponse LicenseContent Methods Examples

Examples showing how all methods are called with LicenseRequest and return LicenseResponse.

getContentInfo Example 
ic static void main(String args[]) {
    try {
        //Valid access token for stock files.
        String accessToken = "Ims Token";

        //Initialize config
        StockConfig config = new StockConfig()
                .setApiKey("AdobeStockClient1")
                .setProduct("Adobe Stock Lib/1.0.0");

        //Creating License Request
        LicenseRequest request = new LicenseRequest()
                .setContentId(84071201).setLicenseState(AssetLicenseState.STANDARD);

        //Initializing License Object to call getContentInfo method
        License license = new License(config);

        //Calling getContentInfo and returning LicenseResponse Object
        LicenseResponse licenseResponse = license.getContentInfo(request,accessToken);

        System.out.println("Content Info Response:");
        print("Content id",licenseResponse.getContents().get(0).getContentId());
        print("Content purchase state",licenseResponse.getContents().get(0).getPurchaseDetails().getPurchaseState());
    } catch (Exception e) {
        e.printStackTrace();
    }
}
getContentLicense Example 
blic static void main(String args[]) {
    try {
        //Valid access token for stock files.
        String accessToken = "Ims Token";

        //Initialize config
        StockConfig config = new StockConfig()
                .setApiKey("AdobeStockClient1")
                .setProduct("Adobe Stock Lib/1.0.0");


        LicenseReference ref = new LicenseReference();
        ref.setLicenseReferenceId(1).setLicenseReferenceValue("Trees");
        LicenseReference refArray[] = {ref};

        //Creating License Request
        LicenseRequest request = new LicenseRequest().setContentId(84071201)
                .setLocale("en-US").setLicenseState(AssetLicenseState.EXTENDED).setLicenseReference(refArray)
                .setPurchaseState(AssetPurchaseState.PURCHASED);

        //Initializing License Object to call getContentLicense method
        License license = new License(config);

        //Calling getContentLicense and returning LicenseResponse Object
        LicenseResponse licenseResponse = license.getContentLicense(request,accessToken);

        System.out.println("Content License Response:");
        print("Content id",licenseResponse.getContents().get(0).getContentId());
        print("Content purchase state",licenseResponse.getContents().get(0).getPurchaseDetails().getPurchaseState());
    } catch (Exception e) {
        e.printStackTrace();
    }
}
getMemberProfile Example 
ic static void main(String args[]) {
    try {
        //Valid access token for stock files.
        String accessToken = "Ims Token";

        //Initialize config
        StockConfig config = new StockConfig()
                .setApiKey("AdobeStockClient1")
                .setProduct("Adobe Stock Lib/1.0.0");

        //Creating License Request
        LicenseRequest request = new LicenseRequest()
                .setContentId(84071201).setLicenseState(AssetLicenseState.STANDARD);

        //Initializing License Object to call getMemberProfile method
        License license = new License(config);

        //Calling getMemberProfile
        LicenseResponse response = license.getMemberProfile(request, accessToken);

        System.out.println("Member Profile Response:");
        print("Entitlement Quota:",response.getEntitlement().getQuota() );
        print("Purchase Options Message", response.getPurchaseOptions().getMessage());
    } catch (Exception e) {
        e.printStackTrace();
    }
}
abandonLicense Example 
ic static void main(String args[]) {
    try {
        //Valid access token for stock files.
        String accessToken = "Ims Token";

        //Initialize config
        StockConfig config = new StockConfig()
                .setApiKey("AdobeStockClient1")
                .setProduct("Adobe Stock Lib/1.0.0");

        //Creating License Request
        LicenseRequest request = new LicenseRequest()
                .setContentId(84071201).setLicenseState(AssetLicenseState.STANDARD);

        //Initializing License Object to call abandonLicense method
        License license = new License(config);

        //Calling getMemberProfile
        license.abandonLicense(request, accessToken);

    } catch (Exception e) {
        e.printStackTrace();
    }
}
downloadAsset Example 
ic static void main(String args[]) {
    try {
        //Valid access token for stock files.
        String accessToken = "Ims Token";

        //Initialize config
        StockConfig config = new StockConfig()
                .setApiKey("AdobeStockClient1")
                .setProduct("Adobe Stock Lib/1.0.0");

        //Creating License Request
        LicenseRequest request = new LicenseRequest()
                .setContentId(84071201).setLicenseState(AssetLicenseState.STANDARD);

        //Initializing License Object to call downloadAsset method
        License license = new License(config);

        //Calling downloadAsset
        String assetUrl = license.downloadAsset(request, accessToken);

        System.out.println("Asset Download Response:");
        print("Asset URL", assetUrl);

    } catch (Exception e) {
        e.printStackTrace();
    }
}
Accessing LicenseHistory
LicenseHistory

LicenseHistory api class will allow you to access the LicenseHistory Stock Api. You can construct the LicenseHistoryRequest object to set offset, limit, set result columns etc. for the LicenseHistory api.

The LicenseHistory api provides paginated interface which allows you to call its methods (for e.g. getNextLicenseHistory, getPreviousLicenseHistory etc.) multiple times to retrieve the subsequent results in order. It maintains the current state of LicenseHistory request and initially, the state is pointing invalid LicenseHistory files results. As soon as, the getNextLicenseHistory method is called, it makes LicenseHistory api call and returns the results with LicenseHistoryResponse object. The getNextLicenseHistory moves the state to next page and fetch the response for the same. Similarly, the getPreviousLicenseHistory and getLicenseHistoryPage methods can be used to move one page behind and skip to a particular LicenseHistory page index respectively.

Instantiation

You can construct the object of this class with below arguments -

Example

Sample code to instantiate the LicenseHistory Api -

   public static void main(String args[]) {
   try {
    //List of result columns
    LicenseHistoryResultColumn[] columns = { LicenseHistoryResultColumn.THUMBNAIL_1000_HEIGHT,
                LicenseHistoryResultColumn.THUMBNAIL_1000_URL,
                LicenseHistoryResultColumn.THUMBNAIL_1000_WIDTH };

    //Instantiating and initializing StockConfig
    StockConfig config = new StockConfig()
                .setApiKey("LucaIOS1")
                .setProduct("Spark Page")
                .setTargetEnvironment(Environment.PROD);

    //Constructing SearchParametersLicenseHistory
    SearchParametersLicenseHistory params = new SearchParametersLicenseHistory()
                .setLimit(2).setOffset(0);

    //Constructing LicenseHistoryRequest
    LicenseHistoryRequest request = new LicenseHistoryRequest()
                .setSearchParams(params).setResultColumns(columns);

    LicenseHistory licensehistory = new LicenseHistory(config, accesstoken, request);

    //Now, you can call getNextLicenseHistory to get the results
    LicenseHistoryResponse response = licensehistory.getNextLicenseHistory();

} catch (StockException e) {
    e.printStackTrace();
}

More examples can be found at the end of this document.

Methods LicenseHistoryRequest

In order to make LicenseHistory API call, you need to create a LicenseHistoryRequest object to define the criterion for LicenseHistory files results. You can set the various search parameters, locale and required result columns supported by Stock LicenseHistory api here.

Here is the mapping of LicenseHistory api query parameters with the setters methods that you can use to set the corresponding parameters in Java Stock SDK -

|API URL Query Parameter| Setter Methods in LicenseHistoryRequest |Description| |—|—|—| |locale|setLocale|Sets location language code. For e.g. “en-US”, “fr-FR” etc.| |search_parameters[*]|setSearchParams|Sets An object of SearchParamLicenseHistory where one can set all supported search_parameters| |result_columns[]| setResultColumns | Allows to set the list of result columns required in the search results. If you are not setting result columns, it will set all default columns in result_column array at api level. For more details, read Result Columns section below.|

SearchParameters

SearchParametersLicenseHistory allows to set the various search_parameters (URL query parameters) supported by LicenseHistory api. This is the class where you can actually set the limit, offset, thumbnail_size etc.

Mapping of query parameter search_parameters[*] with SearchParametersLicenseHistory class setter methods -

|Search Parameter| Setter Methods |Related Enums (If applicable) | Description| |—|—|—|—| |search_parameters[limit]|setLimit| |Allows to set maximum number of assets to return in the call.| |search_parameters[offset]|setOffset| |Allows to set the start position in results. | |search_parameters[thumbnail_size]|setThumbnailSize| LicenseHistoryThumbnailSize |Allows to set thumbnail size.Valid values - 110, 160,220,240,500, 1000 |

Result Columns

You can create array of LicenseHistoryResultColumn enums to define columns that you want to include in your search results.

Example 
nseHistoryResultColumn[] columns = { LicenseHistoryResultColumn.THUMBNAIL_1000_HEIGHT,
                LicenseHistoryResultColumn.THUMBNAIL_1000_URL,
                LicenseHistoryResultColumn.THUMBNAIL_1000_WIDTH };
Note

If you are not setting result columns, it will set following columns in result_column array by default.

LicenseHistoryResponse

It represents the LicenseHistory results returned with Stock LicenseHistory API. The LicenseHistory class methods for e.g. getNextLicenseHistory returns the object of LicenseHistoryResponse initialized with the results returned from the LicenseHistory api. LicenseHistoryResponse allows you to -

Making a LicenseHistoryRequest and Calling LicenseHistory api

These are the complete examples showing how a request is created and then LicenseHistory api is called, which in turn returns results in the form of LicenseHistoryRequest.

ic static void main(String[] args) {
try {
    //List of result columns
    LicenseHistoryResultColumn[] columns = { LicenseHistoryResultColumn.THUMBNAIL_1000_HEIGHT,
                LicenseHistoryResultColumn.THUMBNAIL_1000_URL,
                LicenseHistoryResultColumn.THUMBNAIL_1000_WIDTH };

    //Instantiating and initializing StockConfig
    StockConfig config = new StockConfig().setApiKey("LucaIOS1").setProduct("Spark Page");

    //Constructing SearchParametersLicenseHistory
    SearchParametersLicenseHistory params = new SearchParametersLicenseHistory()
                .setLimit(2).setOffset(0);

    //Constructing LicenseHistoryRequest
    LicenseHistoryRequest request = new LicenseHistoryRequest()
                .setSearchParams(params).setResultColumns(columns);

    LicenseHistory licensehistory = new LicenseHistory(config, accesstoken, request);

    //Now, you can call getNextLicenseHistory to get the results
    LicenseHistoryResponse response = licensehistory.getNextLicenseHistory();

    //Now, you can use these results to access total number of results
    System.out.println(response.getNbResults());

    //or, you can get various  stock files information
    print("license date", response.getFiles().get(0).getLicenseDate());
    print("license state", response.getFiles().get(0).getLicenseState());
    print("width", response.getFiles().get(0).getWidth());

} catch (StockException e) {
    e.printStackTrace();
}


ublic static void main(String[] args) {
try {
    //List of result columns
    LicenseHistoryResultColumn[] columns = { LicenseHistoryResultColumn.THUMBNAIL_1000_HEIGHT,
                LicenseHistoryResultColumn.THUMBNAIL_1000_URL,
                LicenseHistoryResultColumn.THUMBNAIL_1000_WIDTH };

    //Instantiating and initializing StockConfig
    StockConfig config = new StockConfig().setApiKey("LucaIOS1").setProduct("Spark Page");

    //Constructing SearchParametersLicenseHistory
    SearchParametersLicenseHistory params = new SearchParametersLicenseHistory()
                .setLimit(2).setOffset(0);

    //Constructing LicenseHistoryRequest
    LicenseHistoryRequest request = new LicenseHistoryRequest()
                .setSearchParams(params).setResultColumns(columns);

    LicenseHistory licensehistory = new LicenseHistory(config, accesstoken, request);

    //Now, you can call getNextLicenseHistory to get the results
    LicenseHistoryResponse response = licensehistory.getNextLicenseHistory();

    //Perform some operation

    //Now, you can call getPreviousLicenseHistory to get the previous results
    LicenseHistoryResponse response = licensehistory.getPreviousLicenseHistory();

} catch (StockException e) {
    e.printStackTrace();
}


ublic static void main(String[] args) {
try {
    //List of result columns
    LicenseHistoryResultColumn[] columns = { LicenseHistoryResultColumn.THUMBNAIL_1000_HEIGHT,
                LicenseHistoryResultColumn.THUMBNAIL_1000_URL,
                LicenseHistoryResultColumn.THUMBNAIL_1000_WIDTH };

    //Instantiating and initializing StockConfig
    StockConfig config = new StockConfig().setApiKey("LucaIOS1").setProduct("Spark Page");

    //Constructing SearchParametersLicenseHistory
    SearchParametersLicenseHistory params = new SearchParametersLicenseHistory()
                .setLimit(2).setOffset(0);

    //Constructing LicenseHistoryRequest
    LicenseHistoryRequest request = new LicenseHistoryRequest()
                .setSearchParams(params).setResultColumns(columns);

    LicenseHistory licensehistory = new LicenseHistory(config, accesstoken, request);

    //Now, you can call getLicenseHistoryPage to get the results
    LicenseHistoryResponse response = licensehistory.getLicenseHistoryPage(2);

} catch (StockException e) {
    e.printStackTrace();
}
This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.