org.odpi.egeria.connectors.ibm.igc.clientlibrary

Class IGCRestClient

java.lang.Object

org.odpi.egeria.connectors.ibm.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)

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	IGCRestClient(String baseURL, String authorization) 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.
	IGCRestClient(String baseURL, String user, String password) 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.
	IGCRestClient(String host, String port, String user, String password) Default constructor used by the IGCRestClient.

Method Summary

Modifier and Type	Method and Description
void	cacheTypeDetails(String typeName) Cache detailed information about the IGC object type.
String	create(IGCCreate igcCreate) Create the object described by the provided create object.
File	createOpenIgcBundleFile(File directory) Generates an OpenIGC bundle zip file from the provided directory path, and returns the temporary file it creates.
boolean	delete(String rid) Delete the object specified by the provided RID.
boolean	deleteOpenIgcAsset(String assetXML) Delete using the provided OpenIGC asset XML: deleting the asset(s) specified within it.
boolean	detectLineage(String jobRid) Run lineage detection against the provided job (by RID).
void	disconnect() Disconnect from IGC REST API and invalidate the session.
<T extends Reference> List<T>	getAllPages(String propertyName, ItemList<T> list) Retrieve all pages of results from a set of Paging details and items, or if there is no next page return the items provided.
List<String>	getAllPropertiesForType(String typeName) Retrieve the names of all properties for the provided IGC object type, or null if the type is unknown.
List<String>	getAllStringPropertiesForType(String typeName) Retrieve the names of all string properties for the provided IGC object type, or null if the type is unknown.
Reference	getAssetById(String rid) Retrieve all information about an asset from IGC.
Reference	getAssetById(String rid, ObjectCache cache) Retrieve all information about an asset from IGC.
Reference	getAssetRefById(String rid) Retrieve only the minimal unique properties of an asset from IGC.
<T extends Reference> T	getAssetWithSubsetOfProperties(String rid, String assetType, List<String> properties) This will generally be the most performant method by which to retrieve asset information, when only some subset of properties is required
<T extends Reference> T	getAssetWithSubsetOfProperties(String rid, String assetType, List<String> properties, int pageSize) This will generally be the most performant method by which to retrieve asset information, when only some subset of properties is required
<T extends Reference> T	getAssetWithSubsetOfProperties(String rid, String assetType, String[] properties) This will generally be the most performant method by which to retrieve asset information, when only some subset of properties is required
<T extends Reference> T	getAssetWithSubsetOfProperties(String rid, String assetType, String[] properties, int pageSize) This will generally be the most performant method by which to retrieve asset information, when only some subset of properties is required
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.
String	getDisplayNameForType(String typeName) Retrieve the display name of this IGC object type.
static String	getEncodedPathVariable(String pathVariable) Calculate a path-encoded URL for the provided endpoint.
IGCVersionEnum	getIgcVersion() Retrieve the version of the IGC environment (static member VERSION_115 or VERSION_117).
<T extends Reference> T	getModificationDetails(T object, ObjectCache cache) Ensures that the modification details of the asset are populated (takes no action if already populated or the asset does not support them).
<T extends Reference> ItemList<T>	getNextPage(String propertyName, ItemList<T> list) Retrieve the next page of results for the provided parameters.
List<String>	getNonRelationshipPropertiesForType(String typeName) Retrieve the names of all non-relationship properties for the provided IGC object type, or null if the type is unknown.
List<String>	getOpenIgcBundles() Retrieve the set of OpenIGC bundles already defined in the environment.
List<String>	getPagedRelationshipPropertiesForType(String typeName) Retrieve the names of all paged relationship properties for the provided IGC object type, or null if the type is unknown.
Class<?>	getPOJOForType(String assetType) Returns the POJO that is registered to serde the provided IGC asset type, preferring any that have been registered or defaulting to the out-of-the-box ones if there are no overrides.
Object	getPropertyByName(Reference object, String property) Retrieve a property of an IGC object based on the property's name.
TypeDetails	getTypeDetails(String typeName) Retrieves the type details (all properties and their details) for the provided type name in IGC.
TypeDetails	getTypeDetails(String typeName, boolean view, boolean create, boolean edit) Retrieves the type details (requested properties and their details) for the provided type name in IGC.
List<TypeHeader>	getTypes(com.fasterxml.jackson.databind.ObjectMapper objectMapper) 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	hasModificationDetails(String typeName) Indicates whether assets of this type include modification details (true) or not (false).
boolean	isCreatable(String typeName) Indicates whether the IGC object type can be created (true) or not (false).
static boolean	isEmbeddedAssetRid(String rid) Indicates whether the provided Repository ID (RID) represents an embedded asset (true) or not (false).
static boolean	isVirtualAssetRid(String rid) Indicates whether the provided Repository ID (RID) represents a virtual asset (true) or not (false).
Boolean	isWorkflowEnabled() Returns true iff the workflow is enabled in the environment against which the REST connection is defined.
String	makeCreateRequest(String endpoint, org.springframework.http.HttpMethod method, org.springframework.http.MediaType contentType, String payload) General utility for making creation requests.
String	makeRequest(String endpoint, org.springframework.http.HttpMethod method, org.springframework.http.MediaType contentType, String payload) General utility for making requests.
<T extends Reference> ItemList<T>	readJSONIntoItemList(String json) Attempt to convert the JSON string into an ItemList.
<T extends Reference> T	readJSONIntoPOJO(String json) Attempt to convert the JSON string into a Java object.
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 mapping (translation) is done! In general, you'll want your POJO to extend at least the Reference object, and more likely the InformationAsset (for your own OpenIGC object), or if you are adding custom attributes to one of the native asset types, consider directly changing that bean.
<T extends Reference> ItemList<T>	search(IGCSearch igcSearch) 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	start() Start the client by trying to connect based on the configured parameters.
boolean	update(IGCUpdate igcUpdate) Apply the update described by the provided update object.
boolean	uploadFile(String endpoint, org.springframework.http.HttpMethod method, org.springframework.core.io.AbstractResource file) General utility for uploading binary files.
String	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

Constructor Detail

IGCRestClient

public IGCRestClient(String host,
                     String port,
                     String user,
                     String password)
              throws IGCConnectivityException

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:

host - the services (domain) tier host

port - the services (domain) tier port number

user - the username with which to open and retain the session

password - the password for the user

Throws:

IGCConnectivityException - if there is any issue connecting to IGC

IGCRestClient

public IGCRestClient(String baseURL,
                     String user,
                     String password)
              throws IGCConnectivityException

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

user - the username with which to open and retain the session

password - the password of the user

Throws:

IGCConnectivityException - if there is any issue connecting to IGC

IGCRestClient

protected IGCRestClient(String baseURL,
                        String authorization)
                 throws IGCConnectivityException

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

Throws:

IGCConnectivityException - if there is any issue connecting to IGC

Method Detail

start

public boolean start()
              throws IGCConnectivityException,
                     IGCParsingException

Start the client by trying to connect based on the configured parameters.

Returns:

boolean indicating true if the client was successfully started, or false if not.

Throws:

IGCConnectivityException - if there is any issue connecting to IGC

IGCParsingException - if there is any issue parsing a response from IGC

readJSONIntoPOJO

public <T extends Reference> T readJSONIntoPOJO(String json)
                                         throws IGCParsingException

Attempt to convert the JSON string into a Java object.

Type Parameters:

T - the type of POJO into which to read

Parameters:

json - the JSON string to convert

Returns:

T - an IGC object that is at least a Reference, but can be more specific

Throws:

IGCParsingException - if the attempt to read the JSON fails

readJSONIntoItemList

public <T extends Reference> ItemList<T> readJSONIntoItemList(String json)
                                                       throws IGCParsingException

Attempt to convert the JSON string into an ItemList.

Type Parameters:

T - the type of items that should be in the ItemList

Parameters:

json - the JSON string to convert

Returns:

ItemList<T>

Throws:

IGCParsingException - if the attempt to read the JSON fails

getValueAsJSON

public String getValueAsJSON(Reference asset)
                      throws IGCParsingException

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

Throws:

IGCParsingException - if the attempt to read the JSON fails

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

isVirtualAssetRid

public static boolean isVirtualAssetRid(String rid)

Indicates whether the provided Repository ID (RID) represents a virtual asset (true) or not (false).

Parameters:

rid - the Repository ID (RID) to check

Returns:

boolean

isEmbeddedAssetRid

public static boolean isEmbeddedAssetRid(String rid)

Indicates whether the provided Repository ID (RID) represents an embedded asset (true) or not (false).

Parameters:

rid - the Repository ID (RID) to check

Returns:

boolean

uploadFile

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

General utility for uploading binary files.

Parameters:

endpoint - the REST resource 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)

Throws:

IGCConnectivityException - if there is any connectivity issue during the upload

makeRequest

public String makeRequest(String endpoint,
                          org.springframework.http.HttpMethod method,
                          org.springframework.http.MediaType contentType,
                          String payload)
                   throws IGCConnectivityException

General utility for making requests.

Parameters:

endpoint - the REST resource 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:

String - containing the body of the response

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

makeCreateRequest

public String makeCreateRequest(String endpoint,
                                org.springframework.http.HttpMethod method,
                                org.springframework.http.MediaType contentType,
                                String payload)
                         throws IGCConnectivityException

General utility for making creation requests.

Parameters:

endpoint - the REST resource against which to make the request

method - HttpMethod (POST, PUT, etc)

contentType - the type of content to expect in the payload

payload - the data that should be created

Returns:

String - containing the RID of the created object instance

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

getTypes

public List<TypeHeader> getTypes(com.fasterxml.jackson.databind.ObjectMapper objectMapper)
                          throws IGCConnectivityException,
                                 IGCParsingException

Retrieves the list of metadata types supported by IGC.

Parameters:

objectMapper - an ObjectMapper to use for translating the types list

Returns:

List<TypeHeader> the list of types supported by IGC

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the types payload

getTypeDetails

public TypeDetails getTypeDetails(String typeName)
                           throws IGCConnectivityException,
                                  IGCParsingException

Retrieves the type details (all properties and their details) for the provided type name in IGC.

Parameters:

typeName - the IGC type name for which to retrieve details

Returns:

TypeDetails

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the types payload

getTypeDetails

public TypeDetails getTypeDetails(String typeName,
                                  boolean view,
                                  boolean create,
                                  boolean edit)
                           throws IGCConnectivityException,
                                  IGCParsingException

Retrieves the type details (requested properties and their details) for the provided type name in IGC.

Parameters:

typeName - the IGC type name for which to retrieve details

view - whether to include the viewable properties

create - whether to include the properties that can be included during creation

edit - whether to include editable properties

Returns:

TypeDetails

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the types payload

getAssetById

public Reference getAssetById(String rid)
                       throws IGCConnectivityException,
                              IGCParsingException

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

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

See Also:

getAssetRefById(String)

getAssetById

public Reference getAssetById(String rid,
                              ObjectCache cache)
                       throws IGCConnectivityException,
                              IGCParsingException

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

cache - a cache of previously-retrieved assets

Returns:

Reference - the IGC object representing the asset

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

See Also:

getAssetRefById(String)

getEncodedPathVariable

public static String getEncodedPathVariable(String pathVariable)

Calculate a path-encoded URL for the provided endpoint.

Parameters:

pathVariable - the value within the path to encode

Returns:

String - the encoded endpoint

getAssetRefById

public Reference getAssetRefById(String rid)
                          throws IGCConnectivityException,
                                 IGCParsingException

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

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

getAssetWithSubsetOfProperties

public <T extends Reference> T getAssetWithSubsetOfProperties(String rid,
                                                              String assetType,
                                                              List<String> properties)
                                                       throws IGCConnectivityException,
                                                              IGCParsingException

This will generally be the most performant method by which to retrieve asset information, when only some subset of properties is required

Type Parameters:

T - the type of Reference to return

Parameters:

rid - the repository ID (RID) of the asset to retrieve

assetType - the IGC asset type of the asset to retrieve

properties - a list of the properties to retrieve

Returns:

Reference - the object including only the subset of properties specified

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

getAssetWithSubsetOfProperties

public <T extends Reference> T getAssetWithSubsetOfProperties(String rid,
                                                              String assetType,
                                                              String[] properties)
                                                       throws IGCConnectivityException,
                                                              IGCParsingException

This will generally be the most performant method by which to retrieve asset information, when only some subset of properties is required

Type Parameters:

T - the type of Reference to return

Parameters:

rid - the repository ID (RID) of the asset to retrieve

assetType - the IGC asset type of the asset to retrieve

properties - a list of the properties to retrieve

Returns:

Reference - the object including only the subset of properties specified

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

getAssetWithSubsetOfProperties

public <T extends Reference> T getAssetWithSubsetOfProperties(String rid,
                                                              String assetType,
                                                              String[] properties,
                                                              int pageSize)
                                                       throws IGCConnectivityException,
                                                              IGCParsingException

This will generally be the most performant method by which to retrieve asset information, when only some subset of properties is required

Type Parameters:

T - the type of Reference to return

Parameters:

rid - the repository ID (RID) of the asset to retrieve

assetType - the IGC asset type of the asset to retrieve

properties - a list of the properties to retrieve

pageSize - the maximum number of each of the asset's relationships to return on this request

Returns:

Reference - the object including only the subset of properties specified

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

getAssetWithSubsetOfProperties

public <T extends Reference> T getAssetWithSubsetOfProperties(String rid,
                                                              String assetType,
                                                              List<String> properties,
                                                              int pageSize)
                                                       throws IGCConnectivityException,
                                                              IGCParsingException

This will generally be the most performant method by which to retrieve asset information, when only some subset of properties is required

Type Parameters:

T - the type of Reference to return

Parameters:

rid - the repository ID (RID) of the asset to retrieve

assetType - the IGC asset type of the asset to retrieve

properties - a list of the properties to retrieve

pageSize - the maximum number of each of the asset's relationships to return on this request

Returns:

Reference - the object including only the subset of properties specified

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

search

public <T extends Reference> ItemList<T> search(IGCSearch igcSearch)
                                         throws IGCConnectivityException,
                                                IGCParsingException

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

Type Parameters:

T - the type of items that should be in the ItemList

Parameters:

igcSearch - search conditions and criteria to use

Returns:

ItemList<T> - the first page of results from the search

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

update

public boolean update(IGCUpdate igcUpdate)
               throws IGCConnectivityException

Apply the update described by the provided update object.

Parameters:

igcUpdate - update criteria to use

Returns:

boolean - indicating success (true) or not (false) of the operation

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

create

public String create(IGCCreate igcCreate)
              throws IGCConnectivityException

Create the object described by the provided create object.

Parameters:

igcCreate - creation criteria to use

Returns:

String - the created asset's RID (or null if nothing was created)

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

delete

public boolean delete(String rid)
               throws IGCConnectivityException

Delete the object specified by the provided RID.

Parameters:

rid - the RID of the asset to delete

Returns:

boolean

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

detectLineage

public boolean detectLineage(String jobRid)
                      throws IGCConnectivityException

Run lineage detection against the provided job (by RID).

Parameters:

jobRid - the RID of the job for which to detect lineage

Returns:

boolean giving indication of success (true) or not (false)

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

upsertOpenIgcBundle

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

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)

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

createOpenIgcBundleFile

public File createOpenIgcBundleFile(File directory)
                             throws IGCIOException

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

Throws:

IGCIOException - if there is any issue loading the provided directory or creating a bundle from it

getOpenIgcBundles

public List<String> getOpenIgcBundles()
                               throws IGCConnectivityException,
                                      IGCParsingException

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

Returns:

List<String>

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

upsertOpenIgcAsset

public String upsertOpenIgcAsset(String assetXML)
                          throws IGCConnectivityException

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:

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

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

deleteOpenIgcAsset

public boolean deleteOpenIgcAsset(String assetXML)
                           throws IGCConnectivityException

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

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

getNextPage

public <T extends Reference> ItemList<T> getNextPage(String propertyName,
                                                     ItemList<T> list)
                                              throws IGCConnectivityException,
                                                     IGCParsingException

Retrieve the next page of results for the provided parameters.

Type Parameters:

T - the type of items to expect in the ItemList

Parameters:

propertyName - the name of the property for which the list provides items (or null if the result of a search)

list - the list of items from which to retrieve the next page

Returns:

ItemList<T> - the next page of results

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

getAllPages

public <T extends Reference> List<T> getAllPages(String propertyName,
                                                 ItemList<T> list)
                                          throws IGCConnectivityException,
                                                 IGCParsingException

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

Type Parameters:

T - the type of items to expect in the ItemList

Parameters:

propertyName - the name of the property for which the list provides items (or null if the result of a search)

list - the ItemList for which to retrieve all pages

Returns:

List<T> - a List containing all items from all pages of results

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

disconnect

public void disconnect()
                throws IGCConnectivityException

Disconnect from IGC REST API and invalidate the session.

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

cacheTypeDetails

public void cacheTypeDetails(String typeName)
                      throws IGCConnectivityException,
                             IGCParsingException,
                             IGCIOException

Cache detailed information about the IGC object type.

Parameters:

typeName - name of the IGC object type to cache

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

IGCIOException - if there is any issue accessing the POJO that defines the type and its properties

getDisplayNameForType

public String getDisplayNameForType(String typeName)
                             throws IGCConnectivityException,
                                    IGCParsingException,
                                    IGCIOException

Retrieve the display name of this IGC object type.

Parameters:

typeName - the name of the IGC object type

Returns:

String

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

IGCIOException - if there is any issue accessing the POJO defining the type and its properties

isCreatable

public boolean isCreatable(String typeName)
                    throws IGCConnectivityException,
                           IGCParsingException,
                           IGCIOException

Indicates whether the IGC object type can be created (true) or not (false).

Parameters:

typeName - the name of the IGC object type

Returns:

boolean

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

IGCIOException - if there is any issue accessing the POJO defining the type and its properties

hasModificationDetails

public boolean hasModificationDetails(String typeName)
                               throws IGCConnectivityException,
                                      IGCParsingException,
                                      IGCIOException

Indicates whether assets of this type include modification details (true) or not (false).

Parameters:

typeName - the name of the IGC asset type for which to check whether it tracks modification details

Returns:

boolean

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

IGCIOException - if there is any issue accessing the POJO defining the type and its properties

getAllPropertiesForType

public List<String> getAllPropertiesForType(String typeName)
                                     throws IGCConnectivityException,
                                            IGCParsingException,
                                            IGCIOException

Retrieve the names of all properties for the provided IGC object type, or null if the type is unknown.

Parameters:

typeName - the name of the IGC object type

Returns:

List<String>

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

IGCIOException - if there is any issue accessing the POJO defining the type and its properties

getNonRelationshipPropertiesForType

public List<String> getNonRelationshipPropertiesForType(String typeName)
                                                 throws IGCConnectivityException,
                                                        IGCParsingException,
                                                        IGCIOException

Retrieve the names of all non-relationship properties for the provided IGC object type, or null if the type is unknown.

Parameters:

typeName - the name of the IGC object type

Returns:

List<String>

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

IGCIOException - if there is any issue accessing the POJO defining the type and its properties

getAllStringPropertiesForType

public List<String> getAllStringPropertiesForType(String typeName)
                                           throws IGCConnectivityException,
                                                  IGCParsingException,
                                                  IGCIOException

Retrieve the names of all string properties for the provided IGC object type, or null if the type is unknown.

Parameters:

typeName - the name of the IGC object type

Returns:

List<String>

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

IGCIOException - if there is any issue accessing the POJO defining the type and its properties

getPagedRelationshipPropertiesForType

public List<String> getPagedRelationshipPropertiesForType(String typeName)
                                                   throws IGCConnectivityException,
                                                          IGCParsingException,
                                                          IGCIOException

Retrieve the names of all paged relationship properties for the provided IGC object type, or null if the type is unknown.

Parameters:

typeName - the name of the IGC object type

Returns:

List<String>

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

IGCIOException - if there is any issue accessing the POJO defining the type and its properties

registerPOJO

public void registerPOJO(Class<?> clazz)
                  throws IGCIOException

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

In general, you'll want your POJO to extend at least the Reference object, and more likely the InformationAsset (for your own OpenIGC object), or if you are adding custom attributes to one of the native asset types, consider directly changing that bean.

To allow this dynamic registration to work, also ensure you have a @JsonTypeName("...") annotation 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 base POJOs for examples.

Parameters:

clazz - the Java Class (POJO) object to register

Throws:

IGCIOException - if there is any issue introspecting the provided POJO class

getPOJOForType

public Class<?> getPOJOForType(String assetType)
                        throws IGCIOException

Returns the POJO that is registered to serde the provided IGC asset type, preferring any that have been registered or defaulting to the out-of-the-box ones if there are no overrides.

Parameters:

assetType - name of the IGC asset

Returns:

Class

Throws:

IGCIOException - if there is any issue introspecting the provided POJO 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

getPropertyByName

public Object getPropertyByName(Reference object,
                                String property)
                         throws IGCIOException

Retrieve a property of an IGC object based on the property's name.

Parameters:

object - the IGC object from which to retrieve the property's value

property - the name of the property for which to retrieve the value

Returns:

Object

Throws:

IGCIOException - if there is any issue introspecting the class that defines the type and its properties

getModificationDetails

public <T extends Reference> T getModificationDetails(T object,
                                                      ObjectCache cache)
                                               throws IGCConnectivityException,
                                                      IGCParsingException,
                                                      IGCIOException

Ensures that the modification details of the asset are populated (takes no action if already populated or the asset does not support them).

Type Parameters:

T - the type of IGC object (minimally a Reference)

Parameters:

object - the IGC object for which to populate modification details

cache - a cache of information that may already have been retrieved about the provided object

Returns:

T - the IGC object with its _context and modification details populated

Throws:

IGCConnectivityException - if there is any connectivity issue during the request

IGCParsingException - if there is any issue parsing the response from IGC

IGCIOException - if there is any issue accessing the POJO defining the type and its properties