com.thetransactioncompany.jsonrpc2.server

## Class MessageContext

- java.lang.Object
- - com.thetransactioncompany.jsonrpc2.server.MessageContext

-     public class MessageContext
      extends Object

  Context information about JSON-RPC 2.0 request and notification messages. This class is immutable.
  - The client's host name.
  - The client's IP address.
  - Whether the request / notification was transmitted securely (e.g. via HTTPS).
  - The client principal(s) (user), if authenticated.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `MessageContext.BasicPrincipal` Minimal implementation of the `Principal` interface.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MessageContext()` Creates a new JSON-RPC 2.0 request / notification context.
    `MessageContext(HttpServletRequest httpRequest)` Creates a new JSON-RPC 2.0 request / notification context from the specified HTTP request.
    `MessageContext(String clientHostName, String clientInetAddress)` Creates a new JSON-RPC 2.0 request / notification context.
    `MessageContext(String clientHostName, String clientInetAddress, boolean secure)` Creates a new JSON-RPC 2.0 request / notification context.
    `MessageContext(String clientHostName, String clientInetAddress, boolean secure, String principalName)` Creates a new JSON-RPC 2.0 request / notification context.
    `MessageContext(String clientHostName, String clientInetAddress, boolean secure, String[] principalNames)` Creates a new JSON-RPC 2.0 request / notification context.
    `MessageContext(URLConnection connection)` Creates a new JSON-RPC 2.0 request / notification context from the specified URL connection.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `getClientHostName()` Gets the host name of the client that sent the request / notification.
    `String` | `getClientInetAddress()` Gets the IP address of the client that sent the request / notification.
    `Principal` | `getPrincipal()` Returns the first authenticated client principal, `null` if none.
    `String` | `getPrincipalName()` Returns the first authenticated client principal name, `null` if none.
    `String[]` | `getPrincipalNames()` Returns the authenticated client principal names, `null` if none.
    `Principal[]` | `getPrincipals()` Returns the authenticated client principals, `null` if none.
    `boolean` | `isSecure()` Indicates whether the request / notification was received over a secure HTTPS connection.
    `String` | `toString()`

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

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

- - ### Constructor Detail

    - #### MessageContext

          public MessageContext()

      Creates a new JSON-RPC 2.0 request / notification context. Indicates an insecure transport (plain HTTP) and no authenticated client principal. Not client host name / IP is specified.

    - #### MessageContext

          public MessageContext(HttpServletRequest httpRequest)

      Creates a new JSON-RPC 2.0 request / notification context from the specified HTTP request.
      Parameters:
        `httpRequest` - The HTTP request.

    - #### MessageContext

          public MessageContext(String clientHostName,
                                String clientInetAddress)

      Creates a new JSON-RPC 2.0 request / notification context. Indicates an insecure transport (plain HTTP) and no authenticated client principal.
      Parameters:
        `clientHostName` - The client host name, `null` if unknown.
        `clientInetAddress` - The client IP address, `null` if unknown.

    - #### MessageContext

          public MessageContext(String clientHostName,
                                String clientInetAddress,
                                boolean secure)

      Creates a new JSON-RPC 2.0 request / notification context. No authenticated client principal is specified.
      Parameters:
        `clientHostName` - The client host name, `null` if unknown.
        `clientInetAddress` - The client IP address, `null` if unknown.
        `secure` - Specifies a request received over HTTPS.

    - #### MessageContext

          public MessageContext(String clientHostName,
                                String clientInetAddress,
                                boolean secure,
                                String principalName)

      Creates a new JSON-RPC 2.0 request / notification context.
      Parameters:
        `clientHostName` - The client host name, `null` if unknown.
        `clientInetAddress` - The client IP address, `null` if unknown.
        `secure` - Specifies a request received over HTTPS.
        `principalName` - Specifies the authenticated client principle name, `null` if unknown. The name must not be an empty or blank string.

    - #### MessageContext

          public MessageContext(String clientHostName,
                                String clientInetAddress,
                                boolean secure,
                                String[] principalNames)

      Creates a new JSON-RPC 2.0 request / notification context.
      Parameters:
        `clientHostName` - The client host name, `null` if unknown.
        `clientInetAddress` - The client IP address, `null` if unknown.
        `secure` - Specifies a request received over HTTPS.
        `principalNames` - Specifies the authenticated client principle names, `null` if unknown. The names must not be an empty or blank string.

    - #### MessageContext

          public MessageContext(URLConnection connection)

      Creates a new JSON-RPC 2.0 request / notification context from the specified URL connection. Use this constructor in cases when the HTTP server is the origin of the JSON-RPC 2.0 requests / notifications. If the IP address of the HTTP server cannot be resolved `getClientInetAddress()` will return `null`.
      Parameters:
        `connection` - The URL connection, must be established and not `null`.

  - ### Method Detail

    - #### getClientHostName

          public String getClientHostName()

      Gets the host name of the client that sent the request / notification.
      Returns:
        The client host name, `null` if unknown.

    - #### getClientInetAddress

          public String getClientInetAddress()

      Gets the IP address of the client that sent the request / notification.
      Returns:
        The client IP address, `null` if unknown.

    - #### getPrincipal

          public Principal getPrincipal()

      Returns the first authenticated client principal, `null` if none.
      Returns:
        The first client principal, `null` if none.

    - #### getPrincipalName

          public String getPrincipalName()

      Returns the first authenticated client principal name, `null` if none.
      Returns:
        The first client principal name, `null` if none.

    - #### getPrincipalNames

          public String[] getPrincipalNames()

      Returns the authenticated client principal names, `null` if none.
      Returns:
        The client principal names, `null` if none.

    - #### getPrincipals

          public Principal[] getPrincipals()

      Returns the authenticated client principals, `null` if none.
      Returns:
        The client principals, `null` if none.

    - #### isSecure

          public boolean isSecure()

      Indicates whether the request / notification was received over a secure HTTPS connection.
      Returns:
        `true` If the request was received over HTTPS, `false` if it was received over plain HTTP.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`