Class Client

java.lang.Object
org.networkupstools.jnut.Client
public class Client extends Object
A jNut client is the starting point to the dialog to UPSD. It can connect to an UPSD then retrieve its device list. It supports authentication by login/password and STARTTLS for security.

You can directly create and connect a client by using the Client(String host, int port, String login, String passwd) constructor, or use a three-phase construction:

  • empty constructor
  • setting host, port, login, and password with setters
  • call empty connect()

Objects retrieved by Client are attached (directly or indirectly) to it. If the connection is closed, attached objects must not be used anymore (GC).

Note: The jNut Client does not support any reconnection nor ping mechanism, so the calling application must know that the UPSD can time out the connection.

Note: Retrieved values are not valid along the time, they are valid at the precise moment they are retrieved.

Author:
Emilien Kia

  • Constructor Details

  • Method Details

    • getHost

      public String getHost()
      Get the host name or address to which the client is (or will be) connected.
      Returns:
      Host name or address.

    • setHost

      public void setHost(String host)
      Set the host name (or address) to which the client will intend to connect to at the next connection.
      Parameters:
      host - New host name or address.

    • getLogin

      public String getLogin()
      Get the login with which the client is (or will be connected).
      Returns:
      The login.

    • setLogin

      public void setLogin(String login)
      Set the login with which the client will intend to connect.
      Parameters:
      login - New login.

    • getPasswd

      public String getPasswd()
      Get the password with which the client is (or will be connected).
      Returns:
      The password.

    • setPasswd

      public void setPasswd(String passwd)
      Set the password with which the client will intend to connect.
      Parameters:
      passwd - New password.

    • getPort

      public int getPort()
      Get the port to which the client is (or will be) connected.
      Returns:
      Port number.

    • setPort

      public void setPort(int port)
      Set the port to which the client is (or will be) connected.
      Parameters:
      port - Port number.

    • getSslConfig

      public SSLConfig getSslConfig()

    • setSslConfig

      public void setSslConfig(SSLConfig sslConfig)
      Set the SSL configuration for the client; should do so before calling connect(String, int, String, String).
      Parameters:
      sslConfig - SSL configuration object.
      See Also:

    • isTrackingEnabled

      public boolean isTrackingEnabled()
      Get the tracking activation status.
      Returns:
      Tracking activation status.

    • setTracking

      public void setTracking(boolean tracking) throws IOException, NutException
      Set the tracking activation status; requires that the client connection is already active (call this after connect(String, int, String, String) succeeds).
      Parameters:
      tracking - New tracking activation status.
      Throws:
      IOException
      NutException

    • getLastTrackingId

      public TrackingID getLastTrackingId()
      Get the tracking ID for last SET or INSTCMD.
      Returns:
      Tracking ID.

    • connect

      public void connect(String host, int port, String login, String passwd) throws IOException, UnknownHostException, NutException
      Intent to connect and authenticate to an UPSD with specified parameters (remembers them as class instance fields).

      Throw an exception if we cannot connect.

      Parameters:
      host - Host to which connect.
      port - IP port.
      login - Login to use to connect to UPSD.
      passwd - Password to use to connect to UPSD.
      Throws:
      IOException
      UnknownHostException
      NutException

    • connect

      public void connect(String host, int port) throws IOException, UnknownHostException, NutException
      Intent to connect to an UPSD with specified parameters (remembers them as class instance fields) without authentication.

      Throw an exception if we cannot connect.

      Parameters:
      host - Host to which connect.
      port - IP port.
      Throws:
      IOException
      UnknownHostException
      NutException

    • connect

      public void connect() throws IOException, UnknownHostException, NutException
      Connection to UPSD with already specified parameters (including a call to authenticate(String, String) if so configured). Throw an exception if we cannot connect.
      Throws:
      IOException
      UnknownHostException
      NutException

    • authenticate

      public void authenticate(String login, String passwd) throws IOException, NutException
      Intend to authenticate with a specified login and password, overriding already defined ones (remembers them as class instance fields).

      NOTE: This is an operation different from Device.login() which lets a program like upsmon assume a special role on a specific device.

      Parameters:
      login -
      passwd -
      Throws:
      IOException
      NutException

    • authenticate

      public void authenticate() throws IOException, NutException
      Intend to authenticate with an already set login and password.

      NOTE: This is an operation different from Device.login() which lets a program like upsmon assume a special role on a specific device.

      Throws:
      IOException
      NutException

    • isConnected

      public boolean isConnected()
      Test if the client is connected to the UPSD. Note: it does not actively probe to detect if the connection has been closed by the server -- just reports if we had opened it or not.
      Returns:
      True if connected.
      See Also:

    • disconnect

      public void disconnect()
      Disconnect.

    • logout

      public void logout()
      Log out.

    • query

      protected String query(String query, String subquery) throws IOException, NutException
      Send a query line, then read the response. Helper around query(String).
      Parameters:
      query - Query to send.
      subquery - Sub query to send.
      Returns:
      The reply.
      Throws:
      IOException
      NutException

    • query

      protected String query(String query, String subquery, String[] params) throws IOException, NutException
      Send a query line, then read the response. Helper around query(String, String...).
      Parameters:
      query - Query to send.
      subquery - Sub query to send.
      params - Optional additional parameters.
      Returns:
      The reply.
      Throws:
      IOException
      NutException

    • query

      protected String query(String query, String[] params) throws IOException, NutException
      Send a query line, then read the response.
      Parameters:
      query - Query to send.
      params - Optional additional parameters.
      Returns:
      The reply.
      Throws:
      IOException
      NutException

    • query

      protected String query(String query) throws IOException, NutException
      Send a query line, then read the response.
      Parameters:
      query - Query to send.
      Returns:
      The reply.
      Throws:
      IOException
      NutException

    • get

      protected String get(String subcmd, String param) throws IOException, NutException
      Send a GET query line, then read the reply and validate the response.
      Parameters:
      subcmd - GET subcommand to send.
      param - Extra parameters
      Returns:
      GET result return by UPSD, without the subcommand and param prefix.
      Throws:
      IOException
      NutException

    • get

      protected String get(String subcmd, String[] params) throws IOException, NutException
      Send a GET query line, then read the reply and validate the response.
      Parameters:
      subcmd - GET subcommand to send.
      params - Eventual extra parameters.
      Returns:
      GET result return by UPSD, without the subcommand and param prefix.
      Throws:
      IOException
      NutException

    • list

      protected String[] list(String subcmd) throws IOException, NutException
      Send a LIST query line, then read replies and validate them.
      Parameters:
      subcmd - LIST subcommand to send.
      Returns:
      LIST results return by UPSD, without the subcommand and param prefix.
      Throws:
      IOException
      NutException

    • list

      protected String[] list(String subcmd, String param) throws IOException, NutException
      Send a LIST query line, then read replies and validate them.
      Parameters:
      subcmd - LIST subcommand to send.
      param - Extra parameters.
      Returns:
      LIST results return by UPSD, without the subcommand and param prefix.
      Throws:
      IOException
      NutException

    • list

      protected String[] list(String subcmd, String[] params) throws IOException, NutException
      Send a LIST query line, then read replies and validate them.
      Parameters:
      subcmd - LIST subcommand to send.
      params - Eventual extra parameters.
      Returns:
      LIST results return by UPSD, without the subcommand and param prefix.
      Throws:
      IOException
      NutException

    • enableTrackingModeOnce

      public boolean enableTrackingModeOnce() throws IOException, NutException
      Enable TRACKING mode on this connection if it is not already enabled.
      Returns:
      True if tracking is enabled.
      Throws:
      IOException
      NutException

    • getTrackingResult

      public String getTrackingResult(TrackingID id) throws IOException, NutException
      Throws:
      IOException
      NutException

    • waitTrackingResult

      public boolean waitTrackingResult(TrackingID id, int waitIntervalSec, int waitMaxCount) throws IOException, NutException
      Wait for a tracking ID to complete.
      Parameters:
      id - Tracking ID to wait for.
      waitIntervalSec - Interval between checks in seconds.
      waitMaxCount - Maximum number of checks.
      Returns:
      True if the command succeeded, false if timed out or failed.
      Throws:
      IOException
      NutException

    • getDeviceList

      public Device[] getDeviceList() throws IOException, NutException
      Returns the list of available devices from the NUT server.
      Returns:
      List of devices, empty if nothing, null if not connected or failed.
      Throws:
      IOException
      NutException

    • getDevice

      public Device getDevice(String name) throws IOException, NutException
      Intend to retrieve a device by its name.
      Parameters:
      name - Name of the device to look at.
      Returns:
      Device
      Throws:
      IOException
      NutException