http://git-wip-us.apache.org/repos/asf/atlas/blob/f57fd7f0/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/client/AssetConsumer.java ---------------------------------------------------------------------- diff --git a/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/client/AssetConsumer.java b/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/client/AssetConsumer.java new file mode 100644 index 0000000..80a98f5 --- /dev/null +++ b/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/client/AssetConsumer.java @@ -0,0 +1,1260 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * <p/> + * http://www.apache.org/licenses/LICENSE-2.0 + * <p/> + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.atlas.omas.assetconsumer.client; + +import org.apache.atlas.ocf.Connector; +import org.apache.atlas.ocf.ConnectorBroker; +import org.apache.atlas.ocf.ffdc.ConnectionCheckedException; +import org.apache.atlas.ocf.ffdc.ConnectorCheckedException; +import org.apache.atlas.ocf.properties.CommentType; +import org.apache.atlas.omas.assetconsumer.server.properties.GUIDResponse; +import org.apache.atlas.omas.connectedasset.properties.AssetUniverse; +import org.apache.atlas.ocf.properties.beans.Connection; +import org.apache.atlas.ocf.properties.StarRating; +import org.apache.atlas.omas.assetconsumer.AssetConsumerInterface; +import org.apache.atlas.omas.assetconsumer.ffdc.*; +import org.apache.atlas.omas.assetconsumer.ffdc.exceptions.*; +import org.apache.atlas.omas.assetconsumer.server.properties.AssetConsumerOMASAPIResponse; +import org.apache.atlas.omas.assetconsumer.server.properties.ConnectionResponse; +import org.apache.atlas.omas.assetconsumer.server.properties.VoidResponse; +import org.apache.atlas.omas.connectedasset.client.ConnectedAsset; +import org.apache.atlas.omas.connectedasset.client.ConnectedAssetProperties; +import org.springframework.web.client.RestTemplate; + +/** + * The AssetConsumer Open Metadata Access Service (OMAS) provides an interface to support an application or tool + * that is using Open Connector Framework (OCF) connectors to work with assets such as data stores, data sets and + * APIs. The interface is divided into three parts: + * <ul> + * <li>Client-side only services that work with the OCF to create requested connectors.</li> + * <li>OMAS Server calls to retrieve connection information on behalf of the OCF.</li> + * <li>OMAS Server calls to add feedback to the asset.</li> + * </ul> + */ +public class AssetConsumer implements AssetConsumerInterface +{ + private String omasServerURL; /* Initialized in constructor */ + + /** + * Create a new AssetConsumer client. + * + * @param newServerURL - the network address of the server running the OMAS REST servers + */ + public AssetConsumer(String newServerURL) + { + omasServerURL = newServerURL; + } + + + /** + * Use the Open Connector Framework (OCF) to create a connector using the supplied connection. + * + * @param requestedConnection - connection describing the required connector. + * @param methodName - name of the calling method. + * @return a new connector. + */ + private Connector getConnectorForConnection(String userId, + Connection requestedConnection, + String methodName) throws ConnectionCheckedException, + ConnectorCheckedException + { + ConnectorBroker connectorBroker = new ConnectorBroker(); + + /* + * Pass the connection to the ConnectorBroker to create the connector instance. + * Again, exceptions from this process are returned directly to the caller. + */ + Connector newConnector = connectorBroker.getConnector(requestedConnection); + + /* + * If no exception is thrown by getConnector, we should have a connector instance. + */ + if (newConnector == null) + { + /* + * This is probably some sort of logic error since the connector should have been returned. + * Whatever the cause, the process can not proceed without a connector. + */ + AssetConsumerErrorCode errorCode = AssetConsumerErrorCode.NULL_CONNECTOR_RETURNED; + String errorMessage = errorCode.getErrorMessageId() + errorCode.getFormattedErrorMessage(); + + throw new AssetConsumerRuntimeException(errorCode.getHTTPErrorCode(), + this.getClass().getName(), + methodName, + errorMessage, + errorCode.getSystemAction(), + errorCode.getUserAction()); + } + + /* + * If the connector is successfully created, set up the Connected Asset Properties for the connector. + * The properties should be retrieved from the open metadata repositories, so use an OMAS implementation + * of the ConnectedAssetProperties object. + */ + ConnectedAssetProperties connectedAssetProperties = new ConnectedAssetProperties(userId, + omasServerURL, + newConnector.getConnectorInstanceId(), + newConnector.getConnection()); + + /* + * Pass the new connected asset properties to the connector + */ + newConnector.initializeConnectedAssetProperties(connectedAssetProperties); + + /* + * At this stage, the asset properties are not retrieved from the server. This does not happen until the caller + * issues a connector.getConnectedAssetProperties. This causes the connectedAssetProperties.refresh() call + * to be made, which contacts the OMAS server and retrieves the asset properties. + * + * Delaying the population of the connected asset properties ensures the latest values are returned to the + * caller (consider a long running connection). Alternatively, these properties may not ever be used by the + * caller so retrieving the properties at this point would be unnecessary. + */ + + return newConnector; + } + + + + /** + * Returns the connection object corresponding to the supplied connection name. + * + * @param userId - String - userId of user making request. + * @param name - this may be the qualifiedName or displayName of the connection. + * + * @return Connection retrieved from property server + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws UnrecognizedConnectionNameException - there is no connection defined for this name. + * @throws AmbiguousConnectionNameException - there is more than one connection defined for this name. + * @throws PropertyServerException - there is a problem retrieving information from the property (metadata) server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + private Connection getConnectionByName(String userId, + String name) throws InvalidParameterException, + UnrecognizedConnectionNameException, + AmbiguousConnectionNameException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "getConnectionByName"; + final String urlTemplate = "/{0}/connection/by-name/{1}"; + + validateOMASServerURL(methodName); + + ConnectionResponse restResult = callConnectionGetRESTCall(methodName, + omasServerURL + urlTemplate, + userId, + name); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUnrecognizedConnectionNameException(methodName, restResult); + this.detectAndThrowAmbiguousConnectionNameException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowPropertyServerException(methodName, restResult); + + return restResult.getConnection(); + } + + + /** + * Returns the connector corresponding to the supplied connection name. + * + * @param userId - String - userId of user making request. + * @param connectionName - this may be the qualifiedName or displayName of the connection. + * + * @return Connector - connector instance. + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws UnrecognizedConnectionNameException - there is no connection defined for this name. + * @throws AmbiguousConnectionNameException - there is more than one connection defined for this name. + * @throws ConnectionCheckedException - there are errors in the configuration of the connection which is preventing + * the creation of a connector. + * @throws ConnectorCheckedException - there are errors in the initialization of the connector. + * @throws PropertyServerException - there is a problem retrieving information from the property (metadata) server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + public Connector getConnectorByName(String userId, + String connectionName) throws InvalidParameterException, + UnrecognizedConnectionNameException, + AmbiguousConnectionNameException, + ConnectionCheckedException, + ConnectorCheckedException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "getConnectorByName"; + final String nameParameter = "connectionName"; + + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + validateName(connectionName, nameParameter, methodName); + + return this.getConnectorForConnection(userId, + this.getConnectionByName(userId, connectionName), + methodName); + } + + + + /** + * Returns the connection object corresponding to the supplied connection GUID. + * + * @param userId - String - userId of user making request. + * @param guid - the unique id for the connection within the property server. + * + * @return Connection retrieved from the property server + * InvalidParameterException - one of the parameters is null or invalid. + * UnrecognizedConnectionGUIDException - the supplied GUID is not recognized by the property server. + * PropertyServerException - there is a problem retrieving information from the property (metadata) server. + * UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + private Connection getConnectionByGUID(String userId, + String guid) throws InvalidParameterException, + UnrecognizedConnectionGUIDException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "getConnectionByGUID"; + final String urlTemplate = "/{0}/connection/{1}"; + + validateOMASServerURL(methodName); + + ConnectionResponse restResult = callConnectionGetRESTCall(methodName, + omasServerURL + urlTemplate, + userId, + guid); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUnrecognizedConnectionGUIDException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowPropertyServerException(methodName, restResult); + + return restResult.getConnection(); + } + + + + /** + * Returns the connector corresponding to the supplied connection GUID. + * + * @param userId - String - userId of user making request. + * @param connectionGUID - the unique id for the connection within the property server. + * + * @return Connector - connector instance. + * + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws UnrecognizedConnectionGUIDException - the supplied GUID is not recognized by the property server. + * @throws ConnectionCheckedException - there are errors in the configuration of the connection which is preventing + * the creation of a connector. + * @throws ConnectorCheckedException - there are errors in the initialization of the connector. + * @throws PropertyServerException - there is a problem retrieving information from the property server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + public Connector getConnectorByGUID(String userId, + String connectionGUID) throws InvalidParameterException, + UnrecognizedConnectionGUIDException, + ConnectionCheckedException, + ConnectorCheckedException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "getConnectorByGUID"; + final String guidParameter = "connectionGUID"; + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + validateGUID(connectionGUID, guidParameter, methodName); + + return this.getConnectorForConnection(userId, + this.getConnectionByGUID(userId, connectionGUID), + methodName); + } + + + /** + * Returns the connector corresponding to the supplied connection. + * + * @param userId - String - userId of user making request. + * @param connection - the connection object that contains the properties needed to create the connection. + * + * @return Connector - connector instance + * + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws ConnectionCheckedException - there are errors in the configuration of the connection which is preventing + * the creation of a connector. + * @throws ConnectorCheckedException - there are errors in the initialization of the connector. + * @throws PropertyServerException - there is a problem retrieving information from the property (metadata) server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + public Connector getConnectorByConnection(String userId, + Connection connection) throws InvalidParameterException, + ConnectionCheckedException, + ConnectorCheckedException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "getConnectorByConnection"; + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + + return this.getConnectorForConnection(userId, connection, methodName); + } + + + /** + * Returns a comprehensive collection of properties about the requested asset. + * + * @param userId - String - userId of user making request. + * @param assetGUID - String - unique id for asset. + * + * @return AssetUniverse - a comprehensive collection of properties about the asset. + + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws PropertyServerException - There is a problem retrieving the asset properties from + * the property server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + public AssetUniverse getAssetProperties(String userId, + String assetGUID) throws InvalidParameterException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "getAssetProperties"; + final String guidParameter = "assetGUID"; + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + validateGUID(assetGUID, guidParameter, methodName); + + ConnectedAsset connectedAssetClient = new ConnectedAsset(omasServerURL); + + try + { + /* + * Make use of the ConnectedAsset OMAS Service which provides the metadata services for the + * Open Connector Framework (OCF). + */ + return connectedAssetClient.getAssetProperties(userId, assetGUID); + } + catch (Throwable error) + { + AssetConsumerErrorCode errorCode = AssetConsumerErrorCode.NO_CONNECTED_ASSET; + String errorMessage = errorCode.getErrorMessageId() + + errorCode.getFormattedErrorMessage(methodName); + + throw new PropertyServerException(errorCode.getHTTPErrorCode(), + this.getClass().getName(), + methodName, + errorMessage, + errorCode.getSystemAction(), + errorCode.getUserAction()); + } + } + + + /** + * Creates an Audit log record for the asset. This log record is stored in the Asset's Audit Log. + * + * @param userId - String - userId of user making request. + * @param assetGUID - String - unique id for the asset. + * @param connectorInstanceId - String - (optional) id of connector in use (if any). + * @param connectionName - String - (optional) name of the connection (extracted from the connector). + * @param connectorType - String - (optional) type of connector in use (if any). + * @param contextId - String - (optional) function name, or processId of the activity that the caller is performing. + * @param message - log record content. + * + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws PropertyServerException - There is a problem adding the asset properties to + * the property server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + public void addLogMessageToAsset(String userId, + String assetGUID, + String connectorInstanceId, + String connectionName, + String connectorType, + String contextId, + String message) throws InvalidParameterException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "addLogMessageToAsset"; + final String guidParameter = "assetGUID"; + + final String urlTemplate = "/{0}/asset/{1}/log-record?connectorInstanceId={2}&connectionName={3}&connectorType={4}&contextId={5}&message={6}"; + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + validateGUID(assetGUID, guidParameter, methodName); + + VoidResponse restResult = callVoidPostRESTCall(methodName, + omasServerURL + urlTemplate, + userId, + assetGUID, + connectorInstanceId, + connectionName, + connectorType, + contextId, + message); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowPropertyServerException(methodName, restResult); + } + + + + /** + * Adds a new public tag to the asset's properties. + * + * @param userId - String - userId of user making request. + * @param assetGUID - String - unique id for the asset. + * @param tagName - String - name of the tag. + * @param tagDescription - String - (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. + * @return String - GUID for new tag. + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws PropertyServerException - There is a problem adding the asset properties to + * the property server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + public String addTagToAsset(String userId, + String assetGUID, + String tagName, + String tagDescription) throws InvalidParameterException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "addTagToAsset"; + final String guidParameter = "assetGUID"; + final String nameParameter = "tagName"; + + final String urlTemplate = "/{0}/asset/{1}/tags?tagName={2}&tagDescription={3}"; + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + validateGUID(assetGUID, guidParameter, methodName); + validateName(tagName, nameParameter, methodName); + + GUIDResponse restResult = callGUIDPOSTRESTCall(methodName, + omasServerURL + urlTemplate, + userId, + assetGUID, + tagName, + tagDescription); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowPropertyServerException(methodName, restResult); + + return restResult.getGUID(); + } + + + /** + * Adds a new private tag to the asset's properties. + * + * @param userId - String - userId of user making request. + * @param assetGUID - String - unique id for the asset. + * @param tagName - String - name of the tag. + * @param tagDescription - String - (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. + * @return String - GUID for new tag. + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws PropertyServerException - There is a problem adding the asset properties to + * the property server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + public String addPrivateTagToAsset(String userId, + String assetGUID, + String tagName, + String tagDescription) throws InvalidParameterException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "addPrivateTagToAsset"; + final String guidParameter = "assetGUID"; + final String nameParameter = "tagName"; + + final String urlTemplate = "/{0}/asset/{1}/tags/private?tagName={2}&tagDescription={3}"; + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + validateGUID(assetGUID, guidParameter, methodName); + validateName(tagName, nameParameter, methodName); + + GUIDResponse restResult = callGUIDPOSTRESTCall(methodName, + omasServerURL + urlTemplate, + userId, + assetGUID, + tagName, + tagDescription); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowPropertyServerException(methodName, restResult); + + return restResult.getGUID(); + } + + + /** + * Adds a rating to the asset. + * + * @param userId - String - userId of user making request. + * @param assetGUID - String - unique id for the asset. + * @param starRating - StarRating - enumeration for none, one to five stars. + * @param review - String - user review of asset. + * + * @return guid of new rating object. + * + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws PropertyServerException - There is a problem adding the asset properties to + * the property server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + public String addRatingToAsset(String userId, + String assetGUID, + StarRating starRating, + String review) throws InvalidParameterException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "addRatingToAsset"; + final String guidParameter = "assetGUID"; + + final String urlTemplate = "/{0}/asset/{1}/ratings/?starRating={2}&review={3}"; + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + validateGUID(assetGUID, guidParameter, methodName); + + GUIDResponse restResult = callGUIDPOSTRESTCall(methodName, + omasServerURL + urlTemplate, + userId, + assetGUID, + starRating, + review); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowPropertyServerException(methodName, restResult); + + return restResult.getGUID(); + } + + + /** + * Adds a "Like" to the asset. + * + * @param userId - String - userId of user making request. + * @param assetGUID - String - unique id for the asset + * + * @return guid of new like object. + * + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws PropertyServerException - There is a problem adding the asset properties to + * the property server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + public String addLikeToAsset(String userId, + String assetGUID) throws InvalidParameterException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "addRatingToAsset"; + final String guidParameter = "assetGUID"; + + final String urlTemplate = "/{0}/asset/{1}/likes"; + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + validateGUID(assetGUID, guidParameter, methodName); + + GUIDResponse restResult = callGUIDPOSTRESTCall(methodName, + omasServerURL + urlTemplate, + userId, + assetGUID); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowPropertyServerException(methodName, restResult); + + return restResult.getGUID(); + } + + + /** + * Adds a comment to the asset. + * + * @param userId - String - userId of user making request. + * @param assetGUID - String - unique id for the asset. + * @param commentType - type of comment enum. + * @param commentText - String - the text of the comment. + * + * @return guid of new comment. + * + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws PropertyServerException - There is a problem adding the asset properties to + * the property server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + public String addCommentToAsset(String userId, + String assetGUID, + CommentType commentType, + String commentText) throws InvalidParameterException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "addCommentToAsset"; + final String guidParameter = "assetGUID"; + + final String urlTemplate = "/{0}/asset/{1}/comments?commentType{2}&commentText={3}"; + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + validateGUID(assetGUID, guidParameter, methodName); + + GUIDResponse restResult = callGUIDPOSTRESTCall(methodName, + omasServerURL + urlTemplate, + userId, + assetGUID, + commentType, + commentText); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowPropertyServerException(methodName, restResult); + + return restResult.getGUID(); + } + + + /** + * Adds a comment to the asset. + * + * @param userId - String - userId of user making request. + * @param commentGUID - String - unique id for an existing comment. Used to add a reply to a comment. + * @param commentType - type of comment enum. + * @param commentText - String - the text of the comment. + * + * @return guid of new comment. + * + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws PropertyServerException - There is a problem adding the asset properties to + * the property server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + public String addCommentReply(String userId, + String commentGUID, + CommentType commentType, + String commentText) throws InvalidParameterException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "addCommentReply"; + final String commentGUIDParameter = "commentGUID"; + final String urlTemplate = "/{0}/comments/{1}/reply?commentType={2}&commentText={3}"; + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + validateGUID(commentGUID, commentGUIDParameter, methodName); + + GUIDResponse restResult = callGUIDPOSTRESTCall(methodName, + omasServerURL + urlTemplate, + userId, + commentGUID, + commentType, + commentText); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowPropertyServerException(methodName, restResult); + + return restResult.getGUID(); + } + + + /** + * Removes a tag from the asset that was added by this user. + * + * @param userId - String - userId of user making request. + * @param tagGUID - String - unique id for the tag. + * + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws PropertyServerException - There is a problem updating the asset properties in + * the property server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + public void removeTag(String userId, + String tagGUID) throws InvalidParameterException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "removeTag"; + final String guidParameter = "tagGUID"; + + final String urlTemplate = "/{0}/tags/{guid}/delete"; + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + validateGUID(tagGUID, guidParameter, methodName); + + VoidResponse restResult = callVoidPostRESTCall(methodName, + omasServerURL + urlTemplate, + userId, + tagGUID); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowPropertyServerException(methodName, restResult); + } + + + /** + * Removes a tag from the asset that was added by this user. + * + * @param userId - String - userId of user making request. + * @param tagGUID - String - unique id for the tag. + * + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws PropertyServerException - There is a problem updating the asset properties in + * the property server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + public void removePrivateTag(String userId, + String tagGUID) throws InvalidParameterException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "removePrivateTag"; + final String guidParameter = "tagGUID"; + + final String urlTemplate = "/{0}/tags/private/{guid}/delete"; + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + validateGUID(tagGUID, guidParameter, methodName); + + VoidResponse restResult = callVoidPostRESTCall(methodName, + omasServerURL + urlTemplate, + userId, + tagGUID); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowPropertyServerException(methodName, restResult); + } + + + /** + * Removes of a star rating that was added to the asset by this user. + * + * @param userId - String - userId of user making request. + * @param ratingGUID - String - unique id for the rating object + * + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws PropertyServerException - There is a problem updating the asset properties in + * the property server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + public void removeRating(String userId, + String ratingGUID) throws InvalidParameterException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "removeRating"; + final String guidParameter = "ratingGUID"; + + final String urlTemplate = "/{0}/ratings/{guid}/delete"; + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + validateGUID(ratingGUID, guidParameter, methodName); + + VoidResponse restResult = callVoidPostRESTCall(methodName, + omasServerURL + urlTemplate, + userId, + ratingGUID); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowPropertyServerException(methodName, restResult); + } + + + /** + * Removes a "Like" added to the asset by this user. + * + * @param userId - String - userId of user making request. + * @param likeGUID - String - unique id for the like object + * + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws PropertyServerException - There is a problem updating the asset properties in + * the property server. + * @throws UserNotAuthorizedException - the requesting user is not authorized to issue this request. + */ + public void removeLike(String userId, + String likeGUID) throws InvalidParameterException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "removeLike"; + final String guidParameter = "likeGUID"; + + final String urlTemplate = "/{0}/likes/{guid}/delete"; + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + validateGUID(likeGUID, guidParameter, methodName); + + VoidResponse restResult = callVoidPostRESTCall(methodName, + omasServerURL + urlTemplate, + userId, + likeGUID); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowPropertyServerException(methodName, restResult); + } + + + /** + * Removes a comment added to the asset by this user. + * + * @param userId - String - userId of user making request. + * @param commentGUID - String - unique id for the comment object + * + * @throws InvalidParameterException - one of the parameters is null or invalid. + * @throws PropertyServerException - There is a problem updating the asset properties in + * the property server. + * @throws UserNotAuthorizedException - the user does not have permission to perform this request. + */ + public void removeComment(String userId, + String commentGUID) throws InvalidParameterException, + PropertyServerException, + UserNotAuthorizedException + { + final String methodName = "removeComment"; + final String guidParameter = "commentGUID"; + + final String urlTemplate = "/{0}/comments/{guid}/delete"; + + validateOMASServerURL(methodName); + validateUserId(userId, methodName); + validateGUID(commentGUID, guidParameter, methodName); + + VoidResponse restResult = callVoidPostRESTCall(methodName, + omasServerURL + urlTemplate, + userId, + commentGUID); + + this.detectAndThrowInvalidParameterException(methodName, restResult); + this.detectAndThrowUserNotAuthorizedException(methodName, restResult); + this.detectAndThrowPropertyServerException(methodName, restResult); + } + + + /** + * Throw an exception if a server URL has not been supplied on the constructor. + * + * @param methodName - name of the method making the call. + * @throws PropertyServerException - the server URL is not set + */ + private void validateOMASServerURL(String methodName) throws PropertyServerException + { + if (omasServerURL == null) + { + /* + * It is not possible to retrieve a connection without knowledge of where the OMAS Server is located. + */ + AssetConsumerErrorCode errorCode = AssetConsumerErrorCode.SERVER_URL_NOT_SPECIFIED; + String errorMessage = errorCode.getErrorMessageId() + errorCode.getFormattedErrorMessage(); + + throw new PropertyServerException(errorCode.getHTTPErrorCode(), + this.getClass().getName(), + methodName, + errorMessage, + errorCode.getSystemAction(), + errorCode.getUserAction()); + } + } + + + /** + * Throw an exception if the supplied userId is null + * + * @param userId - user name to validate + * @param methodName - name of the method making the call. + * @throws InvalidParameterException - the userId is null + */ + private void validateUserId(String userId, + String methodName) throws InvalidParameterException + { + if (userId == null) + { + AssetConsumerErrorCode errorCode = AssetConsumerErrorCode.NULL_USER_ID; + String errorMessage = errorCode.getErrorMessageId() + + errorCode.getFormattedErrorMessage(methodName); + + throw new InvalidParameterException(errorCode.getHTTPErrorCode(), + this.getClass().getName(), + methodName, + errorMessage, + errorCode.getSystemAction(), + errorCode.getUserAction()); + } + } + + + /** + * Throw an exception if the supplied userId is null + * + * @param guid - unique identifier to validate + * @param guidParameter - name of the parameter that passed the guid. + * @param methodName - name of the method making the call. + * @throws InvalidParameterException - the guid is null + */ + private void validateGUID(String guid, + String guidParameter, + String methodName) throws InvalidParameterException + { + if (guid == null) + { + AssetConsumerErrorCode errorCode = AssetConsumerErrorCode.NULL_GUID; + String errorMessage = errorCode.getErrorMessageId() + + errorCode.getFormattedErrorMessage(guidParameter, + methodName); + + throw new InvalidParameterException(errorCode.getHTTPErrorCode(), + this.getClass().getName(), + methodName, + errorMessage, + errorCode.getSystemAction(), + errorCode.getUserAction()); + } + } + + + /** + * Throw an exception if the supplied userId is null + * + * @param name - unique name to validate + * @param nameParameter - name of the parameter that passed the name. + * @param methodName - name of the method making the call. + * @throws InvalidParameterException - the guid is null + */ + private void validateName(String name, + String nameParameter, + String methodName) throws InvalidParameterException + { + if (name == null) + { + AssetConsumerErrorCode errorCode = AssetConsumerErrorCode.NULL_NAME; + String errorMessage = errorCode.getErrorMessageId() + + errorCode.getFormattedErrorMessage(nameParameter, + methodName); + + throw new InvalidParameterException(errorCode.getHTTPErrorCode(), + this.getClass().getName(), + methodName, + errorMessage, + errorCode.getSystemAction(), + errorCode.getUserAction()); + } + } + + + + /** + * Issue a GET REST call that returns a Connection object. + * + * @param methodName - name of the method being called + * @param urlTemplate - template of the URL for the REST API call with place-holders for the parameters + * @param params - a list of parameters that are slotted into the url template + * @return ConnectionResponse + * @throws PropertyServerException - something went wrong with the REST call stack. + */ + private ConnectionResponse callConnectionGetRESTCall(String methodName, + String urlTemplate, + Object... params) throws PropertyServerException + { + ConnectionResponse restResult = new ConnectionResponse(); + + /* + * Issue the request + */ + try + { + RestTemplate restTemplate = new RestTemplate(); + + restResult = restTemplate.getForObject(urlTemplate, restResult.getClass(), params); + } + catch (Throwable error) + { + AssetConsumerErrorCode errorCode = AssetConsumerErrorCode.CLIENT_SIDE_REST_API_ERROR; + String errorMessage = errorCode.getErrorMessageId() + errorCode.getFormattedErrorMessage(methodName, + omasServerURL, + error.getMessage()); + + throw new PropertyServerException(errorCode.getHTTPErrorCode(), + this.getClass().getName(), + methodName, + errorMessage, + errorCode.getSystemAction(), + errorCode.getUserAction(), + error); + } + + return restResult; + } + + + /** + * Issue a PATCH REST call that returns a TypeDefResponse object. + * + * @param methodName - name of the method being called + * @param urlTemplate - template of the URL for the REST API call with place-holders for the parameters + * @param params - a list of parameters that are slotted into the url template + * @return TypeDefResponse + * @throws PropertyServerException - something went wrong with the REST call stack. + */ + private GUIDResponse callGUIDPOSTRESTCall(String methodName, + String urlTemplate, + Object... params) throws PropertyServerException + { + GUIDResponse restResult = new GUIDResponse(); + + /* + * Issue the request + */ + try + { + RestTemplate restTemplate = new RestTemplate(); + + restResult = restTemplate.postForObject(urlTemplate, null, restResult.getClass(), params); + } + catch (Throwable error) + { + AssetConsumerErrorCode errorCode = AssetConsumerErrorCode.CLIENT_SIDE_REST_API_ERROR; + String errorMessage = errorCode.getErrorMessageId() + errorCode.getFormattedErrorMessage(methodName, + omasServerURL, + error.getMessage()); + + throw new PropertyServerException(errorCode.getHTTPErrorCode(), + this.getClass().getName(), + methodName, + errorMessage, + errorCode.getSystemAction(), + errorCode.getUserAction(), + error); + } + + return restResult; + } + + + /** + * Issue a POST REST call that returns a VoidResponse object. This is typically a create + * + * @param methodName - name of the method being called + * @param urlTemplate - template of the URL for the REST API call with place-holders for the parameters + * @param params - a list of parameters that are slotted into the url template + * @return VoidResponse + * @throws PropertyServerException - something went wrong with the REST call stack. + */ + private VoidResponse callVoidPostRESTCall(String methodName, + String urlTemplate, + Object... params) throws PropertyServerException + { + VoidResponse restResult = new VoidResponse(); + + /* + * Issue the request + */ + try + { + RestTemplate restTemplate = new RestTemplate(); + + restResult = restTemplate.postForObject(urlTemplate, null, restResult.getClass(), params); + } + catch (Throwable error) + { + AssetConsumerErrorCode errorCode = AssetConsumerErrorCode.CLIENT_SIDE_REST_API_ERROR; + String errorMessage = errorCode.getErrorMessageId() + errorCode.getFormattedErrorMessage(methodName, + omasServerURL, + error.getMessage()); + + throw new PropertyServerException(errorCode.getHTTPErrorCode(), + this.getClass().getName(), + methodName, + errorMessage, + errorCode.getSystemAction(), + errorCode.getUserAction(), + error); + } + + return restResult; + } + + + /** + * Throw an AmbiguousConnectionNameException if it is encoded in the REST response. + * + * @param methodName - name of the method called + * @param restResult - response from the rest call. This generated in the remote server. + * @throws AmbiguousConnectionNameException - encoded exception from the server + */ + private void detectAndThrowAmbiguousConnectionNameException(String methodName, + AssetConsumerOMASAPIResponse restResult) throws AmbiguousConnectionNameException + { + final String exceptionClassName = AmbiguousConnectionNameException.class.getName(); + + if ((restResult != null) && (exceptionClassName.equals(restResult.getExceptionClassName()))) + { + throw new AmbiguousConnectionNameException(restResult.getRelatedHTTPCode(), + this.getClass().getName(), + methodName, + restResult.getExceptionErrorMessage(), + restResult.getExceptionSystemAction(), + restResult.getExceptionUserAction()); + } + } + + + /** + * Throw an InvalidParameterException if it is encoded in the REST response. + * + * @param methodName - name of the method called + * @param restResult - response from the rest call. This generated in the remote server. + * @throws InvalidParameterException - encoded exception from the server + */ + private void detectAndThrowInvalidParameterException(String methodName, + AssetConsumerOMASAPIResponse restResult) throws InvalidParameterException + { + final String exceptionClassName = InvalidParameterException.class.getName(); + + if ((restResult != null) && (exceptionClassName.equals(restResult.getExceptionClassName()))) + { + throw new InvalidParameterException(restResult.getRelatedHTTPCode(), + this.getClass().getName(), + methodName, + restResult.getExceptionErrorMessage(), + restResult.getExceptionSystemAction(), + restResult.getExceptionUserAction()); + } + } + + + /** + * Throw an PropertyServerException if it is encoded in the REST response. + * + * @param methodName - name of the method called + * @param restResult - response from the rest call. This generated in the remote server. + * @throws PropertyServerException - encoded exception from the server + */ + private void detectAndThrowPropertyServerException(String methodName, + AssetConsumerOMASAPIResponse restResult) throws PropertyServerException + { + final String exceptionClassName = PropertyServerException.class.getName(); + + if ((restResult != null) && (exceptionClassName.equals(restResult.getExceptionClassName()))) + { + throw new PropertyServerException(restResult.getRelatedHTTPCode(), + this.getClass().getName(), + methodName, + restResult.getExceptionErrorMessage(), + restResult.getExceptionSystemAction(), + restResult.getExceptionUserAction()); + } + } + + + /** + * Throw an UnrecognizedConnectionGUIDException if it is encoded in the REST response. + * + * @param methodName - name of the method called + * @param restResult - response from the rest call. This generated in the remote server. + * @throws UnrecognizedConnectionGUIDException - encoded exception from the server + */ + private void detectAndThrowUnrecognizedConnectionGUIDException(String methodName, + AssetConsumerOMASAPIResponse restResult) throws UnrecognizedConnectionGUIDException + { + final String exceptionClassName = UnrecognizedConnectionGUIDException.class.getName(); + + if ((restResult != null) && (exceptionClassName.equals(restResult.getExceptionClassName()))) + { + throw new UnrecognizedConnectionGUIDException(restResult.getRelatedHTTPCode(), + this.getClass().getName(), + methodName, + restResult.getExceptionErrorMessage(), + restResult.getExceptionSystemAction(), + restResult.getExceptionUserAction()); + } + } + + + /** + * Throw an UnrecognizedConnectionNameException if it is encoded in the REST response. + * + * @param methodName - name of the method called + * @param restResult - response from the rest call. This generated in the remote server. + * @throws UnrecognizedConnectionNameException - encoded exception from the server + */ + private void detectAndThrowUnrecognizedConnectionNameException(String methodName, + AssetConsumerOMASAPIResponse restResult) throws UnrecognizedConnectionNameException + { + final String exceptionClassName = UnrecognizedConnectionNameException.class.getName(); + + if ((restResult != null) && (exceptionClassName.equals(restResult.getExceptionClassName()))) + { + throw new UnrecognizedConnectionNameException(restResult.getRelatedHTTPCode(), + this.getClass().getName(), + methodName, + restResult.getExceptionErrorMessage(), + restResult.getExceptionSystemAction(), + restResult.getExceptionUserAction()); + } + } + + + /** + * Throw an UserNotAuthorizedException if it is encoded in the REST response. + * + * @param methodName - name of the method called + * @param restResult - response from UserNotAuthorizedException - encoded exception from the server + */ + private void detectAndThrowUserNotAuthorizedException(String methodName, + AssetConsumerOMASAPIResponse restResult) throws UserNotAuthorizedException + { + final String exceptionClassName = UserNotAuthorizedException.class.getName(); + + if ((restResult != null) && (exceptionClassName.equals(restResult.getExceptionClassName()))) + { + throw new UserNotAuthorizedException(restResult.getRelatedHTTPCode(), + this.getClass().getName(), + methodName, + restResult.getExceptionErrorMessage(), + restResult.getExceptionSystemAction(), + restResult.getExceptionUserAction()); + } + } +}
http://git-wip-us.apache.org/repos/asf/atlas/blob/f57fd7f0/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/events/AssetConsumerEvent.java ---------------------------------------------------------------------- diff --git a/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/events/AssetConsumerEvent.java b/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/events/AssetConsumerEvent.java new file mode 100644 index 0000000..65a0634 --- /dev/null +++ b/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/events/AssetConsumerEvent.java @@ -0,0 +1,93 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * <p/> + * http://www.apache.org/licenses/LICENSE-2.0 + * <p/> + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.atlas.omas.assetconsumer.events; + +import com.fasterxml.jackson.annotation.JsonAutoDetect; +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonInclude; +import org.apache.atlas.omas.assetconsumer.properties.Asset; + +import java.io.Serializable; + +import static com.fasterxml.jackson.annotation.JsonAutoDetect.Visibility.NONE; +import static com.fasterxml.jackson.annotation.JsonAutoDetect.Visibility.PUBLIC_ONLY; + +/** + * AssetConsumerEvent describes the structure of the events emitted by the Asset Consumer OMAS. + */ +@JsonAutoDetect(getterVisibility=PUBLIC_ONLY, setterVisibility=PUBLIC_ONLY, fieldVisibility=NONE) +@JsonInclude(JsonInclude.Include.NON_NULL) +@JsonIgnoreProperties(ignoreUnknown=true) +public class AssetConsumerEvent implements Serializable +{ + AssetConsumerEventType eventType = AssetConsumerEventType.UNKNOWN_ASSET_CONSUMER_EVENT; + Asset asset = null; + + private static final long serialVersionUID = 1L; + + /** + * Default constructor + */ + public AssetConsumerEvent() + { + } + + + /** + * Return the type of event. + * + * @return event type enum + */ + public AssetConsumerEventType getEventType() + { + return eventType; + } + + + /** + * Set up the type of event. + * + * @param eventType - event type enum + */ + public void setEventType(AssetConsumerEventType eventType) + { + this.eventType = eventType; + } + + + /** + * Return the asset description. + * + * @return properties about the asset + */ + public Asset getAsset() + { + return asset; + } + + + /** + * Set up the asset description. + * + * @param asset - properties about the asset. + */ + public void setAsset(Asset asset) + { + this.asset = asset; + } +} http://git-wip-us.apache.org/repos/asf/atlas/blob/f57fd7f0/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/events/AssetConsumerEventType.java ---------------------------------------------------------------------- diff --git a/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/events/AssetConsumerEventType.java b/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/events/AssetConsumerEventType.java new file mode 100644 index 0000000..7e5a35d --- /dev/null +++ b/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/events/AssetConsumerEventType.java @@ -0,0 +1,98 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * <p/> + * http://www.apache.org/licenses/LICENSE-2.0 + * <p/> + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.atlas.omas.assetconsumer.events; + +import com.fasterxml.jackson.annotation.JsonAutoDetect; +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonInclude; + +import java.io.Serializable; + +import static com.fasterxml.jackson.annotation.JsonAutoDetect.Visibility.NONE; +import static com.fasterxml.jackson.annotation.JsonAutoDetect.Visibility.PUBLIC_ONLY; + +/** + * AssetConsumerEventType describes the different types of events produced by the AssetConsumer OMAS. + */ +@JsonAutoDetect(getterVisibility=PUBLIC_ONLY, setterVisibility=PUBLIC_ONLY, fieldVisibility=NONE) +@JsonInclude(JsonInclude.Include.NON_NULL) +@JsonIgnoreProperties(ignoreUnknown=true) +public enum AssetConsumerEventType implements Serializable +{ + UNKNOWN_ASSET_CONSUMER_EVENT (0, "UnknownAssetConsumerEvent", "An Asset Consumer event that is not recognized by the local server."), + NEW_ASSET_EVENT (1, "NewAsset", "A new asset has been defined."), + UPDATED_ASSET_EVENT (2, "UpdatedAsset", "An existing asset has been updated."), + DELETED_ASSET_EVENT (3, "DeletedAsset", "An existing asset has been deleted."); + + + private static final long serialVersionUID = 1L; + + private int eventTypeCode; + private String eventTypeName; + private String eventTypeDescription; + + + /** + * Default Constructor - sets up the specific values for this instance of the enum. + * + * @param eventTypeCode - int identifier used for indexing based on the enum. + * @param eventTypeName - string name used for messages that include the enum. + * @param eventTypeDescription - default description for the enum value - used when natural resource + * bundle is not available. + */ + AssetConsumerEventType(int eventTypeCode, String eventTypeName, String eventTypeDescription) + { + this.eventTypeCode = eventTypeCode; + this.eventTypeName = eventTypeName; + this.eventTypeDescription = eventTypeDescription; + } + + + /** + * Return the int identifier used for indexing based on the enum. + * + * @return int identifier code + */ + public int getEventTypeCode() + { + return eventTypeCode; + } + + + /** + * Return the string name used for messages that include the enum. + * + * @return String name + */ + public String getEventTypeName() + { + return eventTypeName; + } + + + /** + * Return the default description for the enum value - used when natural resource + * bundle is not available. + * + * @return String default description + */ + public String getEventTypeDescription() + { + return eventTypeDescription; + } +} http://git-wip-us.apache.org/repos/asf/atlas/blob/f57fd7f0/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/ffdc/AssetConsumerErrorCode.java ---------------------------------------------------------------------- diff --git a/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/ffdc/AssetConsumerErrorCode.java b/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/ffdc/AssetConsumerErrorCode.java new file mode 100644 index 0000000..226aea9 --- /dev/null +++ b/omas-assetconsumer/src/main/java/org/apache/atlas/omas/assetconsumer/ffdc/AssetConsumerErrorCode.java @@ -0,0 +1,251 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * <p/> + * http://www.apache.org/licenses/LICENSE-2.0 + * <p/> + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.atlas.omas.assetconsumer.ffdc; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import java.text.MessageFormat; +import java.util.Arrays; + +/** + * The AssetConsumerErrorCode is used to define first failure data capture (FFDC) for errors that occur when working with + * the Asset Consumer OMAS Services. It is used in conjunction with both Checked and Runtime (unchecked) exceptions. + * + * The 5 fields in the enum are: + * <ul> + * <li>HTTP Error Code - for translating between REST and JAVA - Typically the numbers used are:</li> + * <li><ul> + * <li>500 - internal error</li> + * <li>400 - invalid parameters</li> + * <li>404 - not found</li> + * <li>409 - data conflict errors - eg item already defined</li> + * </ul></li> + * <li>Error Message Id - to uniquely identify the message</li> + * <li>Error Message Text - includes placeholder to allow additional values to be captured</li> + * <li>SystemAction - describes the result of the error</li> + * <li>UserAction - describes how a AssetConsumerInterface should correct the error</li> + * </ul> + */ +public enum AssetConsumerErrorCode +{ + SERVER_URL_NOT_SPECIFIED(400, "OMAS-ASSETCONSUMER-400-001 ", + "The OMAS Server URL is null", + "The system is unable to connect to the OMAS Server to retrieve metadata properties.", + "Ensure a valid OMAS Server URL is passed to the AssetConsumer when it is created."), + SERVER_URL_MALFORMED(400, "OMAS-ASSETCONSUMER-400-002 ", + "The OMAS Server URL {0} is not in a recognized format", + "The system is unable to connect to the OMAS Server to retrieve metadata properties.", + "Ensure a valid OMAS Server URL is passed to the AssetConsumer when it is created."), + NULL_USER_ID(400, "OMAS-ASSETCONSUMER-400-003 ", + "The user identifier (user id) passed on the {0} operation is null", + "The system is unable to process the request without a user id.", + "Correct the code in the caller to provide the user id."), + NULL_GUID(400, "OMAS-ASSETCONSUMER-400-004 ", + "The unique identifier (guid) passed on the {0} parameter of the {1} operation is null", + "The system is unable to process the request without a guid.", + "Correct the code in the caller to provide the guid."), + NULL_NAME(400, "OMAS-ASSETCONSUMER-400-005 ", + "The name passed on the {0} parameter of the {1} operation is null", + "The system is unable to process the request without a name.", + "Correct the code in the caller to provide the name."), + NO_CONNECTED_ASSET(400, "OMAS-ASSETCONSUMER-400-006 ", + "The request for the properties of asset {0} failed with the following message returned: {1}", + "The system is unable to process the request.", + "Use the information in the message to understand the nature of the problem and once it is resolved, retry the request."), + TOO_MANY_CONNECTIONS(400, "OMAS-ASSETCONSUMER-400-007 ", + "The request for a named connection {0} from server {1} returned {2} connections", + "The system is unable to return the results.", + "Use the information in the message to understand the nature of the problem and once it is resolved, retry the request."), + USER_NOT_AUTHORIZED(400, "OMAS-ASSETCONSUMER-400-008 ", + "User {0} is not authorized to issue the {1} request for open metadata access service {3} on server {4}", + "The system is unable to process the request.", + "Verify the access rights of the user."), + PROPERTY_SERVER_ERROR(400, "OMAS-ASSETCONSUMER-400-009 ", + "An unexpected error with message \'{0}\' was returned by the property server during {1} request for open metadata access service {2} on server {3}", + "The system is unable to process the request.", + "Verify the access rights of the user."), + NULL_ENUM(400, "OMAS-ASSETCONSUMER-400-010 ", + "The enumeration value passed on the {0} parameter of the {1} operation is null", + "The system is unable to process the request without this enumeration value.", + "Correct the code in the caller to provide the name."), + NULL_TEXT(400, "OMAS-ASSETCONSUMER-400-011 ", + "The text field value passed on the {0} parameter of the {1} operation is null", + "The system is unable to process the request without this text field value.", + "Correct the code in the caller to provide the name."), + OMRS_NOT_INITIALIZED(404, "OMAS-ASSETCONSUMER-404-001 ", + "The open metadata repository services are not initialized for the {0} operation", + "The system is unable to connect to the open metadata property server.", + "Check that the server where the Asset Consumer OMAS is running initialized correctly. " + + "Correct any errors discovered and retry the request when the open metadata services are available."), + OMRS_NOT_AVAILABLE(404, "OMAS-ASSETCONSUMER-404-002 ", + "The open metadata repository services are not available for the {0} operation", + "The system is unable to connect to the open metadata property server.", + "Check that the server where the Asset Consumer OMAS is running initialized correctly. " + + "Correct any errors discovered and retry the request when the open metadata services are available."), + NO_METADATA_COLLECTION(404, "OMAS-ASSETCONSUMER-404-004 ", + "The requested connection {0} is not found in OMAS Server {1}", + "The system is unable to populate the requested connection object.", + "Check that the connection name and the open metadata server URL is correct. Retry the request when the connection is available in the OMAS Service"), + CONNECTION_NOT_FOUND(404, "OMAS-ASSETCONSUMER-404-005 ", + "The requested connection {0} is not found in OMAS Server {1}, optional error message {2}", + "The system is unable to populate the requested connection object.", + "Check that the connection name and the OMAS Server URL is correct. Retry the request when the connection is available in the OMAS Service"), + PROXY_CONNECTION_FOUND(404, "OMAS-ASSETCONSUMER-404-006 ", + "Only an entity proxy for requested connection {0} is found in the open metadata server {1}, error message was: {2}", + "The system is unable to populate the requested connection object.", + "Check that the connection name and the OMAS Server URL is correct. Retry the request when the connection is available in the OMAS Service"), + ASSET_NOT_FOUND(404, "OMAS-ASSETCONSUMER-404-006 ", + "The requested asset {0} is not found for connection {1}", + "The system is unable to populate the asset properties object because none of the open metadata repositories are returning the asset's properties.", + "Verify that the OMAS Service running and the connection definition in use is linked to the Asset definition in the metadata repository. Then retry the request."), + UNKNOWN_ASSET(404, "OMAS-ASSETCONSUMER-404-006 ", + "The asset with unique identifier {0} is not found for method {1} of access service {2} in open metadata server {3}, error message was: {4}", + "The system is unable to update information associated with the asset because none of the connected open metadata repositories recognize the asset's unique identifier.", + "The unique identifier of the asset is supplied by the caller. Verify that the caller's logic is correct, and that there are no errors being reported by the open metadata repository. Once all errors have been resolved, retry the request."), + NULL_CONNECTION_RETURNED(500, "OMAS-ASSETCONSUMER-500-001 ", + "The requested connection named {0} is not returned by the open metadata Server {1}", + "The system is unable to create a connector because the OMAS Server is not returning the Connection properties.", + "Verify that the OMAS server running and the connection definition is correctly configured."), + NULL_CONNECTOR_RETURNED(500, "OMAS-ASSETCONSUMER-500-002 ", + "The requested connector for connection named {0} is not returned by the OMAS Server {1}", + "The system is unable to create a connector.", + "Verify that the OMAS server is running and the connection definition is correctly configured."), + NULL_RESPONSE_FROM_API(503, "OMAS-ASSETCONSUMER-503-001 ", + "A null response was received from REST API call {0} to server {1}", + "The system has issued a call to an open metadata access service REST API in a remote server and has received a null response.", + "Look for errors in the remote server's audit log and console to understand and correct the source of the error."), + CLIENT_SIDE_REST_API_ERROR(503, "OMAS-ASSETCONSUMER-503-002 ", + "A client-side exception was received from API call {0} to repository {1}. The error message was {2}", + "The server has issued a call to the open metadata access service REST API in a remote server and has received an exception from the local client libraries.", + "Look for errors in the local server's console to understand and correct the source of the error."), + SERVICE_NOT_INITIALIZED(503, "OMAS-ASSETCONSUMER-503-003 ", + "The access service has not been initialized and can not support REST API call {0}", + "The server has received a call to one of its open metadata access services but is unable to process it because the access service is not active.", + "If the server is supposed to have this access service activated, correct the server configuration and restart the server.") + ; + + + private int httpErrorCode; + private String errorMessageId; + private String errorMessage; + private String systemAction; + private String userAction; + + private static final Logger log = LoggerFactory.getLogger(AssetConsumerErrorCode.class); + + + /** + * The constructor for AssetConsumerErrorCode expects to be passed one of the enumeration rows defined in + * AssetConsumerErrorCode above. For example: + * + * AssetConsumerErrorCode errorCode = AssetConsumerErrorCode.ASSET_NOT_FOUND; + * + * This will expand out to the 5 parameters shown below. + * + * @param newHTTPErrorCode - error code to use over REST calls + * @param newErrorMessageId - unique Id for the message + * @param newErrorMessage - text for the message + * @param newSystemAction - description of the action taken by the system when the error condition happened + * @param newUserAction - instructions for resolving the error + */ + AssetConsumerErrorCode(int newHTTPErrorCode, String newErrorMessageId, String newErrorMessage, String newSystemAction, String newUserAction) + { + this.httpErrorCode = newHTTPErrorCode; + this.errorMessageId = newErrorMessageId; + this.errorMessage = newErrorMessage; + this.systemAction = newSystemAction; + this.userAction = newUserAction; + } + + + public int getHTTPErrorCode() + { + return httpErrorCode; + } + + + /** + * Returns the unique identifier for the error message. + * + * @return errorMessageId + */ + public String getErrorMessageId() + { + return errorMessageId; + } + + + /** + * Returns the error message with placeholders for specific details. + * + * @return errorMessage (unformatted) + */ + public String getUnformattedErrorMessage() + { + return errorMessage; + } + + + /** + * Returns the error message with the placeholders filled out with the supplied parameters. + * + * @param params - strings that plug into the placeholders in the errorMessage + * @return errorMessage (formatted with supplied parameters) + */ + public String getFormattedErrorMessage(String... params) + { + if (log.isDebugEnabled()) + { + log.debug(String.format("<== OCFErrorCode.getMessage(%s)", Arrays.toString(params))); + } + + MessageFormat mf = new MessageFormat(errorMessage); + String result = mf.format(params); + + if (log.isDebugEnabled()) + { + log.debug(String.format("==> OCFErrorCode.getMessage(%s): %s", Arrays.toString(params), result)); + } + + return result; + } + + + /** + * Returns a description of the action taken by the system when the condition that caused this exception was + * detected. + * + * @return systemAction + */ + public String getSystemAction() + { + return systemAction; + } + + + /** + * Returns instructions of how to resolve the issue reported in this exception. + * + * @return userAction + */ + public String getUserAction() + { + return userAction; + } +}
