Package uk.ac.starlink.vo

## Class UserAgentUtil

- java.lang.Object
- - uk.ac.starlink.vo.UserAgentUtil

-     public class UserAgentUtil
      extends java.lang.Object

  Utilities for manipulating the HTTP `User-Agent` header from the JVM, following IVOA usage conventions. At time of writing, these conventions are sketched in the UserAgentUsage page on the IVOA wiki; they may be amended and/or written up more formally in the future.

  Typical usage would be:

         String uaComment = UserAgentUtil.COMMENT_VALIDATE;   // "(IVOA-validate)"
         UserAgentUtil.pushUserAgentToken( uaComment );
         ... do validation ...
         UserAgentUtil.popUserAgentToken( uaComment );

  Since:
    12 Apr 2019
  Author:
    Mark Taylor
  See Also:
    RFC 2616 sec 14.43, UserAgentUsage IVOA wiki page

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `AGENT_PROPNAME` | System property that can be used to manipulate the UserAgent header.
    `static java.lang.String` | `COMMENT_HARVEST` | Comment token indicating client performs VO harvesting.
    `static java.lang.String` | `COMMENT_MONITOR` | Comment token indicating client performs VO monitoring.
    `static java.lang.String` | `COMMENT_VALIDATE` | Comment token indicating client performs VO validation.
    `static java.lang.String` | `IVOA_PREFIX` | String prefixed to purpose verb to introduce IVOA operation comment.
    `static java.lang.String` | `PURPOSE_HARVEST` | Purpose verb indicating service harvesting: "harvest".
    `static java.lang.String` | `PURPOSE_MONITOR` | Purpose verb indicating service monitoring: "monitor".
    `static java.lang.String` | `PURPOSE_VALIDATE` | Purpose verb indicating validation: "validate".

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.lang.String` | `createOpPurposeComment​(java.lang.String purpose, java.lang.String extra)` | Assembles a string of the form `(IVOA-<purpose> <extra>)`.
    `static void` | `popUserAgentToken​(java.lang.String token)` | Removes a token/comment from the currently-used User-Agent string.
    `static void` | `pushUserAgentToken​(java.lang.String token)` | Appends a token/comment to the currently used User-Agent string.

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

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

- - ### Field Detail

    - #### PURPOSE_VALIDATE

          public static final java.lang.String PURPOSE_VALIDATE

      Purpose verb indicating validation: "validate".
      See Also:
        Constant Field Values

    - #### PURPOSE_MONITOR

          public static final java.lang.String PURPOSE_MONITOR

      Purpose verb indicating service monitoring: "monitor".
      See Also:
        Constant Field Values

    - #### PURPOSE_HARVEST

          public static final java.lang.String PURPOSE_HARVEST

      Purpose verb indicating service harvesting: "harvest".
      See Also:
        Constant Field Values

    - #### IVOA_PREFIX

          public static final java.lang.String IVOA_PREFIX

      String prefixed to purpose verb to introduce IVOA operation comment.
      See Also:
        Constant Field Values

    - #### COMMENT_VALIDATE

          public static final java.lang.String COMMENT_VALIDATE

      Comment token indicating client performs VO validation.

    - #### COMMENT_MONITOR

          public static final java.lang.String COMMENT_MONITOR

      Comment token indicating client performs VO monitoring.

    - #### COMMENT_HARVEST

          public static final java.lang.String COMMENT_HARVEST

      Comment token indicating client performs VO harvesting.

    - #### AGENT_PROPNAME

          public static final java.lang.String AGENT_PROPNAME

      System property that can be used to manipulate the UserAgent header.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### pushUserAgentToken

          public static void pushUserAgentToken​(java.lang.String token)

      Appends a token/comment to the currently used User-Agent string. This does not overwrite existing text, which is in general useful.
      Parameters:
        `token` - string to add

    - #### popUserAgentToken

          public static void popUserAgentToken​(java.lang.String token)

      Removes a token/comment from the currently-used User-Agent string. This only has effect if the given token is at the end of the current list, that is if it has just been added. If it's not present or not at the end, a warning is logged and there is no other effect.
      Parameters:
        `token` - previously added string to remove

    - #### createOpPurposeComment

          public static java.lang.String createOpPurposeComment​(java.lang.String purpose,
                                                                java.lang.String extra)

      Assembles a string of the form `(IVOA-<purpose> <extra>)`.
      Parameters:
        `purpose` - operational purpose string; recommended values are `PURPOSE_*` static members of this class
        `extra` - free form additional text excluding "(" or ")"; may be null
      Returns:
        string suitable for User-Agent header comment
      Throws:
        `java.lang.IllegalArgumentException` - if rudimentary syntax checking detects errors