Package 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
    Description
    static final String
    AGENT_SERVER_PORT_KEY
    The property key to set the agent's port.
    static final int
    COMMAND_SESSION
    The port for attaching to a remote Gogo CommandSession
    static final int
    CONSOLE
    The port for System.in, out, err redirecting.
    static final int
    DEFAULT_PORT
    The default port.
    static final int
    NONE
    The port for having no redircet of IO
    static final Pattern
    PORT_P
    The pattern for a server port specification: [<interface>:]<port> .

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    abort()
    Abort the remote agent.
    boolean
    createFramework(String name, Collection<String> runpath, Map<String,Object> properties)
    This method is only implemented in the Envoy (the pre-Agent).
    List<org.osgi.framework.wiring.dto.BundleRevisionDTO>
    getBundleRevisons(long... bundleId)
    Get the Bundle Revisions for the given ids.
    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
    Map<String,String>
    getSystemProperties()
    Get the remote's system's System properties
    org.osgi.framework.dto.BundleDTO
    install(String location, String sha)
    Install a new bundle at the given bundle location.
    org.osgi.framework.dto.BundleDTO
    installFromURL(String location, String url)
    Install a new bundle at the given location using a url to get the stream.
    org.osgi.framework.dto.BundleDTO
    installWithData(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.
    String
    shell(String cmd)
    Execute a remote command on Gogo (if present) and return the result.
    String
    start(long... id)
    Start a number of bundles
    boolean
    stdin(String s)
    Send a text to the potentially redirected stdin stream so that remotely executing code will read it from an InputStream.
    String
    stop(long... id)
    Stop a number of bundles
    String
    uninstall(long... id)
    Uninstall a number of bundles
    String
    update(long id, String sha)
    Updates a single bundle by id in the framework.
    String
    update(Map<String,String> bundles)
    Update the bundles in the framework.
    String
    updateFromURL(long id, String url)
    Updates a single bundle from a url

  • Field Details

    • 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:

    • AGENT_SERVER_PORT_KEY

      static final String AGENT_SERVER_PORT_KEY
      The property key to set the agent's port.
      See Also:

    • PORT_P

      static final 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:

    • NONE

      static final int NONE
      The port for having no redircet of IO
      See Also:

    • CONSOLE

      static final int CONSOLE
      The port for System.in, out, err redirecting.
      See Also:

  • Method Details

    • 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

      List<org.osgi.framework.dto.BundleDTO> getBundles(long... bundleId) throws Exception
      Get the Bundles for the given ids. If no ids are given, all bundles are returned.
      Throws:
      Exception

    • getBundleRevisons

      List<org.osgi.framework.wiring.dto.BundleRevisionDTO> getBundleRevisons(long... bundleId) throws Exception
      Get the Bundle Revisions for the given ids. If no ids are given, the revisions for all bundles must be returned.
      Throws:
      Exception

    • getFramework

      org.osgi.framework.dto.FrameworkDTO getFramework() throws Exception
      Get the framework DTO
      Throws:
      Exception

    • installWithData

      org.osgi.framework.dto.BundleDTO installWithData(String location, byte[] data) throws 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:
      Exception - if the bundle cannot be installed or updated

    • install

      org.osgi.framework.dto.BundleDTO install(String location, String sha) throws 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:
      Exception

    • installFromURL

      org.osgi.framework.dto.BundleDTO installFromURL(String location, String url) throws 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:
      Exception

    • start

      String start(long... id) throws Exception
      Start a number of bundles
      Parameters:
      id - the bundle ids
      Returns:
      any errors that occurred
      Throws:
      Exception

    • stop

      String stop(long... id) throws Exception
      Stop a number of bundles
      Parameters:
      id - the bundle ids
      Returns:
      any errors that occurred
      Throws:
      Exception

    • uninstall

      String uninstall(long... id) throws Exception
      Uninstall a number of bundles
      Parameters:
      id - the bundle ids
      Returns:
      any errors that occurred
      Throws:
      Exception

    • update

      String update(Map<String,String> bundles) throws 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:
      Exception

    • update

      String update(long id, String sha) throws 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:
      Exception

    • updateFromURL

      String updateFromURL(long id, String url) throws 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:
      Exception

    • redirect

      boolean redirect(int port) throws 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:
      Exception

    • stdin

      boolean stdin(String s) throws 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:
      Exception

    • shell

      String shell(String cmd) throws Exception
      Execute a remote command on Gogo (if present) and return the result.
      Parameters:
      cmd - the command to execute
      Returns:
      the result
      Throws:
      Exception

    • getSystemProperties

      Map<String,String> getSystemProperties() throws Exception
      Get the remote's system's System properties
      Returns:
      the remote systems properties
      Throws:
      Exception

    • createFramework

      boolean createFramework(String name, Collection<String> runpath, Map<String,Object> properties) throws 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:
      Exception

    • abort

      void abort() throws Exception
      Abort the remote agent. The agent should send an event back and die. This is an async method.
      Throws:
      Exception

    • ping

      boolean ping()
      Ping the remote agent to see if it is still alive.