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 Summary

    Fields
    Modifier and Type
    Field
    Description
     
  • Constructor Summary

    Constructors
    Constructor
    Description
    Connection(JsonRpcClient jsonRpcClient)
    Creates a connection to a particular server using a custom implementation of the JsonRpcClient.
    Creates a connection to a particular server using a given url.
    Connection(URL url, int requestTimeout, int connectionTimeout)
    Deprecated.
    This constructor is deprecated.
    Connection(URL url, String sessionReference)
    Creates a connection to a particular server using a given url.
    Connection(URL url, String sessionReference, int requestTimeout, int connectionTimeout)
    Deprecated.
    This constructor is deprecated.
    Connection(org.apache.hc.client5.http.impl.classic.CloseableHttpClient httpClient, URL url, int requestTimeout)
    Deprecated.
    This constructor is deprecated.
  • Method Summary

    Modifier and Type
    Method
    Description
    <T> void
    dispatch(String methodCall, Object[] methodParameters)
    Send a method call to xapi's backend.
    <T> T
    dispatch(String methodCall, Object[] methodParameters, com.fasterxml.jackson.core.type.TypeReference<T> responseTypeReference)
    Send a method call to xapi's backend.
    Updated when Session.login_with_password() is called.
     
    void
    setConnectionTimeout(int connectionTimeout)
    Set the connection timeout in seconds for its client's PoolingHttpClientConnectionManager.
    void
    setRequestTimeout(int requestTimeout)
    Set the timeout in seconds for every request made by this object's client.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • 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

      @Deprecated public Connection(org.apache.hc.client5.http.impl.classic.CloseableHttpClient httpClient, URL url, int requestTimeout)
      Deprecated.
      This constructor is deprecated. To set the requestTimeout please setRequestTimeout(int). You may also use the JsonRpcClient.setRequestTimeout(int) method of this object's client. This option is only advisable if you are managing your own JsonRpcClient as the underlying client for this object.
      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.

      Parameters:
      httpClient - The HttpClient used to make calls, this will be used by the underlying client for handling requests
      url - The URL of the server to connect to. Should be of the form http(s)://host-url/jsonrpc or http(s)://host-url.
      requestTimeout - The reply timeout for JSON-RPC calls in seconds
    • 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

      @Deprecated public Connection(URL url, int requestTimeout, int connectionTimeout)
      Deprecated.
      This constructor is deprecated. To set requestTimeout or connectionTimeout please use setRequestTimeout(int) or setConnectionTimeout(int) respectively. You may also use the JsonRpcClient.setRequestTimeout(int) method of this object's client. This option is only advisable if you are managing your own JsonRpcClient as the underlying client for this object.
      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.

      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.
      requestTimeout - The reply timeout for JSON-RPC calls in seconds
      connectionTimeout - The connection timeout for JSON-RPC calls in seconds
    • 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.
    • Connection

      @Deprecated public Connection(URL url, String sessionReference, int requestTimeout, int connectionTimeout)
      Deprecated.
      This constructor is deprecated. To set requestTimeout or connectionTimeout please use setRequestTimeout(int) or setConnectionTimeout(int) respectively. You may also use the JsonRpcClient.setRequestTimeout(int) method of this object's client. This option is only advisable if you are managing your own JsonRpcClient as the underlying client for this object.
      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.

      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.
      requestTimeout - The reply timeout for JSON-RPC calls in seconds
      connectionTimeout - The connection timeout for JSON-RPC calls in seconds
  • 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.