Usage

JLupin Platform Managemnt Client is divided into layers which are configured when initalizing objects to interact with. First layer is an object to communicate with platform itself. It is created with platform client and is of type JLupinMainServerTransmissionEntryPointCommandForwarder. This layer is responsible for running platform commands and to select proper communication scheme (to use SSL or not).

Second layer is an object of type RemoteExecutor. This is wrapper for platform commands to provide option for additional computing when calling platform commands (like for example enabling caching).

Third layer is an high level API which is used by clients for platform management. It is divided into main three groups: query, operation and update. They separate tasks by their scope of changes. Query API is used only to retrieve information from platform and does not change anything. Operation API is changing ephermal state of platform, like ex. microservice status with start/stop/restart command. Update API is used to changed permament platform settings which are remembered even when platform is restarted.

Adding dependency

JLupin Platform Managemnt Client is distributed as a library which can be incldued in your project. If you use Maven in your project just add below lines into your <dependencies>:

<dependency>
    <groupId>com.jlupin</groupId>
    <artifactId>jlupin-platform-management-client</artifactId>
    <version>${jlupin.platform.management.client.version}</version>
</dependency>

Creating JLupinMainServerTransmissionEntryPointCommandForwarder

To create JLupinMainServerTransmissionEntryPointCommandForwarder with SSL configuration just use code below:

final SSLSocketFactory sslSocketFactory = JLupinSecurityUtil.getTwoWayAuthenticationSSLClientSocketFactory(
    "ssl/client/clientX509Certificate.crt",
    "ssl/client/clientPrivateKey.pk",
    "ssl/server/serverX509Certificate.crt"
);

JLupinSSLCommunicationProtocolUtilSocketFactoryImpl.initialize(sslSocketFactory);

final JLupinMainServerTransmissionEntryPointCommandForwarder commandForwarder =
    new JLupinMainServerTransmissionEntryPointCommandForwarder(
        JLupinSSLCommunicationProtocolUtilSocketFactoryImpl.getInstance()
    );

To create JLupinMainServerTransmissionEntryPointCommandForwarder without SSL configuration just use code below:

final JLupinMainServerTransmissionEntryPointCommandForwarder commandForwarder =
    new JLupinMainServerTransmissionEntryPointCommandForwarder(
        JLupinDefaultCommunicationProtocolUtilSocketFactoryImpl.getInstance()
    );

Creating RemoteExecutor

RemoteExecutorImpl

There is only one constructor available for this implementation:

public RemoteExecutorImpl(
        final Logger actionsLogger, final PrintStreamFunction printStream, final String clientName,
        final JLupinMainServerTransmissionEntryPointCommandForwarder commandForwarder
)

Description of arguments:

• actionsLogger - Through this argument you provides instance of logger used by library. It can be any logger which implements SLF4J.
• printStream - Some commands returns additional output (beside command result) while executing. For example while restarting microservice you will see there live output from restart operation on platform.
• clientName - Name of client which connects to platform. It will be visible in logs on the other side.
• commandForwarder - Command forwarder created in previous step.

Example code:

final Logger logger = LoggerFactory.getLogger(Example.class);

final RemoteExecutor remoteExecutor = new RemoteExecutorImpl(
        logger, logger::debug, "client-name", commandForwarder
);

RemoteExecutorWithCacheImpl

There is only one constructor available for this implementation:

public RemoteExecutorWithCacheImpl(
        final Logger actionsLogger, final PrintStreamFunction printStream, final String clientName,
        final JLupinMainServerTransmissionEntryPointCommandForwarder commandForwarder,
        final RemoteExecutorCache cache
)

Description of arguments:

• actionsLogger - Through this argument you provides instance of logger used by library. It can be any logger which implements SLF4J.
• printStream - Some commands returns additional output (beside command result) while executing. For example while restarting microservice you will see there live output from restart operation on platform.
• clientName - Name of client which connects to platform. It will be visible in logs on the other side.
• commandForwarder - Command forwarder created in previous step.
• cache - Cache instance used by remote executor. Some operations are cleared in cache after some other operations are executed (this way Query API would have proper data after microservice restart for example). For now there is only one implementation of RemoteExecutorCache which is InMemoryRemoteExecutorCacheImpl with default constructor.

Example code:

final Logger logger = LoggerFactory.getLogger(Example.class);
final RemoteExecutorCache cache = new InMemoryRemoteExecutorCacheImpl();

final RemoteExecutor remoteExecutor = new RemoteExecutorWithCacheImpl(
        logger, logger::debug, "client-name", commandForwarder, cache
);

Creating API

QueryAPI

As said before QueryAPI is used to retrieve platform data. For now there is only one available implementation which is QueryAPIImpl. Full exmaple code to create QueryAPI:

import com.jlupin.entrypoint.command.forwarder.transmission.main.JLupinMainServerTransmissionEntryPointCommandForwarder;
import com.jlupin.impl.util.communication.factory.socket.impl.defaults.JLupinDefaultCommunicationProtocolUtilSocketFactoryImpl;
import com.jlupin.platform.management.client.api.query.impl.QueryAPIImpl;
import com.jlupin.platform.management.client.api.query.interfaces.QueryAPI;
import com.jlupin.platform.management.client.remote.executor.cache.impl.InMemoryRemoteExecutorCacheImpl;
import com.jlupin.platform.management.client.remote.executor.cache.intefaces.RemoteExecutorCache;
import com.jlupin.platform.management.client.remote.executor.impl.RemoteExecutorWithCacheImpl;
import com.jlupin.platform.management.client.remote.executor.interfaces.RemoteExecutor;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Example {
    private static final Logger logger = LoggerFactory.getLogger(Example.class);

    public void example() {
        final SSLSocketFactory sslSocketFactory = JLupinSecurityUtil.getTwoWayAuthenticationSSLClientSocketFactory(
                "ssl/client/clientX509Certificate.crt",
                "ssl/client/clientPrivateKey.pk",
                "ssl/server/serverX509Certificate.crt"
        );

        JLupinSSLCommunicationProtocolUtilSocketFactoryImpl.initialize(sslSocketFactory);

        final JLupinMainServerTransmissionEntryPointCommandForwarder commandForwarder =
                new JLupinMainServerTransmissionEntryPointCommandForwarder(
                        JLupinSSLCommunicationProtocolUtilSocketFactoryImpl.getInstance()
                );

        final RemoteExecutorCache cache = new InMemoryRemoteExecutorCacheImpl();

        final RemoteExecutor remoteExecutor = new RemoteExecutorWithCacheImpl(
                logger, logger::debug, "client-name", commandForwarder, cache
        );

        final QueryAPI queryAPI = new QueryAPIImpl(remoteExecutor);
    }
}

OperationAPI

As said before OperationAPI is used to chagne ephermal platform state. For now there is only one available implementation which is OperationAPIImpl. Full exmaple code to create OperationAPI:

import com.jlupin.entrypoint.command.forwarder.transmission.main.JLupinMainServerTransmissionEntryPointCommandForwarder;
import com.jlupin.impl.util.communication.factory.socket.impl.defaults.JLupinDefaultCommunicationProtocolUtilSocketFactoryImpl;
import com.jlupin.platform.management.client.api.operation.impl.OperationAPIImpl;
import com.jlupin.platform.management.client.api.operation.interfaces.OperationAPI;
import com.jlupin.platform.management.client.remote.executor.cache.impl.InMemoryRemoteExecutorCacheImpl;
import com.jlupin.platform.management.client.remote.executor.cache.intefaces.RemoteExecutorCache;
import com.jlupin.platform.management.client.remote.executor.impl.RemoteExecutorWithCacheImpl;
import com.jlupin.platform.management.client.remote.executor.interfaces.RemoteExecutor;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Example {
    private static final Logger logger = LoggerFactory.getLogger(Example.class);

    public void example() {
        final SSLSocketFactory sslSocketFactory = JLupinSecurityUtil.getTwoWayAuthenticationSSLClientSocketFactory(
                "ssl/client/clientX509Certificate.crt",
                "ssl/client/clientPrivateKey.pk",
                "ssl/server/serverX509Certificate.crt"
        );

        JLupinSSLCommunicationProtocolUtilSocketFactoryImpl.initialize(sslSocketFactory);

        final JLupinMainServerTransmissionEntryPointCommandForwarder commandForwarder =
                new JLupinMainServerTransmissionEntryPointCommandForwarder(
                        JLupinSSLCommunicationProtocolUtilSocketFactoryImpl.getInstance()
                );

        final RemoteExecutorCache cache = new InMemoryRemoteExecutorCacheImpl();

        final RemoteExecutor remoteExecutor = new RemoteExecutorWithCacheImpl(
                logger, logger::debug, "client-name", commandForwarder, cache
        );

        final OperationAPI operationAPI = new OperationAPIImpl(remoteExecutor);
    }
}

UpdateAPI

As said before UpdateAPI is used to change permanent platform state. For now there is only one available implementation which is UpdateAPIImpl. Full exmaple code to create UpdateAPI:

import com.jlupin.entrypoint.command.forwarder.transmission.main.JLupinMainServerTransmissionEntryPointCommandForwarder;
import com.jlupin.impl.util.communication.factory.socket.impl.defaults.JLupinDefaultCommunicationProtocolUtilSocketFactoryImpl;
import com.jlupin.platform.management.client.api.update.impl.UpdateAPIImpl;
import com.jlupin.platform.management.client.api.update.interfaces.UpdateAPI;
import com.jlupin.platform.management.client.remote.executor.cache.impl.InMemoryRemoteExecutorCacheImpl;
import com.jlupin.platform.management.client.remote.executor.cache.intefaces.RemoteExecutorCache;
import com.jlupin.platform.management.client.remote.executor.impl.RemoteExecutorWithCacheImpl;
import com.jlupin.platform.management.client.remote.executor.interfaces.RemoteExecutor;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Example {
    private static final Logger logger = LoggerFactory.getLogger(Example.class);

    public void example() {
        final SSLSocketFactory sslSocketFactory = JLupinSecurityUtil.getTwoWayAuthenticationSSLClientSocketFactory(
                "ssl/client/clientX509Certificate.crt",
                "ssl/client/clientPrivateKey.pk",
                "ssl/server/serverX509Certificate.crt"
        );

        JLupinSSLCommunicationProtocolUtilSocketFactoryImpl.initialize(sslSocketFactory);

        final JLupinMainServerTransmissionEntryPointCommandForwarder commandForwarder =
                new JLupinMainServerTransmissionEntryPointCommandForwarder(
                        JLupinSSLCommunicationProtocolUtilSocketFactoryImpl.getInstance()
                );

        final RemoteExecutorCache cache = new InMemoryRemoteExecutorCacheImpl();

        final RemoteExecutor remoteExecutor = new RemoteExecutorWithCacheImpl(
                logger, logger::debug, "client-name", commandForwarder, cache
        );

        final UpdateAPI updateAPI = new UpdateAPIImpl(remoteExecutor);
    }
}