Merge pull request #7721 from MihaiIliescu/review_and_promote_asset_l…

…ineage_to_tech_preview

Added missing documentation items for Asset Lineage

open-metadata-implementation/access-services/asset-lineage/asset-lineage-api/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/event/package-info.java

@@ -0,0 +1,7 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* Copyright Contributors to the ODPi Egeria project. */
+
+/**
+ * Definitions of the different types of events that the Asset Lineage OMAS can publish.
+ */
+package org.odpi.openmetadata.accessservices.assetlineage.event;

open-metadata-implementation/access-services/asset-lineage/asset-lineage-api/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/ffdc/exception/package-info.java

@@ -0,0 +1,7 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* Copyright Contributors to the ODPi Egeria project. */
+
+/**
+ * Exceptions for reporting errors found when using the Asset Lineage OMAS services.
+ */
+package org.odpi.openmetadata.accessservices.assetlineage.ffdc.exception;

open-metadata-implementation/access-services/asset-lineage/asset-lineage-api/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/model/package-info.java

@@ -0,0 +1,7 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* Copyright Contributors to the ODPi Egeria project. */
+
+/**
+ * This package holds the classes needed to create and represent the lineage graph.
+ */
+package org.odpi.openmetadata.accessservices.assetlineage.model;

open-metadata-implementation/access-services/asset-lineage/asset-lineage-client/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/package-info.java

@@ -0,0 +1,7 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* Copyright Contributors to the ODPi Egeria project. */
+
+/**
+ * The Asset Lineage OMAS provides services to query the lineage of business terms and data assets.
+ */
+package org.odpi.openmetadata.accessservices.assetlineage;

open-metadata-implementation/access-services/asset-lineage/asset-lineage-server/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/admin/package-info.java

@@ -0,0 +1,7 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* Copyright Contributors to the ODPi Egeria project. */
+
+/**
+ * Provides the implementation of the admin classes that are called during server start up and shut down.
+ */
+package org.odpi.openmetadata.accessservices.assetlineage.admin;

open-metadata-implementation/access-services/asset-lineage/asset-lineage-server/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/auditlog/AssetLineageAuditCode.java

@@ -7,78 +7,122 @@
 import org.odpi.openmetadata.frameworks.auditlog.messagesets.AuditLogMessageSet;
 import org.odpi.openmetadata.repositoryservices.auditlog.OMRSAuditLogRecordSeverity;
 
+/**
+ * The AssetManagerAuditCode is used to define the message content for the OMRS Audit Log.
+ * The 5 fields in the enum are:
+ * <ul>
+ *     <li>Log Message Id - to uniquely identify the message</li>
+ *     <li>Severity - is this an event, decision, action, error or exception</li>
+ *     <li>Log Message Text - includes placeholder to allow additional values to be captured</li>
+ *     <li>SystemAction - describes the result of the situation</li>
+ *     <li>UserAction - describes how a user should correct the situation</li>
+ * </ul>
+ */
 public enum AssetLineageAuditCode implements AuditLogMessageSet {
-
+    /**
+     * OMAS-ASSET-LINEAGE-0001 The Asset Lineage Open Metadata Access Service (OMAS) is initializing a new server instance.
+     */
     SERVICE_INITIALIZING("OMAS-ASSET-LINEAGE-0001",
             OMRSAuditLogRecordSeverity.STARTUP,
             "The Asset Lineage Open Metadata Access Service (OMAS) is initializing a new server instance",
             "The local server has started up a new instance of the Asset Lineage OMAS.",
             Constants.NORMAL_OPERATION_OF_THE_SERVER),
 
-
+    /**
+     * OMAS-ASSET-LINEAGE-0002 The Asset Lineage OMAS has completed initialization.
+     */
     SERVICE_INITIALIZED("OMAS-ASSET-LINEAGE-0002",
             OMRSAuditLogRecordSeverity.STARTUP,
             "The Asset Lineage Open Metadata Access Service (OMAS) has initialized a new instance for server {0}",
             "The Asset Lineage OMAS has completed initialization.",
             Constants.NORMAL_OPERATION_OF_THE_SERVER),
 
+    /**
+     * OMAS-ASSET-LINEAGE-0003 The local server has requested shut down of an Asset Lineage OMAS server instance.
+     */
     SERVICE_SHUTDOWN("OMAS-ASSET-LINEAGE-0003",
             OMRSAuditLogRecordSeverity.SHUTDOWN,
             "The Asset Lineage Open Metadata Access Service (OMAS) is shutting down server instance {0}",
             "The local server has requested shut down of an Asset Lineage OMAS server instance.",
             Constants.NORMAL_OPERATION_OF_THE_SERVER),
 
-
+    /**
+     * OMAS-ASSET-LINEAGE-0004 The access service detected an error during the start up of a specific server instance.  Its services are not available for the server.
+     */
     SERVICE_INSTANCE_FAILURE("OMAS-ASSET-LINEAGE-0004",
             OMRSAuditLogRecordSeverity.ERROR,
             "The Asset Lineage Open Metadata Access Service (OMAS) is unable to initialize a new instance; error message is {0} from server {1}",
             "The access service detected an error during the start up of a specific server instance.  Its services are not available for the server.",
             "Review the error message and any other reported failures to determine the cause of the problem.  Once this is resolved, restart the server."),
 
+    /**
+     * OMAS-ASSET-LINEAGE-0005 The event could not be processed.
+     */
     EVENT_PROCESSING_EXCEPTION("OMAS-ASSET-LINEAGE-0005",
             OMRSAuditLogRecordSeverity.EXCEPTION,
             "An exception {0} occurred from server {1} while processing incoming event {2}",
             "The event could not be processed",
             "Review the exception to determine the source of the error and correct it."),
 
+    /**
+     * OMAS-ASSET-LINEAGE-0006 The Asset Lineage OMAS records information about processing sequence.
+     */
     PUBLISH_PROCESS_INFO("OMAS-ASSET-LINEAGE-0006",
             OMRSAuditLogRecordSeverity.INFO,
             "{0} Processing sequence entity type {1} with a total of {2} items",
             "The Asset Lineage OMAS records information about processing sequence.",
             Constants.NO_ACTION_IS_REQUIRED),
 
+    /**
+     * OMAS-ASSET-LINEAGE-0007 The Asset Lineage OMAS records information about entity.
+     */
     ENTITY_INFO("OMAS-ASSET-LINEAGE-0007",
             OMRSAuditLogRecordSeverity.INFO,
             "{0} Entity type {1} guid {2}",
             "The Asset Lineage OMAS records information about entity.",
             Constants.NO_ACTION_IS_REQUIRED),
 
+    /**
+     * OMAS-ASSET-LINEAGE-0008 The Asset Lineage OMAS records error while processing entity.
+     */
     ENTITY_ERROR("OMAS-ASSET-LINEAGE-0008",
             OMRSAuditLogRecordSeverity.ERROR,
             "Error processing entity type {0} guid {1}",
             "The Asset Lineage OMAS records error while processing entity.",
             "Review the error message and check the entity in question to determine the cause of the problem."),
 
+    /**
+     * OMAS-ASSET-LINEAGE-0009 Error while trying to use AssetLineagePublisher instance.
+     */
     PUBLISH_EVENT_ERROR("OMAS-ASSET-LINEAGE-0009",
                                   OMRSAuditLogRecordSeverity.ERROR,
             "Error while trying to use AssetLineagePublisher instance.",
-                                          "The Asset Lineage OMAS will not publish entity.",
-                                          "Possible configuration error; Contact the server administrator to " +
-                                                  "check accessServiceOutTopic connection configuration before tying again."),
+            "The Asset Lineage OMAS will not publish entity.",
+            "Possible configuration error; Contact the server administrator to " +
+                    "check accessServiceOutTopic connection configuration before tying again."),
 
+    /**
+     * OMAS-ASSET-LINEAGE-0010 The Asset Lineage OMAS retrieves entity's asset context.
+     */
     ASSET_CONTEXT_INFO("OMAS-ASSET-LINEAGE-0010",
             OMRSAuditLogRecordSeverity.INFO,
             "The asset context for the entity with guid {0} is requested through REST endpoint and will be " +
                     "retrieved on the out topic.",
             "The Asset Lineage OMAS retrieves entity's asset context.",
             Constants.NO_ACTION_IS_REQUIRED),
 
+    /**
+     * OMAS-ASSET-LINEAGE-0011 The Asset Lineage OMAS is configured with property name {} and value {}
+     */
     CONFIGURED_PUBLISHER_BATCH_SIZE("OMAS-ASSET-LINEAGE-0011",
                                      OMRSAuditLogRecordSeverity.STARTUP,
-                                     "The Asset Lineage OMAS is configured with property name {0} and value {1}.",
-                                             "The access service was passed this value in the {0} property of the access service's options.",
-                                             "Verify that this value is correct for your organization."),
+            "The Asset Lineage OMAS is configured with property name {0} and value {1}.",
+            "The access service was passed this value in the {0} property of the access service's options.",
+            "Verify that this value is correct for your organization."),
 
+    /**
+     * OMAS-ASSET-LINEAGE-0012 The access service was passed invalid value in access service's options.
+     */
     INVALID_PUBLISHER_BATCH_SIZE("OMAS-ASSET-LINEAGE-0012",
             OMRSAuditLogRecordSeverity.ERROR,
             "The Asset Lineage OMAS cannot be configured with property name {0}",

open-metadata-implementation/access-services/asset-lineage/asset-lineage-server/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/auditlog/package-info.java

@@ -0,0 +1,7 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* Copyright Contributors to the ODPi Egeria project. */
+
+/**
+ * The auditlog package provides the definition of any messages that are used for auditing the operation of the Asset Lineage.
+ */
+package org.odpi.openmetadata.accessservices.assetlineage.auditlog;

open-metadata-implementation/access-services/asset-lineage/asset-lineage-server/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/converters/package-info.java

@@ -0,0 +1,7 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* Copyright Contributors to the ODPi Egeria project. */
+
+/**
+ * Provides the converters that take beans from the repository services (eg entities and relationships) and converts them into Asset Lineage OMAS beans to return to the caller.
+ */
+package org.odpi.openmetadata.accessservices.assetlineage.converters;

open-metadata-implementation/access-services/asset-lineage/asset-lineage-server/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/handlers/package-info.java

@@ -0,0 +1,7 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* Copyright Contributors to the ODPi Egeria project. */
+
+/**
+ * These handlers drive the interaction with the metadata repositories.
+ */
+package org.odpi.openmetadata.accessservices.assetlineage.handlers;

open-metadata-implementation/access-services/asset-lineage/asset-lineage-server/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/listeners/package-info.java

@@ -0,0 +1,8 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* Copyright Contributors to the ODPi Egeria project. */
+
+/**
+ * Supports the processing of events from the repository services that notify this module of changes to the metadata
+ * in the repository services.
+ */
+package org.odpi.openmetadata.accessservices.assetlineage.listeners;

open-metadata-implementation/access-services/asset-lineage/asset-lineage-server/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/outtopic/package-info.java

@@ -0,0 +1,7 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* Copyright Contributors to the ODPi Egeria project. */
+
+/**
+ * Produces events on the Asset Lineage OMAS's out topic.
+ */
+package org.odpi.openmetadata.accessservices.assetlineage.outtopic;

open-metadata-implementation/access-services/asset-lineage/asset-lineage-server/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/server/package-info.java

@@ -0,0 +1,7 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* Copyright Contributors to the ODPi Egeria project. */
+
+/**
+ * Provides the server side support for the REST API.
+ */
+package org.odpi.openmetadata.accessservices.assetlineage.server;

open-metadata-implementation/access-services/asset-lineage/asset-lineage-server/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/util/package-info.java

@@ -0,0 +1,7 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* Copyright Contributors to the ODPi Egeria project. */
+
+/**
+ * Utility classes for writing out Asset Lineage
+ */
+package org.odpi.openmetadata.accessservices.assetlineage.util;

open-metadata-implementation/access-services/asset-lineage/asset-lineage-spring/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/server/spring/AssetLineageResource.java

@@ -3,6 +3,7 @@
 package org.odpi.openmetadata.accessservices.assetlineage.server.spring;
 
 import io.swagger.v3.oas.annotations.ExternalDocumentation;
+import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.odpi.openmetadata.accessservices.assetlineage.model.FindEntitiesParameters;
 import org.odpi.openmetadata.accessservices.assetlineage.server.AssetLineageRestServices;
@@ -21,7 +22,10 @@
 import java.util.Date;
 import java.util.List;
 
-
+/**
+ * The AssetLineageResource class is a Spring REST controller that provides endpoints for querying and publishing asset lineage information.
+ * It is part of the Asset Lineage OMAS (Open Metadata Access Service) and allows users to interact with the asset lineage.
+ */
 @RestController
 @RequestMapping("/servers/{serverName}/open-metadata/access-services/asset-lineage/users/{userId}/")
 
@@ -34,7 +38,7 @@ public class AssetLineageResource {
     private final AssetLineageRestServices restAPI = new AssetLineageRestServices();
 
     /**
-     * Scan the cohort based on the given entity type and publish the contexts for the found entities to the out topic
+     * Scan the cohort based on the given entity type and publish the contexts for the found entities to the out topic.
      *
      * @param serverName name of server instance to call
      * @param userId     the name of the calling user
@@ -52,6 +56,10 @@ public class AssetLineageResource {
      * @return a list of unique identifiers (guids) of the available entities with the given type provided as a response
      */
     @GetMapping(path = "/publish-entities/{entityType}")
+    @Operation(summary = "scanEntitiesByTypeAndPublish",
+               description = "Scan the cohort based on the given entity type and publish the contexts for the found entities to the out topic.",
+               externalDocs = @ExternalDocumentation(description = "Asset Lineage - Publish Entities",
+                                                     url = "https://egeria-project.org/services/omas/asset-lineage/overview/#publish-entities"))
     public GUIDListResponse publishEntities(@PathVariable String serverName,
                                             @PathVariable String userId,
                                             @PathVariable String entityType,
@@ -83,6 +91,10 @@ public GUIDListResponse publishEntities(@PathVariable String serverName,
      * @return a list of unique identifiers (guids) of the available entity with the given type provided as a response
      */
     @GetMapping(path = "/publish-entity/{entityType}/{guid}")
+    @Operation(summary = "findEntityByGuidAndPublishContext",
+               description = "Find the entity by guid and publish the context for it.",
+               externalDocs = @ExternalDocumentation(description = "Asset Lineage - Publish Entity",
+                                                  url = "https://egeria-project.org/services/omas/asset-lineage/overview/#publish-entity"))
     public GUIDListResponse publishEntity(@PathVariable String serverName,
                                           @PathVariable String userId,
                                           @PathVariable String guid,
@@ -100,6 +112,10 @@ public GUIDListResponse publishEntity(@PathVariable String serverName,
      * @return a list of unique identifiers (guids) of the available entities that exist in the published context
      */
     @GetMapping(path = "/publish-context/{entityType}/{guid}")
+    @Operation(summary = "findEntityByGuidAndPublishAssetContext",
+               description = "Find the entity by guid and publish the asset context for it. It applies for data tables and files.",
+               externalDocs = @ExternalDocumentation(description = "Asset Lineage - Publish Asset Context",
+                                                     url = "https://egeria-project.org/services/omas/asset-lineage/overview/#publish-context"))
     public GUIDListResponse publishAssetContext(@PathVariable String serverName,
                                             @PathVariable String userId,
                                             @PathVariable String guid,
@@ -120,7 +136,10 @@ public GUIDListResponse publishAssetContext(@PathVariable String serverName,
      * PropertyServerException problem retrieving the discovery engine definition.
      */
     @GetMapping(path = "/topics/out-topic-connection/{callerId}")
-
+    @Operation(summary = "getOutTopicConnection",
+               description = "Return the connection object for the Asset Lineage's OMAS's out topic.",
+               externalDocs = @ExternalDocumentation(description = "Asset Lineage - Out Topic Connection",
+                                                     url = "https://egeria-project.org/services/omas/asset-lineage/overview/#out-topic-connection"))
     public ConnectionResponse getOutTopicConnection(@PathVariable String serverName,
                                                     @PathVariable String userId,
                                                     @PathVariable String callerId)

open-metadata-implementation/access-services/asset-lineage/asset-lineage-spring/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/server/spring/package-info.java

@@ -0,0 +1,9 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* Copyright Contributors to the ODPi Egeria project. */
+
+/**
+ * This package provides the server-side implementation of the Asset Lineage OMAS using the Spring framework.
+ * It includes the AssetLineageResource class, which defines the RESTful endpoints for querying and publishing asset lineage information.
+ * The endpoints allow users to scan the cohort, find and publish entities, and retrieve connection information for the Asset Lineage OMAS's out topic.
+ */
+package org.odpi.openmetadata.accessservices.assetlineage.server.spring;

open-metadata-implementation/access-services/asset-lineage/asset-lineage-topic-connectors/src/main/java/org/odpi/openmetadata/accessservices/assetlineage/outtopic/connector/package-info.java

@@ -0,0 +1,14 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+/* Copyright Contributors to the ODPi Egeria project. */
+
+/**
+ * This package provides the implementation for the client-side connector that receives events
+ * from the Asset Lineage OMAS's OutTopic.
+ *
+ * It includes the AssetLineageOutTopicClientConnector class, which handles the registration of event listeners
+ * and processing of inbound events. The package also contains the AssetLineageOutTopicClientProvider class,
+ * which serves as the connector provider for the AssetLineageOutTopicClientConnector.
+ *
+ * Together, these classes enable the receipt and handling of events on the Asset Lineage OMAS OutTopic.
+ */
+package org.odpi.openmetadata.accessservices.assetlineage.outtopic.connector;

open-metadata-implementation/access-services/asset-manager/asset-manager-api/src/main/java/org/odpi/openmetadata/accessservices/assetmanager/ffdc/AssetManagerAuditCode.java

@@ -14,7 +14,6 @@
  *     <li>Log Message Id - to uniquely identify the message</li>
  *     <li>Severity - is this an event, decision, action, error or exception</li>
  *     <li>Log Message Text - includes placeholder to allow additional values to be captured</li>
- *     <li>Additional Information - further parameters and data relating to the audit message (optional)</li>
  *     <li>SystemAction - describes the result of the situation</li>
  *     <li>UserAction - describes how a user should correct the situation</li>
  * </ul>