Platform Services¶

The platform services provide the methods for:

• Querying the origin and capabilities of the OMAG Server Platform.
• Starting and stopping OMAG Servers on the platform and shutting down the platform itself.
• Discovering information about the OMAG Servers that the platform is hosting.
• Dynamically setting up the platform metadata security connector.
• Shutting down the OMAG Server Platform

These methods are available through a Java client, or directly by calling the REST API.

Platform services client¶

The Platform Services client is called PlatformServicesClient. It is located in the platform-services-client module and use definitions from the platform-services-api.

Each Java client has multiple constructors. The constructors set up the connection to the OMAG Server Platform. The parameters are passed in different combinations to control security and logging.

• platformName - the descriptive name of the OMAG Server Platform for error logging.
• platformURLRoot - the platform url root of the OMAG Server Platform.
• auditLog - logging destination for audit log messages.
• userId - this is the optional userId that is embedded in all REST calls. Think of it as the client's user Id rather than the userId of the end user.
• password - this is the password that goes with the client's userId. The userId and password should both be supplied or neither.
• maxPageSize - controls the maximum number of results that can be returned on any call. If this is not set, the max page size is controlled platform-side.
• restClient - inside the java client is a REST API connector that manages the marshalling and de-marshalling of the requests into the HTTP protocol used by REST. Normally this connector is created by the client, but this parameter enables an externally created connector to be used instead.

The constructor may throw InvalidParameterException if there is an issue setting up the client-side components based on the supplied parameters. Pick the constructor that matches the parameters you have. For example, if you call the constructor that supports the client's userId and password and you pass null in these parameters, the exception is thrown.

Below is an example of the code used to construct the PlatformServicesClient.

1

PlatformServicesClient platformServicesClient = new PlatformServicesClient("MyPlatform", platformURLRoot);

Once the client is created, use it to call the API it offers which is documented using Javadoc. All calls take the userId of the caller. Methods that are specific to an OMAG server will also take the server name as a parameter.

Querying the origin and capabilities of the platform¶

The OMAG Server Platform can be built in a variety of ways, both expanding and removing the services delivered by the Egeria community. Therefore it is useful to be able to query a particular OMAG Server Plaftorm to discover what it can do.

Platform origin¶

The platform origin method is used to confirm that the platform is running, and the release of Egeria it is built from.

1

String platformOrigin = platformServicesClient.getPlatformOrigin(clientUserId);

POST {{platformURLRoot}}/open-metadata/platfrom-services/users/{{adminUserId}}/server-platform/origin

The call returns a string value of:

Egeria OMAG Server Platform (version {release})

Registered services¶

It is also possible to list the registered services that are available in the platform.

1
2
3
4

List<RegisteredOMAGService> registeredOMASs = platformServicesClient.getAccessServices(clientUserId);
List<RegisteredOMAGService> registeredOMESs = platformServicesClient.getEngineServices(clientUserId);
List<RegisteredOMAGService> registeredOMISs = platformServicesClient.getIntegrationServices(clientUserId);
List<RegisteredOMAGService> registeredOMVSs = platformServicesClient.getViewServices(clientUserId);

GET {{platformURLRoot}}/open-metadata/platfrom-services/users/{{adminUserId}}/registered-services/access-services
GET {{platformURLRoot}}/open-metadata/platfrom-services/users/{{adminUserId}}/registered-services/engine-services
GET {{platformURLRoot}}/open-metadata/platfrom-services/users/{{adminUserId}}/registered-services/integration-services
GET {{platformURLRoot}}/open-metadata/platfrom-services/users/{{adminUserId}}/registered-services/view-services

Each entry in RegisteredOMAGService details:

• serviceId - the component identifier used by the service when it registers with the audit log.
• serviceName - the name of the service.
• serviceDevelopmentStatus - the status of the service.
• serviceURLMarker - the unique string used in this service's REST API path names.
• serviceDescription - the description of the service.
• serviceWiki - the page in Egeria's documentation that provides more detail of the service.

Supported connectors¶

It is possible to validate whether a specific connector's implementation is included in the OMAG Server Platform's classpath by using the getConnectorType method. This takes the class name of the connector's provider class. It tries to create an instance of the connector and returns it supported connector type.

1

ConnectorType connectorType = platformServicesClient.getConnectorType(clientUserId, "org.odpi.openmetadata.metadatasecurity.samples.CocoPharmaPlatformSecurityProvider");

POST {{platformURLRoot}}/open-metadata/platform-services/users/{{user}}/server-platform/connector-types/org.odpi.openmetadata.metadatasecurity.samples.CocoPharmaPlatformSecurityProvider

{
    "class": "ConnectorTypeResponse",
    "relatedHTTPCode": 200,
    "connectorType": {
        "class": "ConnectorType",
        "headerVersion": 0,
        "type": {
            "typeId": "954421eb-33a6-462d-a8ca-b5709a1bd0d4",
            "typeName": "ConnectorType",
            "typeVersion": 1,
            "typeDescription": "A set of properties describing a type of connector."
        },
        "guid": "c7026446-8d9e-4149-8da0-5c800cf7fc23",
        "qualifiedName": "Egeria:Sample:PlatformSecurity:CocoPharmaceuticals",
        "displayName": "Coco Pharmaceuticals Platform Security Connector",
        "description": "Connector supports a hard-coded user registry and authorization rules for Coco Pharmaceuticals.",
        "connectorProviderClassName": "org.odpi.openmetadata.metadatasecurity.samples.CocoPharmaPlatformSecurityProvider",
        "connectorFrameworkName": "Open Connector Framework (OCF)",
        "connectorInterfaceLanguage": "Java",
        "connectorInterfaces": [
            "org.odpi.openmetadata.frameworks.connectors.SecureConnectorExtension",
            "org.odpi.openmetadata.metadatasecurity.OpenMetadataPlatformSecurity"
        ]
    }
}

Starting OMAG Servers and stopping OMAG Servers¶

The code sample shows the method calls to start and stop named OMAG Servers.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

    /**
     * Start the named server on the platform.  This will fail if the platform is not running,
     * or if the user is not authorized to issue operations requests to the platform or if the
     * server is not configured.
     *
     * @param serverName string name
     */
    private void startServer(String serverName)
    {
        try
        {
            PlatformServiceClient client = new PlatformServiceClient(serverName, platformURLRoot);

            System.out.println("Starting " + serverName + " ...");
            System.out.println(client.activateWithStoredConfig(clientUserId));
        }
        catch (Exception error)
        {
            System.out.println("There was an " + error.getClass().getName() + " exception when calling the platform.  Error message is: " + error.getMessage());
        }
    }


    /**
     * Stop the requested server.    This will fail if the server or the platform is not running,
     * or if the user is not authorized to issue operations requests to the platform.
     *
     * @param serverName string name
     */
    private void stopServer(String serverName)
    {
        try
        {
            PlatformServiceClient client = new PlatformServiceClient(serverName, platformURLRoot);

            System.out.println("Stopping " + serverName + " ...");

            client.deactivateTemporarily(clientUserId);

            System.out.println(serverName + " stopped.");
        }
        catch (Exception error)
        {
            System.out.println("There was an " + error.getClass().getName() + " exception when calling the platform.  Error message is: " + error.getMessage());
        }
    }

Querying the status of the OMAG Servers on the platform¶

Known servers¶

The known servers are those servers that have run on the platform since it started. The getKnownServers method returns a list of server names which is useful for stepping through each of the servers in a for loop.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

List<String> serverList = platformServicesClient.getKnownServers(clientUserId);

if (serverList != null)
{
    for (String serverName : serverList)
    {
        if (serverName != null)
        {
           /*
            * Add code here
            */
       }
    }
}

Active servers¶

The active servers are those servers running on the platform. The getActiveServers returns a list of names of the servers running when the request was made.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

List<String> serverList = platformServicesClient.getActiveServers(clientUserId);

if (serverList != null)
{
    for (String serverName : serverList)
    {
        if (serverName != null)
        {
            /*
             * Add code here
             */
        }
    }
}

Once you have the serverName, you can query the status of an OMAG Server running on the platform:

1

ServerStatus platformServerStatus = platformServicesClient.getServerStatus(clientUserId, serverName);

The platformServerStatus returned includes:

• serverName - Name of the server.
• isActive - Boolean flag indicating whether it is active (running) on the server.
• serverStartTime - The most recent date/time that the server started.
• serverEndTime - The most recent date/time that the server stopped.
• serverHistory - The list of start and stop times for the previous restarts of the server.

This helps to ascertain when the server was available.

Querying the active server status¶

It is also able to retrieve the status of the services running within an active server.

The status of the server (and its nested services) is one of 5 values:

• Unknown - The state of the server is unknown. This is equivalent to a null value.
• Starting - The server is starting.
• Running - The server has completed start up and is running.
• Stopping - The server has received a request to shutdown.
• Inactive - The server is not running.

The server type is derived by the platform services when it starts the server. It is based on an assessment of the capabilities requested in the configuration document.

Dynamically configuring the platform metadata security connector¶

The OMAG Server Platform provides both configuration and diagnostic services for OMAG Servers which in themselves provide access to a wide variety of information and control points. Therefore, it is necessary to provide authorization services relating to the dynamic management of the platform.

Egeria provides a platform security authorization capability. It is implemented in a platform metadata security connector that is called whenever requests are made to the server platform services.

Security is configured for a specific platform once it is running by using the following command.

Determine configured security¶

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/platform/security/connection

{
    "class": "PlatformSecurityRequestBody",
    "urlRoot": "{{platformURLRoot}}",
    "platformSecurityConnection" : 
    {
        "class": "Connection",
        "connectorType": 
        {
            "class": "ConnectorType",
            "connectorProviderClassName": "org.odpi.openmetadata.metadatasecurity.samples.CocoPharmaPlatformSecurityProvider"
        }
    }
}

Determine configured security¶

It is possible to query the setting of the platform security connector using the following command:

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/platform/security/connection

{
    "class": "ConnectionResponse",
    "relatedHTTPCode": 200
}

{
    "class": "ConnectionResponse",
    "relatedHTTPCode": 200,
    "connection": {
        "class": "Connection",
        "connectorType": {
            "class": "ConnectorType",
            "connectorProviderClassName": "org.odpi.openmetadata.metadatasecurity.samples.CocoPharmaPlatformSecurityProvider"
        }
    }
}

Remove configured security¶

It is possible to remove the configuration for the connector using the following command:

{{platformURLRoot}}/open-metadata/admin-services/users/{{adminUserId}}/platform/security/connection

This removes all authorization checking from the platform services.

Shutting down the OMAG Server Platform¶

In release 4.2 we introduced a new method to shut down an OMAG Server Platform. This allows a remote client to terminate the OMAG Server Platform. When this method is called , the platform terminates immediately and a "connection closed" error response is returned to the caller.

1
2
3
4
5
6
7

try
{
    platformServicesClient.shutdownPlatform(clientUserId);
}
catch (Exception platformGone)
{
}

DELETE {{platformURLRoot}}/open-metadata/platfrom-services/users/{{adminUserId}}/server-platform/instance

Raise an issue or comment below