Skip to main content

Using AMPS spark CLI

This reference has a page for each command available in the AMPS spark CLI. For more information on the features available in AMPS, see the relevant chapters in this guide.

To run this client, simply type ./bin/spark at the command line from the AMPS spark CLI installation directory. It will output its help screen as shown below, with a brief description of the AMPS spark CLI features.

%> ./bin/spark
===============================
- Spark - AMPS client utility -
===============================
Usage:

    spark help [command]

Supported Commands:

    help
    ping
    publish
    sow
    sow_and_subscribe
    sow_delete
    subscribe

Example:

    %> ./spark help sow

Returns the help and usage information for the 'sow' command.

AMPS spark CLI Commands​

Each command topic describes commonly used options and includes examples. For the full range of options, including compatibility options, use spark help.

  • help: Display command usage and available options.
  • publish: Publish messages to an AMPS topic.
  • sow: Query messages stored in the AMPS State of the World.
  • subscribe: Subscribe to live messages from an AMPS topic.
  • sow_and_subscribe: Query the AMPS State of the World and subscribe to live updates.
  • sow_delete: Delete records from the AMPS State of the World.
  • ping: Test connectivity and logon to an AMPS instance.

AMPS spark CLI Authentication​

AMPS spark CLI includes a way to provide credentials to AMPS for use with instances that are configured to require authentication. For example, to use a specific user ID and password to authenticate to AMPS, simply provide them in the URI in the format user:password@host:port.

The command below shows how to use AMPS spark CLI to subscribe to a server, providing the specified username and password to AMPS.

$AMPS_HOME/bin/spark subscribe -type json \
                               -server username:password@localhost:9007

AMPS also provides the ability to implement custom authentication, and many production deployments use customized authentication methods. To support this, the AMPS spark CLI authentication scheme is customizable. By default, the authentication scheme used by AMPS spark CLI simply provides the username and password from the -server parameter, as described above.

Authentication schemes for AMPS spark CLI are implemented in Java, as classes that implement Authenticator -- the same method used by the AMPS Java client. To use a different authentication scheme with AMPS spark CLI, you implement the AuthenticatorFactory interface in AMPS spark CLI to return your custom authenticator, adjust the CLASSPATH to include the .jar file that contains the authenticator, and then provide the name of your AuthenticatorFactory on the command line. See the AMPS Java Client API documentation for details on implementing a custom Authenticator.

For a factory implementation and examples of loading your authenticator, see Custom Authentication with AMPS spark CLI.

The command below explicitly loads the default factory, found in the spark package, without adjusting the CLASSPATH.

$AMPS_HOME/bin/spark subscribe –server username:password@localhost:9007 \
                               -type json -topic foo \
      -authenticator com.crankuptheamps.spark.DefaultAuthenticatorFactory

AMPS spark CLI Support for TCPS​

AMPS spark CLI supports secure connections over SSL for AMPS TCPS transports. Details about the available AMPS spark CLI command options are provided in each command topic.

AMPS spark CLI recognizes the AMPS_SPARK_OPTS environment variable for passing Java properties to the underlying JVM. This is needed for SSL properties such as -Djavax.net.ssl.trustStore and -Djavax.net.ssl.trustStorePassword.

Typically, it is sufficient to set the trust store JVM properties in the AMPS_SPARK_OPTS environment variable and specify the secure option with a valid value. If secure is set to true, yes, or 1, the connection will use the tcps URI scheme; otherwise, it will use tcp.

%> export AMPS_SPARK_OPTS="-Djavax.net.ssl.trustStore=./cacerts -Djavax.net.ssl.trustStorePassword=changeit"
%> ./spark subscribe -secure 1 -server localhost:10110 -type json -topic Orders

The example above places a subscription on the Orders topic over a tcps connection.

If additional customization of the AMPS connection URI is required, the urischeme and uriopts options can be specified. For example, a custom AMPS Client Transport can be created and associated with a specific URI scheme by defining a custom Transport class and mapping it to the chosen URI scheme name.

In the example below, a custom AMPS Client Transport is associated with the URI scheme protected:

%> export AMPS_SPARK_OPTS="-Djavax.net.ssl.trustStore=./cacerts -Djavax.net.ssl.trustStorePassword=changeit -cp secure.jar:spark.jar"
%> ./spark subscribe -urischeme protected -server localhost:10110 -type json -topic Orders

This will generate the following URI:

protected://localhost:10110/amps/json

In this case you would specify the option urischeme, which refers to a custom AMPS Client Transport. The custom class would need to be added to the Java classpath using AMPS_SPARK_OPTS. If both urischeme and secure were provided in this example, urischeme would override secure.

For more information on properties to define to customize SSL connections, see the SSL section in the Advanced Topics chapter of the AMPS Java Developer Guide.

For information on URI parameters that can be used to customize AMPS spark CLI connections, using the uriopts option, see the Connection Parameters for AMPS chapter of the AMPS Java Developer Guide.