com.mathworks.mps.client

## Class MWHttpClient

- java.lang.Object
- - com.mathworks.mps.client.MWHttpClient

- All Implemented Interfaces:
    MWClient

      public class MWHttpClient
      extends java.lang.Object
      implements MWClient

  Establishes an HTTP/HTTPS based connection between a Java client and MATLAB Production Server. `MWHttpClient` allows Java clients to invoke MATLAB functions exported by a CTF file hosted by the server. The CTF is specified by a URL. A server can host multiple CTF's and each CTF has a unique URL.

  To establish client-server communication, following information is required:

  - URL to the CTF file of the form: `http://server_name:port_number/CTF_name_without_extension`
  - Names of MATLAB functions exported by this CTF
  - Information about the number of inputs and outputs for each MATLAB function and their types
  - Optionally, a user written Java interface written using some of the above information:
    - Public methods with same names as those of the MATLAB functions exported by the CTF
    - Public methods of this interface must be consistent with MATLAB functions in terms of the numbers of inputs and outputs and their types
    - Each method in this interface has to declare following checked exceptions:
      - `com.mathworks.mps.client.MATLABException` : Represents MATLAB errors
      - `java.io.IOException` : Represents any transport errors during client-server communication
    - There can be overloads of a method in the interface depending on the MATLAB function that the Java method is representing
    - Name of this JAVA interface does not have to be same as the CTF

  `MWHttpClient` can be configured by providing an object that extends the `MWHttpClientDefaultConfig` utility class to change its properties. `MWHttpClientDefaultConfig` has the following properties:

  - `Interruptible` : Determines if the MATLAB function call can be interupted while waiting for a response. The default is `false` .
  - `TimeOutMs` : Specifies the time in mS that the client waits for the response from the server. The default is 120000 mS.
  - `MaxConnectionsPerAddress` : Specifies the maximum number of connections per address used by `MWHttpClient` to fulfill multiple simultaneous requests created by client. The default is -1.
  - `ResponseSizeLimit` : Specifies the maximum size, in bytes, of the response the client will accept. The default is 64*1024*1024.

  `MWHttpClient` security configuration can be modified by providing an object that extends the `MWSSLDefaultConfig` utility class to change its properties.

  ## A Quick Example

  Here's a quick example that demonstrates the use of `MWHttpClient` class when both client and server are hosted on the same machine.

  Let's consider a simple MATLAB function `mymagic` that returns a magic square:

         function m = mymagic(in)
         m = magic(in);

  - `mymagic` takes an int as input and returns a 2-D double array

  Let's assume that MATLAB function `mymagic` is compiled into `magiccomponent.ctf` and this CTF is hosted by the server at URL: `http://localhost:8990/magiccomponent`

  The Java interface `Magic` shown below represents `magiccomponent.ctf` on the client side:

       interface Magic {
           double[][] mymagic(int in1) throws IOException, MATLABException;
       }

  This is how `MWHttpClient` uses the `Magic` interface and the URL to invoke `mymagic` MATLAB function:

       import com.mathworks.mps.client.MWClient;
       import com.mathworks.mps.client.MWHttpClient;
       import com.mathworks.mps.client.MATLABException;
       import java.net.URL;

       public class ClientExample {

           public static void main(String[] args) {

               MWClient client = new MWHttpClient();
               try {
                   Magic m =
                           client.createProxy(new URL("http://localhost:8990/magiccomponent"), Magic.class);
                   double[][] result = m.mymagic(5);
               } catch (IOException ex) {
                   ex.printStackTrace();
               } catch (MATLABException ex) {
                   ex.printMATLABStackTrace();
               } finally {
                   client.close();
               }
           }
       }

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static com.mathworks.mps.client.internal.MWLoggerFactory` | `loggerFactory`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MWHttpClient()` Create an `MWHttpClient` instance with an instance of `MWHttpClientDefaultConfig` to configure the client-server connection and an instance of `MWSSLDefaultConfig` to configure secure socket connection over `HTTPS`.
    `MWHttpClient(MWHttpClientConfig config)` Create an `MWHttpClient` instance with a user provided configuration.
    `MWHttpClient(MWHttpClientConfig config, MWSSLConfig sslConfig)` Create an `MWHttpClient` instance with user provided configurations for both the client-server connection and the SSL layer.
    `MWHttpClient(MWSSLConfig sslConfig)` Create an `MWHttpClient` instance with a user user provided configuration for the secure socket communication.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes the client-server communication.
    `MWInvokable` | `createComponentProxy(java.net.URL url)` Creates a reflection-based proxy object reference to a deployable archive hosted by MATLAB Production Server.
    `MWInvokable` | `createComponentProxy(java.net.URL url, MWMarshalingRules marshalingRules)` Creates a reflection-based proxy object reference to a deployable archive hosted by MATLAB Production Server.
    `<T> T` | `createProxy(java.net.URL url, java.lang.Class<T> mwComponent)` Creates an interface-based proxy object reference to a deployable archive hosted by the server.
    `java.util.UUID` | `getClientUUID()` Returns the client's universally unique identifier (UUID).
    `MWHttpClientConfig` | `getConfig()` Returns a reference to the connection configuration associated with this instance of `MWHttpClient`.
    `java.lang.String` | `getID()` Get unique identifier for this client instance
    `MWSSLConfig` | `getSSLConfig()` Returns a reference to the SSL configuration associated with this instance of `MWHttpClient`.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### loggerFactory

          public static com.mathworks.mps.client.internal.MWLoggerFactory loggerFactory

  - ### Constructor Detail

    - #### MWHttpClient

          public MWHttpClient()

      Create an `MWHttpClient` instance with an instance of `MWHttpClientDefaultConfig` to configure the client-server connection and an instance of `MWSSLDefaultConfig` to configure secure socket connection over `HTTPS`.

    - #### MWHttpClient

          public MWHttpClient(MWHttpClientConfig config)

      Create an `MWHttpClient` instance with a user provided configuration. It uses an instance of `MWSSLDefaultConfig` to configure secure socket connection.
      Parameters:
        `config` - user extended instance of `MWHttpClientDefaultConfig`
      See Also:
        `MWHttpClientDefaultConfig`

    - #### MWHttpClient

          public MWHttpClient(MWSSLConfig sslConfig)

      Create an `MWHttpClient` instance with a user user provided configuration for the secure socket communication. It uses an instance of `MWHttpClientDefaultConfig` to configure the client-server connection.
      Parameters:
        `sslConfig` - user extended instance of `MWSSLDefaultConfig`
      See Also:
        `MWSSLDefaultConfig`

    - #### MWHttpClient

          public MWHttpClient(MWHttpClientConfig config,
                              MWSSLConfig sslConfig)

      Create an `MWHttpClient` instance with user provided configurations for both the client-server connection and the SSL layer.
      Parameters:
        `config` - user extended instance of `MWHttpClientDefaultConfig`
        `sslConfig` - user extended instance of `MWSSLDefaultConfig`
      See Also:
        `MWHttpClientDefaultConfig`, `MWSSLDefaultConfig`

  - ### Method Detail

    - #### getConfig

          public MWHttpClientConfig getConfig()

      Returns a reference to the connection configuration associated with this instance of `MWHttpClient`.
      Returns:
        `MWHttpClientConfig` instance associated with this instance of `MWHttpClient`

    - #### getSSLConfig

          public MWSSLConfig getSSLConfig()

      Returns a reference to the SSL configuration associated with this instance of `MWHttpClient`.
      Returns:
        `MWSSLConfig` instance associated with this instance of `MWHttpClient`

    - #### getClientUUID

          public java.util.UUID getClientUUID()

      Returns the client's universally unique identifier (UUID).
      Returns:
        Client UUID

    - #### createProxy

          public <T> T createProxy(java.net.URL url,
                                   java.lang.Class<T> mwComponent)

      Creates an interface-based proxy object reference to a deployable archive hosted by the server. The deployable archive is identified by a URL. The type of this proxy object is determined by the second input `mwComponent`. The proxy object has public methods of the interface defined by `mwComponent`. This interface has methods with names of MATLAB functions in the deployable archive and with inputs and outputs consistent with MATLAB functions in terms of types and numbers. When a method is invoked, the proxy object establishes a client-server connection over HTTP. The HTTP request carries the inputs for the MATLAB function and the response carries the MATLAB result.
      Specified by:
        `createProxy` in interface `MWClient`
      Type Parameters:
        `T` - The type of the returned object
      Parameters:
        `url` - url to the deployable archive with the form: `http://<server_name>:<port_number>/<archive_name>`
        `mwComponent` - Reference to interface modeled after the deployable archive pointed by the URL
      Returns:
        An object of type <T>

    - #### createComponentProxy

          public MWInvokable createComponentProxy(java.net.URL url,
                                                  MWMarshalingRules marshalingRules)

      Creates a reflection-based proxy object reference to a deployable archive hosted by MATLAB Production Server. The deployable archive is identified by a URL. The proxy object has an `invoke` method to call MATLAB functions contained in the specified deployable archive.
      Specified by:
        `createComponentProxy` in interface `MWClient`
      Parameters:
        `url` - url to the deployable archive with the form: `http://<server_name>:<port_number>/<archive_name>`
        `marshalingRules` - List of java classes, used as input or output argument to the MATLAB function, that represent a MATALB struct
      Returns:
        A reference to the `MWInvocable` interface that provides methods to invoke MATLAB functions directly

    - #### createComponentProxy

          public MWInvokable createComponentProxy(java.net.URL url)

      Creates a reflection-based proxy object reference to a deployable archive hosted by MATLAB Production Server. The deployable archive is identified by a URL. The proxy object has an `invoke` method to call MATLAB functions contained in the specified deployable archive.
      Specified by:
        `createComponentProxy` in interface `MWClient`
      Parameters:
        `url` - url to the deployable archive with the form: `http://<server_name>:<port_number>/<archive_name>`
      Returns:
        A reference to the `MWInvocable` interface that provides methods to invoke MATLAB functions directly

    - #### close

          public void close()

      Closes the client-server communication. Once closed, an instance of `MWHttpClient` cannot be restarted. It should not be used to create new deployable archive references and the existing deployable archive references created using this instance of `MWHttpClient` are unusable.
      Specified by:
        `close` in interface `MWClient`

    - #### getID

          public java.lang.String getID()

      Description copied from interface: `MWClient`
      Get unique identifier for this client instance
      Specified by:
        `getID` in interface `MWClient`
      Returns:
        String representing the unique identifier for this instance of the client

Copyright 2010-2022 The MathWorks, Inc.