com.suse.salt.netapi.client

Class SaltClient

java.lang.Object

com.suse.salt.netapi.client.SaltClient

public class SaltClient
extends Object

Salt API client.

Constructor Summary

Constructors

Constructor and Description
SaltClient(URI url) Constructor for connecting to a given URL.
SaltClient(URI url, ConnectionFactory connectionFactory) Constructor for connecting to a given URL using a specific connection factory.
SaltClient(URI url, ConnectionFactory connectionFactory, ExecutorService executor) Constructor for connecting to a given URL using a specific connection factory.
SaltClient(URI url, ExecutorService executor) Constructor for connecting to a given URL.

Method Summary

Modifier and Type	Method and Description
<R> R	call(Call<?> call, Client client, String endpoint, Optional<Map<String,Object>> custom, com.google.gson.reflect.TypeToken<R> type) Generic interface to make a Call to an endpoint using a given Client.
<R> R	call(Call<?> call, Client client, String endpoint, com.google.gson.reflect.TypeToken<R> type) Convenience method to make a call without arguments.
EventStream	events(EventListener... listeners) Returns a WebSocket @ClientEndpoint annotated object connected to the /ws ServerEndpoint.
ClientConfig	getConfig() Directly access the configuration.
ResultInfoSet	getJobResult(ScheduledJob job) Query for the result of a supplied job.
ResultInfoSet	getJobResult(String job) Query for the result of a supplied job.
Map<String,Job>	getJobs() Get previously run jobs.
Future<Map<String,Job>>	getJobsAsync() Asynchronously get previously run jobs.
Map<String,Object>	getMinionDetails(String minionId) Query for details (grains) of the specified minion.
Future<Map<String,Object>>	getMinionDetailsAsync(String minionId) Query for details (grains) of the specified minion asynchronously.
Map<String,Map<String,Object>>	getMinions() Query for all minions and immediately return a map of minions keyed by minion id.
Future<Map<String,Map<String,Object>>>	getMinionsAsync() Asynchronously query for all minions and return a map of minions keyed by minion id.
Key.Names	keys() Query general key information.
Future<Key.Names>	keysAsync() Asynchronously query general key information.
Token	login(String username, String password, AuthModule eauth) Perform login and return the token.
Future<Token>	loginAsync(String username, String password, AuthModule eauth) Asynchronously perform login and return a Future with the token.
boolean	logout() Perform logout and clear the session token from the config.
Future<Boolean>	logoutAsync() Asynchronously perform logout and clear the session token from the config.
<T> Map<String,Object>	run(String username, String password, AuthModule eauth, String client, Target<T> target, String function, List<Object> args, Map<String,Object> kwargs) Generic interface to start any execution command bypassing normal session handling.
<T> Future<Map<String,Object>>	runAsync(String username, String password, AuthModule eauth, String client, Target<T> target, String function, List<Object> args, Map<String,Object> kwargs) Asynchronously start any execution command bypassing normal session handling.
<T> Map<String,Result<SSHRawResult>>	runRawSSHCommand(String command, Target<T> target, SaltSSHConfig cfg) Calls salt-ssh with a command in raw shell mode (commands bypass Salt and gets executed as shell commands).
boolean	sendEvent(String eventTag, String eventData) Trigger an event in Salt with the specified tag and data.
Future<Boolean>	sendEventAsync(String eventTag, String eventData) Asynchronously trigger an event in Salt with the specified tag and data.
void	setProxy(ProxySettings settings) Configure to use a proxy when connecting to the Salt API.
<T> ScheduledJob	startCommand(Target<T> target, String function, List<Object> args, Map<String,Object> kwargs) Generic interface to start any execution command and immediately return an object representing the scheduled job.
<T> Future<ScheduledJob>	startCommandAsync(Target<T> target, String function, List<Object> args, Map<String,Object> kwargs) Asynchronously start any execution command and immediately return an object representing the scheduled job.
Stats	stats() Query statistics from the CherryPy Server.
Future<Stats>	statsAsync() Asynchronously query statistics from the CherryPy Server.

Methods inherited from class java.lang.Object

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

Constructor Detail

SaltClient

public SaltClient(URI url)

Constructor for connecting to a given URL.

Parameters:

url - the Salt API URL

SaltClient

public SaltClient(URI url,
                  ConnectionFactory connectionFactory)

Constructor for connecting to a given URL using a specific connection factory.

Parameters:

url - the Salt API URL

connectionFactory - ConnectionFactory implementation

SaltClient

public SaltClient(URI url,
                  ExecutorService executor)

Constructor for connecting to a given URL.

Parameters:

url - the Salt API URL

executor - ExecutorService to be used for async operations

SaltClient

public SaltClient(URI url,
                  ConnectionFactory connectionFactory,
                  ExecutorService executor)

Constructor for connecting to a given URL using a specific connection factory.

Parameters:

url - the Salt API URL

connectionFactory - ConnectionFactory implementation

executor - ExecutorService to be used for async operations

Method Detail

getConfig

public ClientConfig getConfig()

Directly access the configuration.

Returns:

the configuration object

setProxy

public void setProxy(ProxySettings settings)

Configure to use a proxy when connecting to the Salt API.

Parameters:

settings - the proxy settings

login

public Token login(String username,
                   String password,
                   AuthModule eauth)
            throws SaltException

Perform login and return the token.

POST /login

Parameters:

username - the username

password - the password

eauth - the eauth type

Returns:

the authentication token

Throws:

SaltException - if anything goes wrong

loginAsync

public Future<Token> loginAsync(String username,
                                String password,
                                AuthModule eauth)

Asynchronously perform login and return a Future with the token.

POST /login

Parameters:

username - the username

password - the password

eauth - the eauth type

Returns:

Future containing the authentication token

logout

public boolean logout()
               throws SaltException

Perform logout and clear the session token from the config.

POST /logout

Returns:

true if the logout was successful, otherwise false

Throws:

SaltException - if anything goes wrong

logoutAsync

public Future<Boolean> logoutAsync()

Asynchronously perform logout and clear the session token from the config.

POST /logout

Returns:

Future containing a boolean result, true if logout was successful

getMinions

public Map<String,Map<String,Object>> getMinions()
                                          throws SaltException

Query for all minions and immediately return a map of minions keyed by minion id.

GET /minions

Returns:

map containing maps representing minions, keyed by minion id

Throws:

SaltException - if anything goes wrong

See Also:

Grains

getMinionsAsync

public Future<Map<String,Map<String,Object>>> getMinionsAsync()
                                                       throws SaltException

Asynchronously query for all minions and return a map of minions keyed by minion id.

GET /minions

Returns:

Future with a map containing maps representing minions, keyed by minion id

Throws:

SaltException - if anything goes wrong

See Also:

Grains

getMinionDetails

public Map<String,Object> getMinionDetails(String minionId)
                                    throws SaltException

Query for details (grains) of the specified minion.

GET /minions/<minion-id>

Parameters:

minionId - the minion ID

Returns:

Map key: grain name, value: grain value

Throws:

SaltException - if anything goes wrong

See Also:

Grains

getMinionDetailsAsync

public Future<Map<String,Object>> getMinionDetailsAsync(String minionId)
                                                 throws SaltException

Query for details (grains) of the specified minion asynchronously.

GET /minions/<minion-id>

Parameters:

minionId - the minion ID

Returns:

Future with a map containing details of the minion

Throws:

SaltException - if anything goes wrong

See Also:

Grains

startCommand

public <T> ScheduledJob startCommand(Target<T> target,
                                     String function,
                                     List<Object> args,
                                     Map<String,Object> kwargs)
                              throws SaltException

Generic interface to start any execution command and immediately return an object representing the scheduled job.

POST /minions

Type Parameters:

T - type of the tgt property for this command

Parameters:

target - the target

function - the function to execute

args - list of non-keyword arguments

kwargs - map containing keyword arguments

Returns:

object representing the scheduled job

Throws:

SaltException - if anything goes wrong

startCommandAsync

public <T> Future<ScheduledJob> startCommandAsync(Target<T> target,
                                                  String function,
                                                  List<Object> args,
                                                  Map<String,Object> kwargs)

Asynchronously start any execution command and immediately return an object representing the scheduled job.

POST /minions

Type Parameters:

T - type of the tgt property for this command

Parameters:

target - the target

function - the function to execute

args - list of non-keyword arguments

kwargs - map containing keyword arguments

Returns:

Future containing the scheduled job

getJobResult

public ResultInfoSet getJobResult(ScheduledJob job)
                           throws SaltException

Query for the result of a supplied job.

GET /job/<job-id>

Parameters:

job - ScheduledJob object representing scheduled job

Returns:

ResultInfoSet representing result set from minions

Throws:

SaltException - if anything goes wrong

getJobResult

public ResultInfoSet getJobResult(String job)
                           throws SaltException

Query for the result of a supplied job.

GET /job/<job-id>

Parameters:

job - String representing scheduled job

Returns:

ResultInfoSet representing result set from minions

Throws:

SaltException - if anything goes wrong

getJobs

public Map<String,Job> getJobs()
                        throws SaltException

Get previously run jobs.

GET /jobs

Returns:

map containing run jobs keyed by job id

Throws:

SaltException - if anything goes wrong

getJobsAsync

public Future<Map<String,Job>> getJobsAsync()

Asynchronously get previously run jobs.

GET /jobs

Returns:

Future with a map containing run jobs keyed by job id

run

public <T> Map<String,Object> run(String username,
                                  String password,
                                  AuthModule eauth,
                                  String client,
                                  Target<T> target,
                                  String function,
                                  List<Object> args,
                                  Map<String,Object> kwargs)
                           throws SaltException

Generic interface to start any execution command bypassing normal session handling.

POST /run

Type Parameters:

T - type of the tgt property for this command

Parameters:

username - the username

password - the password

eauth - the eauth type

client - the client

target - the target

function - the function to execute

args - list of non-keyword arguments

kwargs - map containing keyword arguments

Returns:

Map key: minion id, value: command result from that minion

Throws:

SaltException - if anything goes wrong

runRawSSHCommand

public <T> Map<String,Result<SSHRawResult>> runRawSSHCommand(String command,
                                                             Target<T> target,
                                                             SaltSSHConfig cfg)
                                                      throws SaltException

Calls salt-ssh with a command in raw shell mode (commands bypass Salt and gets executed as shell commands).

Type Parameters:

T - type of the tgt property for this command

Parameters:

command - to be executed

target - glob type, targets to be reached by the command

cfg - SaltSSH config holder

Returns:

a map in which every key is a host associated to the result of the raw command

Throws:

SaltException

runAsync

public <T> Future<Map<String,Object>> runAsync(String username,
                                               String password,
                                               AuthModule eauth,
                                               String client,
                                               Target<T> target,
                                               String function,
                                               List<Object> args,
                                               Map<String,Object> kwargs)

Asynchronously start any execution command bypassing normal session handling.

POST /run

Type Parameters:

T - type of the tgt property for this command

Parameters:

username - the username

password - the password

eauth - the eauth type

client - the client

target - the target

function - the function to execute

args - list of non-keyword arguments

kwargs - map containing keyword arguments

Returns:

Future containing Map key: minion id, value: command result from that minion

stats

public Stats stats()
            throws SaltException

Query statistics from the CherryPy Server.

GET /stats

Returns:

the stats

Throws:

SaltException - if anything goes wrong

statsAsync

public Future<Stats> statsAsync()

Asynchronously query statistics from the CherryPy Server.

GET /stats

Returns:

Future containing the stats

keys

public Key.Names keys()
               throws SaltException

Query general key information.

Required permissions: @wheel

GET /keys

Returns:

the keys

Throws:

SaltException - if anything goes wrong

keysAsync

public Future<Key.Names> keysAsync()

Asynchronously query general key information.

Required permissions: @wheel

GET /keys

Returns:

Future containing the keys

events

public EventStream events(EventListener... listeners)
                   throws SaltException

Returns a WebSocket @ClientEndpoint annotated object connected to the /ws ServerEndpoint.

The stream object supports the EventStream interface which allows the caller to register/unregister for stream event notifications as well as close the event stream.

Note: login(String, String, AuthModule) or loginAsync(String, String, AuthModule) must be called prior to calling this method.

GET /events

Parameters:

listeners - event listeners to be added before the stream is initialized

Returns:

the event stream

Throws:

SaltException - in case of an error during websocket stream initialization

sendEvent

public boolean sendEvent(String eventTag,
                         String eventData)
                  throws SaltException

Trigger an event in Salt with the specified tag and data.

POST /hook

Parameters:

eventTag - the event tag

eventData - the event data. Must be valid JSON.

Returns:

the boolean value returned by Salt. If true the event was triggered successfully. A value of false is returned only if Salt itself returns false; it does not mean a communication failure.

Throws:

SaltException - if anything goes wrong

sendEventAsync

public Future<Boolean> sendEventAsync(String eventTag,
                                      String eventData)

Asynchronously trigger an event in Salt with the specified tag and data.

POST /hook

Parameters:

eventTag - the event tag

eventData - the event data. Must be valid JSON.

Returns:

Future containing a boolean value indicating the success or failure of triggering the event.

call

public <R> R call(Call<?> call,
                  Client client,
                  String endpoint,
                  Optional<Map<String,Object>> custom,
                  com.google.gson.reflect.TypeToken<R> type)
           throws SaltException

Generic interface to make a Call to an endpoint using a given Client.

Type Parameters:

R - the object type that will be returned

Parameters:

call - the call

client - the client to use

endpoint - the endpoint

custom - map of arguments

type - return type as a TypeToken

Returns:

the result of the call

Throws:

SaltException - if anything goes wrong

call

public <R> R call(Call<?> call,
                  Client client,
                  String endpoint,
                  com.google.gson.reflect.TypeToken<R> type)
           throws SaltException

Convenience method to make a call without arguments.

Type Parameters:

R - the object type that will be returned

Parameters:

call - the call

client - the client to use

endpoint - the endpoint

type - return type as a TypeToken

Returns:

the result of the call

Throws:

SaltException - if anything goes wrong