Package org.hansken.plugin.extraction.runtime.grpc.client

Class ExtractionPluginClient

java.lang.Object

org.hansken.plugin.extraction.runtime.grpc.client.ExtractionPluginClient

All Implemented Interfaces:

AutoCloseable, BaseExtractionPlugin, RemoteExtractionPlugin

public class ExtractionPluginClient
extends Object
implements RemoteExtractionPlugin, AutoCloseable

Client to connect to a running Extraction Plugin (server).

This client acts as a proxy between the clean API and an extraction plugin implementation that is served by a remote gRPC server.

Author:

Netherlands Forensic Institute

Constructor Summary

Constructors

Constructor	Description
ExtractionPluginClient(String target)	Same as ExtractionPluginClient(String, int), but with a target string instead.
ExtractionPluginClient(String host, int port)	Constructor for the Extraction Plugin client.
ExtractionPluginClient(String host, int port, RetryPolicy retryPolicy)	See ExtractionPluginClient(String, int), but with a RetryPolicy.
ExtractionPluginClient(String target, RetryPolicy retryPolicy)	Same as ExtractionPluginClient(String, RetryPolicy), but with a target string instead.
ExtractionPluginClient(String target, RetryPolicy retryPolicy, String pluginId)	Same as ExtractionPluginClient(String, RetryPolicy), but with a pluginId parameter for routing.

Method Summary

Modifier and Type	Method	Description
protected ExtractionPluginGrpcAdapter	adapter(ClientTrace trace, ClientDataContext dataContext, TraceSearcher searcher)	Returns an adapter that translates gRPC protocol messages to clean API calls.
void	close()
static Object	createTransformerArgument(String type, String value)
Map<String,TransformerArgument>	deserializeJsonArguments(TransformerLabel label, Map<String,String> arguments)
String	getPluginApiVersion()	Returns the API version of the Remote Extraction Plugin.
String	getTarget()	Gets the client's connection target, a String which consists of a host and port.
protected ProtocolHandler	handler(ClientTrace trace, ClientDataContext dataContext, TraceSearcher searcher, ReplyStream stream)	Returns a handler for orchestrating the processing of a trace over gRPC.
protected RpcTransformerResponse	invokeTransformer(RpcTransformerRequest request)	Invoke a transformer with a given request.
boolean	isCompatible()	Checks that the API implemented by the remote plugin is compatible with the currently loaded (runtime) Extraction Plugin SDK version.
PluginInfo	pluginInfo()
void	process(ClientTrace trace, ClientDataContext dataContext)	See ExtractionPlugin.process(Trace, DataContext), but requires a special type of Trace.
void	processDeferred(ClientTrace trace, ClientDataContext dataContext, TraceSearcher searcher)	See ExtractionPlugin.process(Trace, DataContext), but requires a special type of Trace.
TransformerArgument	transform(TransformerLabel label, Map<String,String> stringMap)	Calls a transformer method of a remote extraction plugin.
void	validateTransformerRequest(TransformerLabel label, Map<String,TransformerArgument> arguments)	Validates if a transformer request given a transformer label and specific arguments is correct.

Methods inherited from class java.lang.Object

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

Constructor Details

ExtractionPluginClient

public ExtractionPluginClient(String host,
 int port)

Constructor for the Extraction Plugin client.

During construction of this client object no actual connection is created, so if the server is not available on the provided host and port, no exception is thrown. Instead, an exception will be thrown each time a new info or process-method is invoked. In case the client has to fail early it should invoke pluginInfo() directly after constructing the client.

There is no retry policy configured, for this, use ExtractionPluginClient(String, int, RetryPolicy).

Parameters:

host - Host where the extraction plugin server is running

port - Port where the extraction plugin server is running on

ExtractionPluginClient

public ExtractionPluginClient(String host,
 int port,
 RetryPolicy retryPolicy)

See ExtractionPluginClient(String, int), but with a RetryPolicy.

Parameters:

host - host where the extraction plugin server is running

port - port where the extraction plugin server is running

retryPolicy - the retry configuration policy to use, or null if no policy should be used

ExtractionPluginClient

public ExtractionPluginClient(String target)

Same as ExtractionPluginClient(String, int), but with a target string instead.

Parameters:

target - endpoint where the extraction plugin server is running

ExtractionPluginClient

public ExtractionPluginClient(String target,
 RetryPolicy retryPolicy)

Same as ExtractionPluginClient(String, RetryPolicy), but with a target string instead.

Parameters:

target - endpoint where the extraction plugin server is running

retryPolicy - the retry configuration policy to use, or null if no policy should be used

ExtractionPluginClient

public ExtractionPluginClient(String target,
 RetryPolicy retryPolicy,
 String pluginId)

Same as ExtractionPluginClient(String, RetryPolicy), but with a pluginId parameter for routing.

Parameters:

target - endpoint where the extraction plugin server is running

retryPolicy - the retry configuration policy to use, or null if no policy should be used

pluginId - the id of the plugin, which is set in the header, for routing purposes

Method Details

isCompatible

public boolean isCompatible()

Description copied from interface: RemoteExtractionPlugin

Checks that the API implemented by the remote plugin is compatible with the currently loaded (runtime) Extraction Plugin SDK version.

Specified by:

isCompatible in interface RemoteExtractionPlugin

Returns:

true if compatible, false otherwise

getPluginApiVersion

public String getPluginApiVersion()

Returns the API version of the Remote Extraction Plugin.

Returns:

API version

pluginInfo

public PluginInfo pluginInfo()

Specified by:

pluginInfo in interface BaseExtractionPlugin

process

public void process(ClientTrace trace,
 ClientDataContext dataContext)
             throws IOException

Description copied from interface: RemoteExtractionPlugin

See ExtractionPlugin.process(Trace, DataContext), but requires a special type of Trace.

Specified by:

process in interface RemoteExtractionPlugin

Parameters:

trace - the trace to process

dataContext - data context of this trace extraction

Throws:

IOException - when an I/O error occurs

processDeferred

public void processDeferred(ClientTrace trace,
 ClientDataContext dataContext,
 TraceSearcher searcher)
                     throws IOException

Description copied from interface: RemoteExtractionPlugin

See ExtractionPlugin.process(Trace, DataContext), but requires a special type of Trace.

Specified by:

processDeferred in interface RemoteExtractionPlugin

Parameters:

trace - the trace to process

dataContext - data context of this trace extraction

searcher - the trace searcher

Throws:

IOException - when an I/O error occurs

validateTransformerRequest

public void validateTransformerRequest(TransformerLabel label,
 Map<String,TransformerArgument> arguments)
                                throws IllegalArgumentException

Validates if a transformer request given a transformer label and specific arguments is correct.

Parameters:

label - The transformer label specifying the transformer method that is to be called.

arguments - The actual arguments that the transformer method is to be invoked with.

Throws:

IllegalArgumentException - Any validation errors describing how the current label and arguments are not compliant.

transform

public TransformerArgument transform(TransformerLabel label,
 Map<String,String> stringMap)

Description copied from interface: RemoteExtractionPlugin

Calls a transformer method of a remote extraction plugin.

Specified by:

transform in interface RemoteExtractionPlugin

Parameters:

label - Describes the name, parameters and return type of the transformer method that we want to invoke.

stringMap - The actual arguments we want to pass to the method. Specified as a name and value pair.

Returns:

Returns a value that was produced by the transformer method.

deserializeJsonArguments

public Map<String,TransformerArgument> deserializeJsonArguments(TransformerLabel label,
 Map<String,String> arguments)

createTransformerArgument

public static Object createTransformerArgument(String type,
 String value)

invokeTransformer

protected RpcTransformerResponse invokeTransformer(RpcTransformerRequest request)

Invoke a transformer with a given request. This method is isolated such that it can be easily used for mocking.

Parameters:

request - The transformer request containing the transformer name and arguments we want to invoke it with.

Returns:

The returned response from the transformer.

getTarget

public String getTarget()

Gets the client's connection target, a String which consists of a host and port. For example: localhost:8999.

Returns:

a host and port combined into an authority string

handler

protected ProtocolHandler handler(ClientTrace trace,
 ClientDataContext dataContext,
 TraceSearcher searcher,
 ReplyStream stream)

Returns a handler for orchestrating the processing of a trace over gRPC.

This method is exposed as protected method so we can hook into this object using unit tests.

Parameters:

trace - the trace to process

dataContext - the data context to process

searcher - the trace searcher

stream - the outbound communication stream

Returns:

a gRPC handler

adapter

protected ExtractionPluginGrpcAdapter adapter(ClientTrace trace,
 ClientDataContext dataContext,
 TraceSearcher searcher)

Returns an adapter that translates gRPC protocol messages to clean API calls.

This method is exposed as protected method so we can hook into this object using unit tests.

Parameters:

trace - the trace on which to make the API calls

dataContext - the data context on which to make the API calls

searcher - the searcher on which to make the API calls

Returns:

gRPC adapter object

close

public void close()
           throws InterruptedException

Specified by:

close in interface AutoCloseable

Throws:

InterruptedException