Package com.xensource.xenapi

Class Connection

java.lang.Object
com.xensource.xenapi.Connection
public class Connection extends Object
Represents a connection to a XenServer. Creating a new instance of this class initialises a new JsonRpcClient that is then used by all method calls: each method call in xen-api takes a Connection as a parameter, composes a JSON-RPC method call, and dispatches it on the Connection's client via the dispatch method.

  • Field Details

  • Constructor Details

    • Connection

      public Connection(JsonRpcClient jsonRpcClient)
      Creates a connection to a particular server using a custom implementation of the JsonRpcClient.

      Note this constructor does NOT call Session.loginWithPassword; the programmer is responsible for calling it, passing the Connection as a parameter. No attempt to connect to the server is made until login is called.

      When this constructor is used, a call to dispose() will do nothing. The programmer is responsible for manually logging out the Session.

      Parameters:
      jsonRpcClient - The JsonRpcClient used to connect to the JSON-RPC backed.

    • Connection

      public Connection(URL url)
      Creates a connection to a particular server using a given url. This object can then be passed in to any other API calls.

      Note this constructor does NOT call Session.loginWithPassword; the programmer is responsible for calling it, passing the Connection as a parameter. No attempt to connect to the server is made until login is called.

      When this constructor is used, a call to dispose() will do nothing. The programmer is responsible for manually logging out the Session.

      This constructor uses the default values of the reply and connection timeouts for the JSON-RPC calls (600 seconds and 5 seconds respectively).

      Parameters:
      url - The URL of the server to connect to. Should be of the form http(s)://host-url/jsonrpc or http(s)://host-url.

    • Connection

      public Connection(URL url, String sessionReference)
      Creates a connection to a particular server using a given url. This object can then be passed in to any other API calls.

      Note this constructor does NOT call Session.loginWithPassword; the programmer is responsible for calling it, passing the Connection as a parameter. No attempt to connect to the server is made until login is called.

      When this constructor is used, a call to dispose() will do nothing. The programmer is responsible for manually logging out the Session.

      This constructor uses the default values of the reply and connection timeouts for the JSON-RPC calls (600 seconds and 5 seconds respectively).

      Parameters:
      url - The URL of the server to connect to. Should be of the form http(s)://host-url/jsonrpc or http(s)://host-url.
      sessionReference - A reference to a logged-in Session. Any method calls on this Connection will use it. This constructor does not call Session.loginWithPassword, and dispose() on the resulting Connection object does not call Session.logout. The programmer is responsible for ensuring the Session is logged in and out correctly.

  • Method Details

    • setRequestTimeout

      public void setRequestTimeout(int requestTimeout) throws NullPointerException
      Set the timeout in seconds for every request made by this object's client. If not set the value defaults to 600. You may also pass your own JsonRpcClient in the constructor for more control.
      Parameters:
      requestTimeout - the timeout value in seconds
      Throws:
      NullPointerException - if the client is null
      See Also:
      • RequestConfig.Builder.setConnectionRequestTimeout(long, TimeUnit)

    • setConnectionTimeout

      public void setConnectionTimeout(int connectionTimeout)
      Set the connection timeout in seconds for its client's PoolingHttpClientConnectionManager. If not set the value defaults to 5. You may also pass your own JsonRpcClient in the constructor for more control.
      Parameters:
      connectionTimeout - the client's connection timeout in seconds.
      Throws:
      NullPointerException - if the client is null
      See Also:
      • ConnectionConfig.Builder.setConnectTimeout(Timeout)

    • getAPIVersion

      public APIVersion getAPIVersion()
      Updated when Session.login_with_password() is called.

    • getSessionReference

      public String getSessionReference()

    • dispatch

      public <T> T dispatch(String methodCall, Object[] methodParameters, com.fasterxml.jackson.core.type.TypeReference<T> responseTypeReference) throws Types.XenAPIException, IOException
      Send a method call to xapi's backend. You need to provide the type of the data returned by a successful response.
      Type Parameters:
      T - The type of the response's payload. For instance, a map of opaque references to VM objects is expected when calling VM.get_all_records
      Parameters:
      methodCall - The JSON-RPC xapi method call. e.g.: session.login_with_password
      methodParameters - The methodParameters of the method call
      responseTypeReference - The type of the response, wrapped with a TypeReference
      Returns:
      The result of the call with the type specified under T.
      Throws:
      Types.XenAPIException - if the call failed.
      IOException - if an I/O error occurs when sending or receiving, includes cases when the request's payload or the response's payload cannot be written or read as valid JSON.

    • dispatch

      public <T> void dispatch(String methodCall, Object[] methodParameters) throws Types.XenAPIException, IOException
      Send a method call to xapi's backend. To be used with methods without a return type
      Parameters:
      methodCall - the JSON-RPC xapi method call. e.g.: session.login_with_password
      methodParameters - the methodParameters of the method call
      Throws:
      Types.XenAPIException - if the call failed.
      IOException - if an I/O error occurs when sending or receiving, includes cases when the request's payload or the response's payload cannot be written or read as valid JSON.