Package org.zkoss.zk.device

## Class Devices

- java.lang.Object
- - org.zkoss.zk.device.Devices

-     public class Devices
      extends java.lang.Object

  A manager of devices (`Device`).
  Since:
    2.4.0
  Author:
    tomyeh

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.lang.String` | `add​(java.lang.String deviceType, java.lang.Class cls)` | Adds a device type.
    `static java.lang.String` | `add​(java.lang.String deviceType, java.lang.String clsnm)` | Adds a device type.
    `static void` | `add​(Element config)` | Adds a device based on the XML declaration.
    `static void` | `addEmbedded​(java.lang.String deviceType, java.lang.String content)` | Adds the content that shall be added to the output generated and sent to the client, when rending a desktop.
    `static boolean` | `exists​(java.lang.String deviceType)` | Tests whether the device for the specified type exists.
    `static Device` | `getDevice​(java.lang.String deviceType)` | Returns the device for the specified desktop type.
    `static Device` | `getDeviceByClient​(java.lang.String userAgent)` | Returns the device for the specified client.
    `java.lang.String` | `getEmbedded​(java.lang.String deviceType)` | Returns the content that shall be embedded to the output being generated to the client, or null if no embedded content.
    `static java.lang.String` | `getServerPushClass​(java.lang.String deviceType)` | Returns the class name that implements the server push feature.
    `static java.lang.String` | `getUnavailableMessage​(java.lang.String deviceType)` | Returns the unavailable message for the specified device type.
    `static java.lang.String` | `loadFileContentAsString​(Execution exec, java.lang.String path)` | Loads the content of a file as a String.
    `static java.lang.String` | `loadJavaScript​(Execution exec, java.lang.String path)` | Loads the content of a javascript file as a String.
    `static java.lang.Object[]` | `matches​(java.lang.String userAgent)` | Returns the name and version of the client if the given user agent matches any of the devices, or null if not matched or it is a standard browser request.
    `static java.lang.String` | `setServerPushClass​(java.lang.String deviceType, java.lang.Class cls)` | Sets the class that implements the server-push feature.
    `static java.lang.String` | `setServerPushClass​(java.lang.String deviceType, java.lang.String clsnm)` | Sets the name of the class that implements the server-push feature.
    `static java.lang.String` | `setUnavailableMessage​(java.lang.String deviceType, java.lang.String msg)` | Sets the unavailable message for the specified device type.

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

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

- - ### Method Detail

    - #### getDevice

          public static final Device getDevice​(java.lang.String deviceType)
                                        throws DeviceNotFoundException

      Returns the device for the specified desktop type.
      Parameters:
        `deviceType` - the device type, such as ajax, xml and mil.
      Throws:
        `DeviceNotFoundException` - if not found.
      Since:
        3.0.0

    - #### getDeviceByClient

          public static final Device getDeviceByClient​(java.lang.String userAgent)
                                                throws DeviceNotFoundException

      Returns the device for the specified client. It invokes `Device.isCompatible(java.lang.String)` to return the correct device. If all devices returns null (means unknown), one of the devices returning null is returned. If all devices returns Boolean.FALSE, DeviceNotFoundException is thrown.
      Parameters:
        `userAgent` - represents a client. It is the user-agent header for HTTP-base client.
      Throws:
        `DeviceNotFoundException` - if not found.
      Since:
        3.0.0
      See Also:
        `Execution.getUserAgent()`

    - #### exists

          public static final boolean exists​(java.lang.String deviceType)

      Tests whether the device for the specified type exists.
      Parameters:
        `deviceType` - the device type, say, ajax.
      Since:
        2.4.0

    - #### add

          public static final void add​(Element config)

      Adds a device based on the XML declaration.

                  <device-config>
                  <device-type>superajax</device-type>
                  <device-class>my.MyDevice</device-class>
                  <unavailable-message>error message</unavailable-message>
                  <server-push-class>my.MyServerPush</server-push-class>
                  </device-config>

      Parameters:
        `config` - the XML element called zscript-config

    - #### add

          public static final java.lang.String add​(java.lang.String deviceType,
                                                   java.lang.String clsnm)

      Adds a device type.
      Parameters:
        `deviceType` - the device type (a.k.a., the device name).
        `clsnm` - the device class name
      Returns:
        the previous class of the device with the same type, if any, or null if no such device.

    - #### add

          public static final java.lang.String add​(java.lang.String deviceType,
                                                   java.lang.Class cls)

      Adds a device type.
      Parameters:
        `deviceType` - the device type (a.k.a., the device name).
        `cls` - the device class
      Returns:
        the previous class of the device with the same type, if any, or null if no such device.
      Since:
        3.0.0

    - #### getUnavailableMessage

          public static final java.lang.String getUnavailableMessage​(java.lang.String deviceType)

      Returns the unavailable message for the specified device type.

      The result is the same as the invocation of `Device.getUnavailableMessage()` against `getDevice(java.lang.String)`, but this method will not load the device if it is not loaded yet.

      See Also:
        `Device`, `Device.getUnavailableMessage()`

    - #### setUnavailableMessage

          public static final java.lang.String setUnavailableMessage​(java.lang.String deviceType,
                                                                     java.lang.String msg)

      Sets the unavailable message for the specified device type.
      Returns:
        the previous unavailable message if any.
      See Also:
        `Device`, `Device.setUnavailableMessage(java.lang.String)`

    - #### getEmbedded

          public java.lang.String getEmbedded​(java.lang.String deviceType)

      Returns the content that shall be embedded to the output being generated to the client, or null if no embedded content.
      Since:
        3.0.6

    - #### addEmbedded

          public static void addEmbedded​(java.lang.String deviceType,
                                         java.lang.String content)

      Adds the content that shall be added to the output generated and sent to the client, when rending a desktop. What content can be embedded depends on the device. For Ajax devices, it can be anything that can be placed inside HTML HEAD, such as JavaScript codes.

      As the method name suggests, the embedded contents are accumulated and all generated to the output.

      Since:
        3.0.6

    - #### getServerPushClass

          public static final java.lang.String getServerPushClass​(java.lang.String deviceType)

      Returns the class name that implements the server push feature.

      Default: null (the server-push feature is not available).

      The result is the same as the invocation of `Device.getServerPushClass()` against `getDevice(java.lang.String)`, but this method will not load the device if it is not loaded yet.

      Since:
        3.0.0

    - #### setServerPushClass

          public static final java.lang.String setServerPushClass​(java.lang.String deviceType,
                                                                  java.lang.String clsnm)

      Sets the name of the class that implements the server-push feature.
      Parameters:
        `clsnm` - the class name that implements the server push. If null, it means no server push is available.
      Returns:
        the previous class name, or null if not available.
      Since:
        3.0.0

    - #### setServerPushClass

          public static final java.lang.String setServerPushClass​(java.lang.String deviceType,
                                                                  java.lang.Class cls)

      Sets the class that implements the server-push feature.
      Parameters:
        `cls` - the class that implements the server push. If null, it means no server push is available.
      Returns:
        the previous class name, or null if not available.
      Since:
        3.0.0

    - #### matches

          public static final java.lang.Object[] matches​(java.lang.String userAgent)

      Returns the name and version of the client if the given user agent matches any of the devices, or null if not matched or it is a standard browser request.

      It iterates all devices and invokes `Device.matches(java.lang.String)` one-by-one, then returns the first non-null return, if any.

      Parameters:
        `userAgent` - represents a client (i.e., HTTP's user-agent).
      Returns:
        a pair of objects or null. The first element of the pair is the name of the client (String), the second element is the version (Double, such as 3.5).
      Since:
        6.0.0

    - #### loadJavaScript

          public static java.lang.String loadJavaScript​(Execution exec,
                                                        java.lang.String path)
                                                 throws java.io.IOException

      Loads the content of a javascript file as a String.
      Throws:
        `java.io.IOException`
      Since:
        5.0.11

    - #### loadFileContentAsString

          public static java.lang.String loadFileContentAsString​(Execution exec,
                                                                 java.lang.String path)
                                                          throws java.io.IOException

      Loads the content of a file as a String.
      Throws:
        `java.io.IOException`
      Since:
        8.5.1