aQute.remote.api

Interface Agent

@ProviderType
public interface Agent

An agent runs on remote OSGi framework and provides the means to control this framework. This API can also be used to install a framework before an agent is started. Such a pre-agent is called an Envoy. An Envoy implements createFramework(String, Collection, Map) and isEnvoy() only but switches to the agent API once the framework is installed.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	AGENT_SERVER_PORT_KEY The property key to set the agent's port.
static int	COMMAND_SESSION The port for attaching to a remote Gogo CommandSession
static int	CONSOLE The port for System.in, out, err redirecting.
static int	DEFAULT_PORT The default port.
static int	NONE The port for having no redircet of IO
static java.util.regex.Pattern	PORT_P The pattern for a server port specification: [<interface>:]<port> .

Method Summary

Modifier and Type	Method and Description
void	abort() Abort the remote agent.
boolean	createFramework(java.lang.String name, java.util.Collection<java.lang.String> runpath, java.util.Map<java.lang.String,java.lang.Object> properties) This method is only implemented in the Envoy (the pre-Agent).
java.util.List<org.osgi.framework.wiring.dto.BundleRevisionDTO>	getBundleRevisons(long... bundleId) Get the Bundle Revisions for the given ids.
java.util.List<org.osgi.framework.dto.BundleDTO>	getBundles(long... bundleId) Get the Bundles for the given ids.
org.osgi.framework.dto.FrameworkDTO	getFramework() Get the framework DTO
java.util.Map<java.lang.String,java.lang.String>	getSystemProperties() Get the remote's system's System properties
org.osgi.framework.dto.BundleDTO	install(java.lang.String location, java.lang.String sha) Install a new bundle at the given bundle location.
org.osgi.framework.dto.BundleDTO	installFromURL(java.lang.String location, java.lang.String url) Install a new bundle at the given location using a url to get the stream.
org.osgi.framework.dto.BundleDTO	installWithData(java.lang.String location, byte[] data) Install or update a bundle from the specified byte array instance.
boolean	isEnvoy() An Envoy is an agent that can install a framework (well, -runpath) and launch it with an Agent.
boolean	ping() Ping the remote agent to see if it is still alive.
boolean	redirect(int port) Redirect I/O from port.
java.lang.String	shell(java.lang.String cmd) Execute a remote command on Gogo (if present) and return the result.
java.lang.String	start(long... id) Start a number of bundles
boolean	stdin(java.lang.String s) Send a text to the potentially redirected stdin stream so that remotely executing code will read it from an InputStream.
java.lang.String	stop(long... id) Stop a number of bundles
java.lang.String	uninstall(long... id) Uninstall a number of bundles
java.lang.String	update(long id, java.lang.String sha) Updates a single bundle by id in the framework.
java.lang.String	update(java.util.Map<java.lang.String,java.lang.String> bundles) Update the bundles in the framework.
java.lang.String	updateFromURL(long id, java.lang.String url) Updates a single bundle from a url

Field Detail

DEFAULT_PORT

static final int DEFAULT_PORT

The default port. The port can be overridden with the System/framework property {$value AGENT_SERVER_PORT_KEY.

See Also:

Constant Field Values

AGENT_SERVER_PORT_KEY

static final java.lang.String AGENT_SERVER_PORT_KEY

The property key to set the agent's port.

See Also:

Constant Field Values

PORT_P

static final java.util.regex.Pattern PORT_P

The pattern for a server port specification: [<interface>:]<port> .

COMMAND_SESSION

static final int COMMAND_SESSION

The port for attaching to a remote Gogo CommandSession

See Also:

Constant Field Values

NONE

static final int NONE

The port for having no redircet of IO

See Also:

Constant Field Values

CONSOLE

static final int CONSOLE

The port for System.in, out, err redirecting.

See Also:

Constant Field Values

Method Detail

isEnvoy

boolean isEnvoy()

An Envoy is an agent that can install a framework (well, -runpath) and launch it with an Agent. An envoy can only handle this method and createFramework(String, Collection, Map) so other methods should not be called. This rather awkward model is necessary so that we do not have to reconnect to the actual agent.

Returns:

true if this is a limited envoy, otherwise true for a true Agent.

getBundles

java.util.List<org.osgi.framework.dto.BundleDTO> getBundles(long... bundleId)
                                                     throws java.lang.Exception

Get the Bundles for the given ids. If no ids are given, all bundles are returned.

Throws:

java.lang.Exception

getBundleRevisons

java.util.List<org.osgi.framework.wiring.dto.BundleRevisionDTO> getBundleRevisons(long... bundleId)
                                                                           throws java.lang.Exception

Get the Bundle Revisions for the given ids. If no ids are given, the revisions for all bundles must be returned.

Throws:

java.lang.Exception

getFramework

org.osgi.framework.dto.FrameworkDTO getFramework()
                                          throws java.lang.Exception

Get the framework DTO

Throws:

java.lang.Exception

installWithData

org.osgi.framework.dto.BundleDTO installWithData(java.lang.String location,
                                                 byte[] data)
                                          throws java.lang.Exception

Install or update a bundle from the specified byte array instance.

This method does check if there is any existing bundle with the specified location identifier. If found, the existing bundle gets updated with the specified byte array instance. Otherwise, a new bundle gets installed with the specified byte array instance.

Parameters:

location - The bundle location (cannot be null)

data - The byte array instance from which this bundle will be read (cannot be null)

Returns:

A Bundle DTO (cannot be null)

Throws:

java.lang.Exception - if the bundle cannot be installed or updated

install

org.osgi.framework.dto.BundleDTO install(java.lang.String location,
                                         java.lang.String sha)
                                  throws java.lang.Exception

Install a new bundle at the given bundle location. The SHA identifies the file and should be retrievable through Supervisor.getFile(String) .

Parameters:

location - the bundle location

sha - the sha of the bundle's JAR

Returns:

A Bundle DTO

Throws:

java.lang.Exception

installFromURL

org.osgi.framework.dto.BundleDTO installFromURL(java.lang.String location,
                                                java.lang.String url)
                                         throws java.lang.Exception

Install a new bundle at the given location using a url to get the stream.

NOTICE: this method makes assumptions about the target e.g. that it will be able to use out-of-band communication to read from the URL and have the necessary url handlers to open the URL stream.

Parameters:

location - the bundle location

url - url of the bundle that can retrived using url.openStream()

Returns:

A bundle DTO

Throws:

java.lang.Exception

start

java.lang.String start(long... id)
                throws java.lang.Exception

Start a number of bundles

Parameters:

id - the bundle ids

Returns:

any errors that occurred

Throws:

java.lang.Exception

stop

java.lang.String stop(long... id)
               throws java.lang.Exception

Stop a number of bundles

Parameters:

id - the bundle ids

Returns:

any errors that occurred

Throws:

java.lang.Exception

uninstall

java.lang.String uninstall(long... id)
                    throws java.lang.Exception

Uninstall a number of bundles

Parameters:

id - the bundle ids

Returns:

any errors that occurred

Throws:

java.lang.Exception

update

java.lang.String update(java.util.Map<java.lang.String,java.lang.String> bundles)
                 throws java.lang.Exception

Update the bundles in the framework. Each agent compares this map against a map of installed bundles. The map maps a bundle location to SHA. Any differences are reflected in the installed bundles. That is, a change in the SHA will update, a new entry will install, and a removed entry will uninstall. This is the preferred way to keep the remote framework synchronized since it is idempotent.

Parameters:

bundles - the bundles to update

Throws:

java.lang.Exception

update

java.lang.String update(long id,
                        java.lang.String sha)
                 throws java.lang.Exception

Updates a single bundle by id in the framework. The SHA identifies the file and should be retrievable through Supervisor.getFile(String)

Parameters:

id - the bundle id

sha - the sha of the bundle

Returns:

any errors that occurred

Throws:

java.lang.Exception

updateFromURL

java.lang.String updateFromURL(long id,
                               java.lang.String url)
                        throws java.lang.Exception

Updates a single bundle from a url

NOTICE: this method makes assumptions about the target e.g. that it will be able to use out-of-band communication to read from the URL and have the necessary url handlers to open the URL stream.

Parameters:

id - bundle to update

url - location of bundle contents

Returns:

any errors that occurred

Throws:

java.lang.Exception

redirect

boolean redirect(int port)
          throws java.lang.Exception

Redirect I/O from port. Port can be CONSOLE, COMMAND_SESSION, NONE, or a TCP Telnet port.

Parameters:

port - the port to redirect from

Returns:

if the redirection was changed

Throws:

java.lang.Exception

stdin

boolean stdin(java.lang.String s)
       throws java.lang.Exception

Send a text to the potentially redirected stdin stream so that remotely executing code will read it from an InputStream.

Parameters:

s - text that should be read as input

Returns:

true if this was redirected

Throws:

java.lang.Exception

shell

java.lang.String shell(java.lang.String cmd)
                throws java.lang.Exception

Execute a remote command on Gogo (if present) and return the result.

Parameters:

cmd - the command to execute

Returns:

the result

Throws:

java.lang.Exception

getSystemProperties

java.util.Map<java.lang.String,java.lang.String> getSystemProperties()
                                                              throws java.lang.Exception

Get the remote's system's System properties

Returns:

the remote systems properties

Throws:

java.lang.Exception

createFramework

boolean createFramework(java.lang.String name,
                        java.util.Collection<java.lang.String> runpath,
                        java.util.Map<java.lang.String,java.lang.Object> properties)
                 throws java.lang.Exception

This method is only implemented in the Envoy (the pre-Agent). It is meant to install a -runpath before the framework runs. An Envoy can actally created multiple independent frameworks. If this framework already existed, and the given parameters are identical, that framework will be used for the aget that will take over. Otherwise the current framework is stopped and a new framework is started.

Parameters:

name - the name of the framework

runpath - the runpath the install

properties - the framework properties

Returns:

if this created a new framework

Throws:

java.lang.Exception

abort

void abort()
    throws java.lang.Exception

Abort the remote agent. The agent should send an event back and die. This is an async method.

Throws:

java.lang.Exception

ping

boolean ping()

Ping the remote agent to see if it is still alive.