org.odpi.openmetadata.accessservices.assetconsumer.client

Class AssetConsumer

java.lang.Object

org.odpi.openmetadata.accessservices.assetconsumer.client.AssetConsumer

All Implemented Interfaces:

AssetConsumerAssetInterface, AssetConsumerConnectorFactoryInterface, AssetConsumerFeedbackInterface, AssetConsumerGlossaryInterface, AssetConsumerLoggingInterface, AssetConsumerTaggingInterface

public class AssetConsumer
extends Object
implements AssetConsumerAssetInterface, AssetConsumerConnectorFactoryInterface, AssetConsumerFeedbackInterface, AssetConsumerGlossaryInterface, AssetConsumerLoggingInterface, AssetConsumerTaggingInterface

The Asset Consumer Open Metadata Access Service (OMAS) is used by applications and tools as a factory for Open Connector Framework (OCF) connectors. The configuration for the connectors is managed as open metadata in a Connection definition. The caller to the Asset Consumer OMAS passes either the name, GUID or URL for the connection to the appropriate method to retrieve a connector. The Asset Consumer OMAS retrieves the connection from the metadata repository and creates an appropriate connector as described the connection and returns it to the caller. The Asset Consumer OMAS supports access to the asset properties either through the connector, or by a direct call to Asset Consumer API. It is also possible to look up the definitions of terms associated with the assets. It supports the ability to add and remove feedback for an asset. This feedback may be in the form of reviews, likes and comments. Asset Consumer OMAS also supports the maintenance of informal tags and their attachments to assets. Finally, Asset Consumer OMAS supports the ability to add audit log records to the local server's audit log about an asset.

Constructor Summary

Constructors

Constructor and Description
AssetConsumer(String serverName, String newServerURL) Create a new client with no authentication embedded in the HTTP request.
AssetConsumer(String serverName, String omasServerURL, String userId, String password) Create a new client that passes userId and password in each HTTP request.

Method Summary

Modifier and Type	Method and Description
String	addCommentReply(String userId, String commentGUID, CommentType commentType, String commentText) Adds a comment to another comment.
String	addCommentToAsset(String userId, String assetGUID, CommentType commentType, String commentText) Adds a comment to the asset.
String	addLikeToAsset(String userId, String assetGUID) Adds a "Like" to the asset.
void	addLogMessageToAsset(String userId, String assetGUID, String connectorInstanceId, String connectionName, String connectorType, String contextId, String message) Creates an Audit log record about the asset.
String	addReviewToAsset(String userId, String assetGUID, StarRating starRating, String review) Adds a star rating and optional review text to the asset.
void	addTagToAsset(String userId, String assetGUID, String tagGUID) Adds a tag (either private of public) to an asset.
String	createPrivateTag(String userId, String tagName, String tagDescription) Creates a new private informal tag and returns the unique identifier for it.
String	createPublicTag(String userId, String tagName, String tagDescription) Creates a new public informal tag and returns the unique identifier for it.
void	deleteTag(String userId, String tagGUID) Removes a tag from the repository.
String	getAssetForConnection(String userId, String connectionGUID) Returns the unique identifier for the asset connected to the requested connection.
String	getAssetForConnectionName(String userId, String connectionName) Returns the asset corresponding to the supplied connection name.
AssetUniverse	getAssetProperties(String userId, String assetGUID) Returns a comprehensive collection of properties about the requested asset.
Connector	getConnectorByConnection(String userId, Connection connection) Returns the connector corresponding to the supplied connection.
Connector	getConnectorByGUID(String userId, String connectionGUID) Returns the connector corresponding to the supplied connection GUID.
Connector	getConnectorByName(String userId, String connectionName) Returns the connector corresponding to the supplied connection name.
GlossaryTerm	getMeaning(String userId, String guid) Return the full definition (meaning) of a term using the unique identifier of the glossary term that contains the definition.
List<GlossaryTerm>	getMeaningByName(String userId, String term, int startFrom, int pageSize) Return the full definition (meaning) of the terms matching the supplied name.
Tag	getTag(String userId, String guid) Return the tag for the supplied unique identifier (guid).
List<Tag>	getTagsByName(String userId, String tag, int startFrom, int pageSize) Return the list of tags matching the supplied name.
void	removeCommentFromAsset(String userId, String commentGUID) Removes a comment added to the asset by this user.
void	removeLikeFromAsset(String userId, String likeGUID) Removes a "Like" added to the asset by this user.
void	removeReviewFromAsset(String userId, String reviewGUID) Removes of a review that was added to the asset by this user.
void	removeTagFromAsset(String userId, String assetGUID, String tagGUID) Removes a tag from the asset that was added by this user.
void	updateComment(String userId, String commentGUID, CommentType commentType, String commentText) Update an existing comment.
void	updateReviewOnAsset(String userId, String reviewGUID, StarRating starRating, String review) Updates the rating and optional review text attached to the asset by this user.
void	updateTagDescription(String userId, String tagGUID, String tagDescription) Updates the description of an existing tag (either private of public).

Methods inherited from class java.lang.Object

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

Constructor Detail

AssetConsumer

public AssetConsumer(String serverName,
                     String newServerURL)

Create a new client with no authentication embedded in the HTTP request.

Parameters:

serverName - name of the server to connect to

newServerURL - the network address of the server running the OMAS REST servers

AssetConsumer

public AssetConsumer(String serverName,
                     String omasServerURL,
                     String userId,
                     String password)

Create a new client that passes userId and password in each HTTP request. This is the userId/password of the calling server. The end user's userId is sent on each request.

Parameters:

serverName - name of the server to connect to

omasServerURL - the network address of the server running the OMAS REST servers

userId - caller's userId embedded in all HTTP requests

password - caller's userId embedded in all HTTP requests

Method Detail

getAssetForConnection

public String getAssetForConnection(String userId,
                                    String connectionGUID)
                             throws InvalidParameterException,
                                    NoConnectedAssetException,
                                    PropertyServerException,
                                    UserNotAuthorizedException

Returns the unique identifier for the asset connected to the requested connection.

Specified by:

getAssetForConnection in interface AssetConsumerAssetInterface

Parameters:

userId - the userId of the requesting user.

connectionGUID - unique identifier for the connection.

Returns:

unique identifier of asset.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem retrieving information from the property server.

NoConnectedAssetException - there is no asset associated with this connection.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

getAssetForConnectionName

public String getAssetForConnectionName(String userId,
                                        String connectionName)
                                 throws InvalidParameterException,
                                        AmbiguousConnectionNameException,
                                        NoConnectedAssetException,
                                        PropertyServerException,
                                        UserNotAuthorizedException

Returns the asset corresponding to the supplied connection name.

Specified by:

getAssetForConnectionName in interface AssetConsumerAssetInterface

Parameters:

userId - userId of user making request.

connectionName - this may be the qualifiedName or displayName of the connection.

Returns:

unique identifier of asset.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

AmbiguousConnectionNameException - there is more than one connection defined for this name.

NoConnectedAssetException - there is no asset associated with this connection.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

getAssetProperties

public AssetUniverse getAssetProperties(String userId,
                                        String assetGUID)
                                 throws InvalidParameterException,
                                        PropertyServerException,
                                        UserNotAuthorizedException

Returns a comprehensive collection of properties about the requested asset.

Specified by:

getAssetProperties in interface AssetConsumerAssetInterface

Parameters:

userId - userId of user making request.

assetGUID - unique identifier for asset.

Returns:

a comprehensive collection of properties about the asset.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem retrieving the asset properties from the property servers).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

getConnectorByName

public Connector getConnectorByName(String userId,
                                    String connectionName)
                             throws InvalidParameterException,
                                    AmbiguousConnectionNameException,
                                    ConnectionCheckedException,
                                    ConnectorCheckedException,
                                    PropertyServerException,
                                    UserNotAuthorizedException

Returns the connector corresponding to the supplied connection name.

Specified by:

getConnectorByName in interface AssetConsumerConnectorFactoryInterface

Parameters:

userId - userId of user making request.

connectionName - this may be the qualifiedName or displayName of the connection.

Returns:

Connector connector instance.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

AmbiguousConnectionNameException - there is more than one connection defined for this name.

ConnectionCheckedException - there are errors in the configuration of the connection which is preventing the creation of a connector.

ConnectorCheckedException - there are errors in the initialization of the connector.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

getConnectorByGUID

public Connector getConnectorByGUID(String userId,
                                    String connectionGUID)
                             throws InvalidParameterException,
                                    ConnectionCheckedException,
                                    ConnectorCheckedException,
                                    PropertyServerException,
                                    UserNotAuthorizedException

Returns the connector corresponding to the supplied connection GUID.

Specified by:

getConnectorByGUID in interface AssetConsumerConnectorFactoryInterface

Parameters:

userId - userId of user making request.

connectionGUID - the unique id for the connection within the metadata repository.

Returns:

Connector connector instance.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

ConnectionCheckedException - there are errors in the configuration of the connection which is preventing the creation of a connector.

ConnectorCheckedException - there are errors in the initialization of the connector.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

getConnectorByConnection

public Connector getConnectorByConnection(String userId,
                                          Connection connection)
                                   throws InvalidParameterException,
                                          ConnectionCheckedException,
                                          ConnectorCheckedException,
                                          PropertyServerException

Returns the connector corresponding to the supplied connection.

Specified by:

getConnectorByConnection in interface AssetConsumerConnectorFactoryInterface

Parameters:

userId - userId of user making request.

connection - the connection object that contains the properties needed to create the connection.

Returns:

Connector connector instance

Throws:

InvalidParameterException - one of the parameters is null or invalid.

ConnectionCheckedException - there are errors in the configuration of the connection which is preventing the creation of a connector.

ConnectorCheckedException - there are errors in the initialization of the connector.

PropertyServerException - there is a problem retrieving information from the property server(s).

addReviewToAsset

public String addReviewToAsset(String userId,
                               String assetGUID,
                               StarRating starRating,
                               String review)
                        throws InvalidParameterException,
                               PropertyServerException,
                               UserNotAuthorizedException

Adds a star rating and optional review text to the asset.

Specified by:

addReviewToAsset in interface AssetConsumerFeedbackInterface

Parameters:

userId - userId of user making request.

assetGUID - unique identifier for the asset.

starRating - StarRating enumeration for not recommended, one to five stars.

review - user review of asset. This can be null.

Returns:

guid of new review object.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem adding the asset properties to the property server.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

updateReviewOnAsset

public void updateReviewOnAsset(String userId,
                                String reviewGUID,
                                StarRating starRating,
                                String review)
                         throws InvalidParameterException,
                                PropertyServerException,
                                UserNotAuthorizedException

Updates the rating and optional review text attached to the asset by this user.

Specified by:

updateReviewOnAsset in interface AssetConsumerFeedbackInterface

Parameters:

userId - userId of user making request.

reviewGUID - unique identifier for the review.

starRating - StarRating enumeration for none, one to five stars.

review - user review of asset. This can be null.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem adding the asset properties to the property server.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

removeReviewFromAsset

public void removeReviewFromAsset(String userId,
                                  String reviewGUID)
                           throws InvalidParameterException,
                                  PropertyServerException,
                                  UserNotAuthorizedException

Removes of a review that was added to the asset by this user.

Specified by:

removeReviewFromAsset in interface AssetConsumerFeedbackInterface

Parameters:

userId - userId of user making request.

reviewGUID - unique identifier for the rating object.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem updating the asset properties in the property server.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

addLikeToAsset

public String addLikeToAsset(String userId,
                             String assetGUID)
                      throws InvalidParameterException,
                             PropertyServerException,
                             UserNotAuthorizedException

Adds a "Like" to the asset.

Specified by:

addLikeToAsset in interface AssetConsumerFeedbackInterface

Parameters:

userId - userId of user making request.

assetGUID - unique identifier for the asset

Returns:

guid of new like object.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem adding the asset properties to the property server.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

removeLikeFromAsset

public void removeLikeFromAsset(String userId,
                                String likeGUID)
                         throws InvalidParameterException,
                                PropertyServerException,
                                UserNotAuthorizedException

Removes a "Like" added to the asset by this user.

Specified by:

removeLikeFromAsset in interface AssetConsumerFeedbackInterface

Parameters:

userId - userId of user making request.

likeGUID - unique identifier for the like object.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem updating the asset properties in the property server.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

addCommentToAsset

public String addCommentToAsset(String userId,
                                String assetGUID,
                                CommentType commentType,
                                String commentText)
                         throws InvalidParameterException,
                                PropertyServerException,
                                UserNotAuthorizedException

Adds a comment to the asset.

Specified by:

addCommentToAsset in interface AssetConsumerFeedbackInterface

Parameters:

userId - userId of user making request.

assetGUID - unique identifier for the asset.

commentType - type of comment enum.

commentText - the text of the comment.

Returns:

guid of new comment.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem adding the asset properties to the property server.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

addCommentReply

public String addCommentReply(String userId,
                              String commentGUID,
                              CommentType commentType,
                              String commentText)
                       throws InvalidParameterException,
                              PropertyServerException,
                              UserNotAuthorizedException

Adds a comment to another comment.

Specified by:

addCommentReply in interface AssetConsumerFeedbackInterface

Parameters:

userId - userId of user making request.

commentGUID - unique identifier for an existing comment. Used to add a reply to a comment.

commentType - type of comment enum.

commentText - the text of the comment.

Returns:

guid of new comment.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem adding the asset properties to the property server.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

updateComment

public void updateComment(String userId,
                          String commentGUID,
                          CommentType commentType,
                          String commentText)
                   throws InvalidParameterException,
                          PropertyServerException,
                          UserNotAuthorizedException

Update an existing comment.

Specified by:

updateComment in interface AssetConsumerFeedbackInterface

Parameters:

userId - userId of user making request.

commentGUID - unique identifier for the comment to change.

commentType - type of comment enum.

commentText - the text of the comment.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem adding the asset properties to the property server.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

removeCommentFromAsset

public void removeCommentFromAsset(String userId,
                                   String commentGUID)
                            throws InvalidParameterException,
                                   PropertyServerException,
                                   UserNotAuthorizedException

Removes a comment added to the asset by this user.

Specified by:

removeCommentFromAsset in interface AssetConsumerFeedbackInterface

Parameters:

userId - userId of user making request.

commentGUID - unique identifier for the comment object.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem updating the asset properties in the property server.

UserNotAuthorizedException - the user does not have permission to perform this request.

getMeaning

public GlossaryTerm getMeaning(String userId,
                               String guid)
                        throws InvalidParameterException,
                               PropertyServerException,
                               UserNotAuthorizedException

Return the full definition (meaning) of a term using the unique identifier of the glossary term that contains the definition.

Specified by:

getMeaning in interface AssetConsumerGlossaryInterface

Parameters:

userId - userId of the user making the request.

guid - unique identifier of the glossary term.

Returns:

meaning response object

Throws:

InvalidParameterException - the userId is null or invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

getMeaningByName

public List<GlossaryTerm> getMeaningByName(String userId,
                                           String term,
                                           int startFrom,
                                           int pageSize)
                                    throws InvalidParameterException,
                                           PropertyServerException,
                                           UserNotAuthorizedException

Return the full definition (meaning) of the terms matching the supplied name.

Specified by:

getMeaningByName in interface AssetConsumerGlossaryInterface

Parameters:

userId - the name of the calling user.

term - name of term. This may include wild card characters.

startFrom - index of the list ot start from (0 for start)

pageSize - maximum number of elements to return.

Returns:

meaning list response or

Throws:

InvalidParameterException - the userId is null or invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

addLogMessageToAsset

public void addLogMessageToAsset(String userId,
                                 String assetGUID,
                                 String connectorInstanceId,
                                 String connectionName,
                                 String connectorType,
                                 String contextId,
                                 String message)
                          throws InvalidParameterException,
                                 PropertyServerException,
                                 UserNotAuthorizedException

Creates an Audit log record about the asset. This log record is stored in the local server's Audit Log.

Specified by:

addLogMessageToAsset in interface AssetConsumerLoggingInterface

Parameters:

userId - userId of user making request.

assetGUID - unique id for the asset.

connectorInstanceId - (optional) id of connector in use (if any).

connectionName - (optional) name of the connection (extracted from the connector).

connectorType - (optional) type of connector in use (if any).

contextId - (optional) function name, or processId of the activity that the caller is performing.

message - log record content.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - There is a problem adding the asset properties to the property server.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

createPublicTag

public String createPublicTag(String userId,
                              String tagName,
                              String tagDescription)
                       throws InvalidParameterException,
                              PropertyServerException,
                              UserNotAuthorizedException

Creates a new public informal tag and returns the unique identifier for it.

Specified by:

createPublicTag in interface AssetConsumerTaggingInterface

Parameters:

userId - userId of user making request.

tagName - name of the tag.

tagDescription - (optional) description of the tag. Setting a description, particularly in a public tag makes the tag more valuable to other users and can act as an embryonic glossary term.

Returns:

GUID for new tag.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem adding the asset properties to the property server.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

createPrivateTag

public String createPrivateTag(String userId,
                               String tagName,
                               String tagDescription)
                        throws InvalidParameterException,
                               PropertyServerException,
                               UserNotAuthorizedException

Creates a new private informal tag and returns the unique identifier for it.

Specified by:

createPrivateTag in interface AssetConsumerTaggingInterface

Parameters:

userId - userId of user making request.

tagName - name of the tag.

tagDescription - (optional) description of the tag. Setting a description, particularly in a public tag makes the tag more valuable to other users and can act as an embryonic glossary term.

Returns:

GUID for new tag.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem adding the asset properties to the property server.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

updateTagDescription

public void updateTagDescription(String userId,
                                 String tagGUID,
                                 String tagDescription)
                          throws InvalidParameterException,
                                 PropertyServerException,
                                 UserNotAuthorizedException

Updates the description of an existing tag (either private of public).

Specified by:

updateTagDescription in interface AssetConsumerTaggingInterface

Parameters:

userId - userId of user making request.

tagGUID - unique identifier for the tag.

tagDescription - description of the tag. Setting a description, particularly in a public tag makes the tag more valuable to other users and can act as an embryonic glossary term.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem adding the asset properties to the property server.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

deleteTag

public void deleteTag(String userId,
                      String tagGUID)
               throws InvalidParameterException,
                      PropertyServerException,
                      UserNotAuthorizedException

Removes a tag from the repository. All of the relationships to assets are lost.

Specified by:

deleteTag in interface AssetConsumerTaggingInterface

Parameters:

userId - userId of user making request.

tagGUID - unique id for the tag.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem updating the asset properties in the property server.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

getTag

public Tag getTag(String userId,
                  String guid)
           throws InvalidParameterException,
                  PropertyServerException,
                  UserNotAuthorizedException

Return the tag for the supplied unique identifier (guid).

Specified by:

getTag in interface AssetConsumerTaggingInterface

Parameters:

userId - userId of the user making the request.

guid - unique identifier of the tag.

Returns:

tag

Throws:

InvalidParameterException - the userId is null or invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

getTagsByName

public List<Tag> getTagsByName(String userId,
                               String tag,
                               int startFrom,
                               int pageSize)
                        throws InvalidParameterException,
                               PropertyServerException,
                               UserNotAuthorizedException

Return the list of tags matching the supplied name.

Specified by:

getTagsByName in interface AssetConsumerTaggingInterface

Parameters:

userId - the name of the calling user.

tag - name of tag. This may include wild card characters.

startFrom - index of the list ot start from (0 for start)

pageSize - maximum number of elements to return.

Returns:

tag list

Throws:

InvalidParameterException - the userId is null or invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

addTagToAsset

public void addTagToAsset(String userId,
                          String assetGUID,
                          String tagGUID)
                   throws InvalidParameterException,
                          PropertyServerException,
                          UserNotAuthorizedException

Adds a tag (either private of public) to an asset.

Specified by:

addTagToAsset in interface AssetConsumerTaggingInterface

Parameters:

userId - userId of user making request.

assetGUID - unique id for the asset.

tagGUID - unique id of the tag.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem adding the asset properties to the property server.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

removeTagFromAsset

public void removeTagFromAsset(String userId,
                               String assetGUID,
                               String tagGUID)
                        throws InvalidParameterException,
                               PropertyServerException,
                               UserNotAuthorizedException

Removes a tag from the asset that was added by this user.

Specified by:

removeTagFromAsset in interface AssetConsumerTaggingInterface

Parameters:

userId - userId of user making request.

assetGUID - unique id for the asset.

tagGUID - unique id for the tag.

Throws:

InvalidParameterException - one of the parameters is null or invalid.

PropertyServerException - there is a problem updating the asset properties in the property server.

UserNotAuthorizedException - the requesting user is not authorized to issue this request.