Interface Delegate

public interface Delegate

Delegates a variety of methods to user-supplied code.

New instances are generally acquired via DelegateFactory.newDelegate(RequestContext).

  • Method Details

    • setRequestContext

      void setRequestContext(RequestContext context) throws DelegateException
      Provides information about the request to the instance. This is the first method in this interface to be invoked.
      Parameters:
      context - Context to set.
      Throws:
      DelegateException - if the delegate object does not contain a setter method for the context.

    • getRequestContext

      RequestContext getRequestContext()
      Returns:
      The instance passed to setRequestContext(RequestContext).

    • deserializeMetaIdentifier

      default Map<String,Object> deserializeMetaIdentifier(String metaIdentifier) throws DelegateException

      Deserializes the given meta-identifier string into its component parts.

      The identifier portion has already been URL-decoded.

      This method is used only when the Key.META_IDENTIFIER_TRANSFORMER configuration key is set to the simple class name of DelegateMetaIdentifierTransformer.

      The returned instance contains the following keys:

      identifier
      String. Required.
      page_number
      Integer. Optional.
      scale_constraint
      Two-element array of integers with scale constraint numerator at position 0 and denominator at position 1. Optional.

      This default implementation supports the identifier;page_number;sc_numerator:sc_denominator scheme.

      Parameters:
      metaIdentifier - Meta-identifier to deserialize.
      Returns:
      See above. The return value must be compatible with the argument to serializeMetaIdentifier(Map).
      Throws:
      DelegateException - if there is any problem generating a result.

    • serializeMetaIdentifier

      default String serializeMetaIdentifier(Map<String,Object> metaIdentifier) throws DelegateException

      Serializes the given meta-identifier hash, but does not URL-encode it.

      This method is used only when the Key.META_IDENTIFIER_TRANSFORMER configuration key is set to the simple class name of DelegateMetaIdentifierTransformer.

      This default implementation supports the identifier;page_number;sc_numerator:sc_denominator scheme.

      Parameters:
      metaIdentifier - See deserializeMetaIdentifier(java.lang.String) for a description of the map structure.
      Returns:
      Serialized meta-identifier compatible with the argument to deserializeMetaIdentifier(String).
      Throws:
      DelegateException - if there is any problem generating a result.

    • authorizeBeforeAccess

      default Object authorizeBeforeAccess() throws DelegateException

      Returns authorization status for the current request. This method is called upon all requests to all public endpoints early in the request lifecycle, before the image has been accessed. This means that some request context keys will not be available yet.

      This method should implement all possible authorization logic except that which requires any of the context keys that aren't yet available. This will ensure efficient authorization failures.

      Implementations should assume that the underlying resource is available, and not try to check for it.

      Possible return values:

      1. Boolean true/false, indicating whether the request is fully authorized or not. If false, the client will receive a 403 Forbidden response.
      2. Hash with a status_code key.
        1. If it corresponds to an integer from 200-299, the request is authorized.
        2. If it corresponds to an integer from 300-399:
          1. If the hash also contains a location key corresponding to a URI string, the request will be redirected to that URI using that code.
          2. If the hash also contains scale_numerator and scale_denominator keys, the request will be redirected using that code to a virtual reduced-scale version of the source image.
        3. If it corresponds to 401, the hash must include a challenge key corresponding to a WWW-Authenticate header value.
      Returns:
      See above.
      Throws:
      DelegateException - if there is any problem generating a result.

    • authorize

      default Object authorize() throws DelegateException

      Returns authorization status for the current request. Will be called upon all requests to all public image endpoints.

      This is a counterpart of authorizeBeforeAccess() that is invoked later in the request cycle, once information about the source image has become available. It should only contain logic that depends on request context keys that aren't available yet from authorizeBeforeAccess().

      Implementations should assume that the underlying resource is available, and not try to check for it.

      Returns:
      See the documentation of authorizeBeforeAccess().
      Throws:
      DelegateException - if there is any problem generating a result.

    • customizeIIIF1InformationResponse

      default void customizeIIIF1InformationResponse(Map<String,Object> info) throws DelegateException

      Can be used to modify the JSON content of an IIIF Image API 1.x information response. See the IIIF Image API 1.1 specification and "endpoints" section of the user manual.

      Parameters:
      info - Modifiable information content.
      Throws:
      DelegateException - if there is any problem generating a result.

    • customizeIIIF2InformationResponse

      default void customizeIIIF2InformationResponse(Map<String,Object> info) throws DelegateException

      Can be used to modify the JSON content of an IIIF Image API 2.x information response. See the IIIF Image API 2.1 specification and "endpoints" section of the user manual.

      Parameters:
      info - Modifiable information content.
      Throws:
      DelegateException - if there is any problem generating a result.

    • customizeIIIF3InformationResponse

      default void customizeIIIF3InformationResponse(Map<String,Object> info) throws DelegateException

      Can be used to modify the JSON content of an IIIF Image API 3.x information response. See the IIIF Image API 3.0 specification and "endpoints" section of the user manual.

      Parameters:
      info - Modifiable information content.
      Throws:
      DelegateException - if there is any problem generating a result.

    • getSource

      default String getSource() throws DelegateException
      Tells the server which Source implementation to use for the given identifier.
      Returns:
      Source class name.
      Throws:
      DelegateException - if there is any problem generating a result.

    • getFilesystemSourcePathname

      default String getFilesystemSourcePathname() throws DelegateException
      N.B.: this method should not try to perform authorization.
      Returns:
      Absolute pathname of the image corresponding to the identifier in the request context, or null if not found.
      Throws:
      DelegateException - if there is any problem generating a result.

    • getHTTPSourceResourceInfo

      default Map<String,?> getHTTPSourceResourceInfo() throws DelegateException
      Returns one of the following:
      1. String URI
      2. Map with the following keys:
        uri
        String. Required.
        username
        For HTTP Basic authentication. Optional.
        secret
        For HTTP Basic authentication. Optional.
        headers
        Hash of request headers. Optional.
        send_head_request
        Optional. Defaults to true. See the documentation of the Key.HTTPSOURCE_SEND_HEAD_REQUESTS configuration key in the sample config file.
      3. null if not found.

      N.B.: This method should not try to perform authorization. authorize() should be used instead.

      Returns:
      See above.
      Throws:
      DelegateException - if there is any problem generating a result.

    • getMetadata

      default String getMetadata() throws DelegateException

      Returns XMP metadata to embed in the variant image.

      Source image metadata is available in the metadata request context key, and has the following structure:

      
 {
     "exif": {
         "tagSet": "Baseline TIFF",
         "fields": {
             "Field1Name": [
                 value
             ],
             "Field2Name": [
                 value
             ],
             "EXIFIFD": {
                 "tagSet": "EXIF",
                 "fields": {
                     "Field1Name": [
                         value
                     ],
                     "Field2Name": [
                         value
                     ]
                 }
             }
         }
     },
     "iptc": [
         "Field1Name": value,
         "Field2Name": value
     ],
     "xmp_string": "&lt;rdf:RDF&gt;...&lt;/rdf:RDF&gt;",
     "xmp_model": See https://jena.apache.org/documentation/javadoc/jena/org/apache/jena/rdf/model/Model.html,
     "xmp_elements": {
         "Field1Name": "value",
         "Field2Name": [
             "value1",
             "value2"
         ]
     },
     "native": {
         # structure varies
     }
 }
      • The exif key refers to embedded EXIF data. This also includes IFD0 metadata from source TIFFs, whether or not an EXIF IFD is present.
      • The iptc key refers to embedded IPTC IIM data.
      • The xmp_string key refers to raw embedded XMP data.
      • The xmp_model key contains a Jena Model object pre-loaded with the contents of xmp_string.
      • The xmp_elements key contains a view of the embedded XMP data as key-value pairs. This is convenient to use, but won't work correctly with XMP fields that cannot be expressed as key-value pairs.
      • The native key refers to format-specific metadata.

      Any combination of the above keys may be present or missing depending on what is available in a particular source image.

      Only XMP can be embedded in variant images. See the Guide for examples of working with the XMP model programmatically.

      Returns:
      String or Jena model containing XMP data to embed in the variant image, or null to not embed anything.
      Throws:
      DelegateException - if there is any problem generating a result.

    • getOverlayProperties

      default Map<String,Object> getOverlayProperties() throws DelegateException

      Tells the server what overlay, if any, to apply to an image. Called upon all image requests to any endpoint if overlays are enabled and the overlay strategy is set to DelegateStrategy in the application configuration.

      Possible return values:

      1. For string overlays, a map with the following keys:
        background_color
        CSS-compliant RGA(A) color.
        color
        CSS-compliant RGA(A) color.
        font
        Font name.
        font_min_size
        Minimum font size in points. Ignored when word_wrap is true.
        font_size
        Font size in points.
        font_weight
        Font weight based on 1.
        glyph_spacing
        Glyph spacing based on 0.
        inset
        Pixels of inset.
        position
        Position like top left, center, center right, etc.
        string
        String to draw.
        stroke_color
        CSS-compliant RGB(A) text outline color.
        stroke_width
        Text outline width in pixels.
        word_wrap
        Whether to wrap long lines within string ( true or false).
      2. For image overlays, a hash with the following keys:
        image
        Image pathname or URL.
        position
        See above.
        inset
        See above.
      3. null for no overlay.
      Returns:
      See above.
      Throws:
      DelegateException - if there is any problem generating a result.

    • getRedactions

      default List<Map<String,Object>> getRedactions() throws DelegateException

      Draws one or more rectangles over an image in response to a request. Will be called upon all image requests to any endpoint.

      Returns:
      List of maps, each with x, y, width, height, and color keys. The first four have integer values, and the last is a valid CSS color. If no redactions are to be applied, an empty list is returned.
      Throws:
      DelegateException - if there is any problem generating a result.

    • invoke

      default Object invoke(String methodName, Object... args) throws DelegateException

      Invokes an arbitrarily-named method.

      This default implementation simply invokes the method with the given name defined in the same class.

      Parameters:
      methodName - Name of the method to invoke.
      args - Arguments to pass to the invocation.
      Returns:
      Method return value.
      Throws:
      DelegateException - if there is any problem generating a result.