org.odpi.openmetadata.adapters.repositoryservices.igc.clientlibrary

Class IGCRestClient

java.lang.Object

org.odpi.openmetadata.adapters.repositoryservices.igc.clientlibrary.IGCRestClient

public class IGCRestClient
extends Object

Library of methods to connect to and interact with an IBM Information Governance Catalog environment using appropriate session management.

Methods are provided to interact with REST API endpoints and process results as JsonNode objects (ie. allowing direct traversal of the JSON objects) and through the use of registered POJOs to automatically (de-)serialise between the JSON form and a native Java object.

The native Java objects for out-of-the-box Information Governance Catalog asset types have been generated under org.odpi.openmetadata.adapters.repositoryservices.igc.model.* -- including different versions depending on the environment to which you are connecting.

For additional examples of using the REST API (eg. potential criteria and operators for searching, etc), see:

• IGC REST API: Tips, tricks, and time-savers
• IGC REST API: Sample REST API calls and use case descriptions

See Also:

registerPOJO(Class)

Field Summary

Fields

Modifier and Type	Field and Description
static String	EP_ASSET
static String	EP_BUNDLE_ASSETS
static String	EP_BUNDLES
static String	EP_LOGOUT
static String	EP_SEARCH
static String	EP_TYPES

Constructor Summary

Constructors

Constructor and Description
IGCRestClient()
IGCRestClient(String baseURL, String authorization) Default constructor used by the IGCRestClient.

Method Summary

Modifier and Type	Method and Description
File	createOpenIgcBundleFile(File directory) Generates an OpenIGC bundle zip file from the provided directory path, and returns the temporary file it creates.
boolean	deleteOpenIgcAsset(String assetXML) Delete using the provided OpenIGC asset XML: deleting the asset(s) specified within it.
void	disconnect() Disconnect from IGC REST API and invalidate the session.
static String	encodeBasicAuth(String username, String password) Utility function to easily encode a username and password to send through as authorization info.
com.fasterxml.jackson.databind.node.ArrayNode	getAllPages(com.fasterxml.jackson.databind.node.ArrayNode items, com.fasterxml.jackson.databind.JsonNode paging) Retrieve all pages of results from a set of paging details and items ...
List<Reference>	getAllPages(List<Reference> items, Paging paging) Retrieve all pages of results from a set of Paging details and items ...
Reference	getAssetById(String rid) Retrieve all information about an asset from IGC.
Reference	getAssetRefById(String rid) Retrieve only the minimal unique properties of an asset from IGC.
String	getBaseURL() Retrieve the base URL of this IGC REST API connection.
int	getDefaultPageSize() Retrieve the default page size for this IGC REST API connection.
IGCVersionEnum	getIgcVersion() Retrieve the version of the IGC environment (static member VERSION_115 or VERSION_117).
com.fasterxml.jackson.databind.JsonNode	getJsonAssetById(String rid) Retrieve all information about an asset from IGC.
com.fasterxml.jackson.databind.JsonNode	getNextPage(com.fasterxml.jackson.databind.JsonNode paging) Retrieve the next page of results from a set of paging details ...
ReferenceList	getNextPage(Paging paging) Retrieve the next page of results from a set of Paging details ...
List<String>	getOpenIgcBundles() Retrieve the set of OpenIGC bundles already defined in the environment.
Class	getPOJOForType(String typeName) Returns the POJO that is registered to serde the provided IGC asset type.
com.fasterxml.jackson.databind.node.ArrayNode	getTypes() Retrieves the list of metadata types supported by IGC.
String	getValueAsJSON(Reference asset) Attempt to convert the provided IGC object into JSON, based on the registered POJOs.
boolean	isSuccessfullyInitialised() Indicates whether the client was successfully initialised (true) or not (false).
Boolean	isWorkflowEnabled() Returns true iff the workflow is enabled in the environment against which the REST connection is defined.
com.fasterxml.jackson.databind.JsonNode	makeRequest(String endpoint, org.springframework.http.HttpMethod method, org.springframework.http.MediaType contentType, String payload) General utility for making requests.
protected Reference	readJSONIntoPOJO(com.fasterxml.jackson.databind.JsonNode jsonNode) Attempt to convert a JSON structure into a Java object, based on the registered POJOs.
Reference	readJSONIntoPOJO(String json) Attempt to convert the JSON string into a Java object, based on the registered POJOs.
ReferenceList	readJSONIntoReferenceList(String json) Attempt to convert the JSON string into a ReferenceList.
void	registerPOJO(Class clazz) Register a POJO as an object to handle serde of JSON objects. Note that this MUST be done BEFORE any object mappingRemoved (translation) is done! In general, you'll want your POJO to extend at least the model.Reference object in this package; more likely the model.MainObject (for your own OpenIGC object), or if you are adding custom attributes to one of the native asset types, consider directly extending that asset from model.generated.* To allow this dynamic registration to work, also ensure you have a 'public static String getIgcTypeId()' in your class set to the type that the IGC REST API uses to refer to the asset (eg.
ReferenceList	search(IGCSearch igcSearch) Retrieve all assets that match the provided search criteria from IGC.
com.fasterxml.jackson.databind.JsonNode	searchJson(IGCSearch igcSearch) Retrieve all assets that match the provided search criteria from IGC.
com.fasterxml.jackson.databind.JsonNode	searchJson(com.fasterxml.jackson.databind.JsonNode query) Retrieve all assets that match the provided search criteria from IGC.
void	setDefaultPageSize(int pageSize) Set the default page size for this IGC REST API connection.
boolean	update(IGCUpdate igcUpdate) Apply the update described by the provided update object.
com.fasterxml.jackson.databind.JsonNode	updateJson(String rid, com.fasterxml.jackson.databind.JsonNode value) Update the asset specified by the provided RID with the value(s) provided.
boolean	uploadFile(String endpoint, org.springframework.http.HttpMethod method, org.springframework.core.io.AbstractResource file) General utility for uploading binary files.
com.fasterxml.jackson.databind.JsonNode	upsertOpenIgcAsset(String assetXML) Upload the provided OpenIGC asset XML: creating the asset(s) if they do not exist, updating if they do.
boolean	upsertOpenIgcBundle(String name, org.springframework.core.io.AbstractResource file) Upload the specified bundle, creating it if it does not already exist or updating it if it does.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EP_TYPES

public static final String EP_TYPES

See Also:

Constant Field Values

EP_ASSET

public static final String EP_ASSET

See Also:

Constant Field Values

EP_SEARCH

public static final String EP_SEARCH

See Also:

Constant Field Values

EP_LOGOUT

public static final String EP_LOGOUT

See Also:

Constant Field Values

EP_BUNDLES

public static final String EP_BUNDLES

See Also:

Constant Field Values

EP_BUNDLE_ASSETS

public static final String EP_BUNDLE_ASSETS

See Also:

Constant Field Values

Constructor Detail

IGCRestClient

public IGCRestClient()

IGCRestClient

public IGCRestClient(String baseURL,
                     String authorization)

Default constructor used by the IGCRestClient.

Creates a new session on the server and retains the cookies to re-use the same session for the life of the client (or until the session times out); whichever occurs first.

Parameters:

baseURL - the base URL of the domain tier of Information Server

authorization - the Basic-encoded authorization string to use to login to Information Server

Method Detail

isSuccessfullyInitialised

public boolean isSuccessfullyInitialised()

Indicates whether the client was successfully initialised (true) or not (false).

Returns:

boolean

readJSONIntoPOJO

protected Reference readJSONIntoPOJO(com.fasterxml.jackson.databind.JsonNode jsonNode)

Attempt to convert a JSON structure into a Java object, based on the registered POJOs.

Parameters:

jsonNode - the JSON structure to convert

Returns:

Reference - an IGC object

readJSONIntoPOJO

public Reference readJSONIntoPOJO(String json)

Attempt to convert the JSON string into a Java object, based on the registered POJOs.

Parameters:

json - the JSON string to convert

Returns:

Reference - an IGC object

readJSONIntoReferenceList

public ReferenceList readJSONIntoReferenceList(String json)

Attempt to convert the JSON string into a ReferenceList.

Parameters:

json - the JSON string to convert

Returns:

ReferenceList

getValueAsJSON

public String getValueAsJSON(Reference asset)

Attempt to convert the provided IGC object into JSON, based on the registered POJOs.

Parameters:

asset - the IGC asset to convert

Returns:

String of JSON representing the asset

getIgcVersion

public IGCVersionEnum getIgcVersion()

Retrieve the version of the IGC environment (static member VERSION_115 or VERSION_117).

Returns:

IGCVersionEnum

getBaseURL

public String getBaseURL()

Retrieve the base URL of this IGC REST API connection.

Returns:

String

getDefaultPageSize

public int getDefaultPageSize()

Retrieve the default page size for this IGC REST API connection.

Returns:

int

setDefaultPageSize

public void setDefaultPageSize(int pageSize)

Set the default page size for this IGC REST API connection.

Parameters:

pageSize - the new default page size to use

encodeBasicAuth

public static String encodeBasicAuth(String username,
                                     String password)

Utility function to easily encode a username and password to send through as authorization info.

Parameters:

username - username to encode

password - password to encode

Returns:

String of appropriately-encoded credentials for authorization

uploadFile

public boolean uploadFile(String endpoint,
                          org.springframework.http.HttpMethod method,
                          org.springframework.core.io.AbstractResource file)

General utility for uploading binary files.

Parameters:

endpoint - the URL against which to upload the file

method - HttpMethod (POST, PUT, etc)

file - the Spring FileSystemResource or ClassPathResource containing the file to be uploaded

Returns:

boolean - indicates success (true) or failure (false)

makeRequest

public com.fasterxml.jackson.databind.JsonNode makeRequest(String endpoint,
                                                           org.springframework.http.HttpMethod method,
                                                           org.springframework.http.MediaType contentType,
                                                           String payload)

General utility for making requests.

Parameters:

endpoint - the URL against which to make the request

method - HttpMethod (GET, POST, etc)

contentType - the type of content to expect in the payload (if any)

payload - if POSTing some content, the JSON structure providing what should be POSTed

Returns:

JsonNode - JSON structure of the response

getTypes

public com.fasterxml.jackson.databind.node.ArrayNode getTypes()

Retrieves the list of metadata types supported by IGC.

Returns:

ArrayNode the list of types supported by IGC, as a JSON structure

getJsonAssetById

public com.fasterxml.jackson.databind.JsonNode getJsonAssetById(String rid)

Retrieve all information about an asset from IGC.

Parameters:

rid - the Repository ID of the asset

Returns:

JsonNode - the JSON response of the retrieval

getAssetById

public Reference getAssetById(String rid)

Retrieve all information about an asset from IGC. This can be an expensive operation that may retrieve far more information than you actually need.

Parameters:

rid - the Repository ID of the asset

Returns:

Reference - the IGC object representing the asset

See Also:

getAssetRefById(String)

getAssetRefById

public Reference getAssetRefById(String rid)

Retrieve only the minimal unique properties of an asset from IGC. This will generally be the most performant way to see that an asset exists and get its identifying characteristics.

Parameters:

rid - the Repository ID of the asset

Returns:

Reference - the minimalistic IGC object representing the asset

searchJson

public com.fasterxml.jackson.databind.JsonNode searchJson(com.fasterxml.jackson.databind.JsonNode query)

Retrieve all assets that match the provided search criteria from IGC.

Parameters:

query - the JSON query by which to search

Returns:

JsonNode - the first JSON page of results from the search

searchJson

public com.fasterxml.jackson.databind.JsonNode searchJson(IGCSearch igcSearch)

Retrieve all assets that match the provided search criteria from IGC.

Parameters:

igcSearch - the IGCSearch object defining criteria by which to search

Returns:

JsonNode - the first JSON page of results from the search

search

public ReferenceList search(IGCSearch igcSearch)

Retrieve all assets that match the provided search criteria from IGC.

Parameters:

igcSearch - search conditions and criteria to use

Returns:

ReferenceList - the first page of results from the search

updateJson

public com.fasterxml.jackson.databind.JsonNode updateJson(String rid,
                                                          com.fasterxml.jackson.databind.JsonNode value)

Update the asset specified by the provided RID with the value(s) provided.

Parameters:

rid - the Repository ID of the asset to update

value - the JSON structure defining what value(s) of the asset to update (and mode)

Returns:

JsonNode - the JSON structure indicating the updated asset's RID and updates made

update

public boolean update(IGCUpdate igcUpdate)

Apply the update described by the provided update object.

Parameters:

igcUpdate - update criteria to use

upsertOpenIgcBundle

public boolean upsertOpenIgcBundle(String name,
                                   org.springframework.core.io.AbstractResource file)

Upload the specified bundle, creating it if it does not already exist or updating it if it does.

Parameters:

name - the bundleId of the bundle

file - the Spring FileSystemResource or ClassPathResource containing the file to be uploaded

Returns:

boolean - indication of success (true) or failure (false)

createOpenIgcBundleFile

public File createOpenIgcBundleFile(File directory)

Generates an OpenIGC bundle zip file from the provided directory path, and returns the temporary file it creates.

Parameters:

directory - the directory under which the OpenIGC bundle is defined (ie. including an 'asset_type_descriptor.xml', an 'i18n' subdirectory and an 'icons' subdirectory)

Returns:

File - the temporary zip file containing the bundle

getOpenIgcBundles

public List<String> getOpenIgcBundles()

Retrieve the set of OpenIGC bundles already defined in the environment.

Returns:

List<String>

upsertOpenIgcAsset

public com.fasterxml.jackson.databind.JsonNode upsertOpenIgcAsset(String assetXML)

Upload the provided OpenIGC asset XML: creating the asset(s) if they do not exist, updating if they do.

Parameters:

assetXML - the XML string defining the OpenIGC asset

Returns:

JsonNode - the JSON structure indicating the updated assets' RID(s)

deleteOpenIgcAsset

public boolean deleteOpenIgcAsset(String assetXML)

Delete using the provided OpenIGC asset XML: deleting the asset(s) specified within it.

Parameters:

assetXML - the XML string defining the OpenIGC asset deletion

Returns:

boolean - true on success, false on failure

getNextPage

public com.fasterxml.jackson.databind.JsonNode getNextPage(com.fasterxml.jackson.databind.JsonNode paging)

Retrieve the next page of results from a set of paging details
... or if there is no next page, return an empty JSON Items set.

Parameters:

paging - the "paging" portion of the JSON response from which to retrieve the next page

Returns:

JsonNode - the JSON response of the next page of results

getAllPages

public com.fasterxml.jackson.databind.node.ArrayNode getAllPages(com.fasterxml.jackson.databind.node.ArrayNode items,
                                                                 com.fasterxml.jackson.databind.JsonNode paging)

Retrieve all pages of results from a set of paging details and items
... or if there is no next page, return the items provided.

Parameters:

items - the "items" array of the JSON response for which to retrieve all pages

paging - the "paging" portion of the JSON response for which to retrieve all pages

Returns:

JsonNode - the JSON containing all pages of results as an "items" array

getNextPage

public ReferenceList getNextPage(Paging paging)

Retrieve the next page of results from a set of Paging details
... or if there is no next page, return an empty JSON Items set.

Parameters:

paging - the "Paging" object from which to retrieve the next page

Returns:

ReferenceList - the ReferenceList containing the next page of results

getAllPages

public List<Reference> getAllPages(List<Reference> items,
                                   Paging paging)

Retrieve all pages of results from a set of Paging details and items
... or if there is no next page, return the items provided.

Parameters:

items - the List of items for which to retrieve all pages

paging - the Paging object for which to retrieve all pages

Returns:

List<Reference> - an List containing all items from all pages of results

disconnect

public void disconnect()

Disconnect from IGC REST API and invalidate the session.

registerPOJO

public void registerPOJO(Class clazz)

Register a POJO as an object to handle serde of JSON objects.
Note that this MUST be done BEFORE any object mappingRemoved (translation) is done!

In general, you'll want your POJO to extend at least the model.Reference object in this package; more likely the model.MainObject (for your own OpenIGC object), or if you are adding custom attributes to one of the native asset types, consider directly extending that asset from model.generated.*

To allow this dynamic registration to work, also ensure you have a 'public static String getIgcTypeId()' in your class set to the type that the IGC REST API uses to refer to the asset (eg. for Term.class it would be "term"). See the generated POJOs for examples.

Parameters:

clazz - the Java Class (POJO) object to register

See Also:

getPOJOForType(String)

getPOJOForType

public Class getPOJOForType(String typeName)

Returns the POJO that is registered to serde the provided IGC asset type.

Note that the POJO must first be registered via registerPOJO!

Parameters:

typeName - name of the IGC asset

Returns:

Class

See Also:

registerPOJO(Class)

isWorkflowEnabled

public Boolean isWorkflowEnabled()

Returns true iff the workflow is enabled in the environment against which the REST connection is defined.

Returns:

Boolean