Package edu.illinois.library.cantaloupe.delegate

Interface JavaDelegate

public interface JavaDelegate

Interface to be implemented by JVM language-based delegate classes.

The application will create an instance of an implementation early in the request cycle and dispose of it at the end of the request cycle. Instances don't need to be thread-safe, but sharing information across instances (requests) does need to be done thread-safely.

The methods in this interface are considered public API. No other part of the application is considered public API, unless so documented, and breaking changes to it may happen at any time.

Since:
5.0

  • Method Summary

    Modifier and Type Method Description
    java.lang.Object authorize()
    Returns authorization status for the current request.
    java.util.Map<java.lang.String,​java.lang.Object> deserializeMetaIdentifier​(java.lang.String metaIdentifier)
    Deserializes the given meta-identifier string into a map of its component parts.
    java.lang.String getAzureStorageSourceBlobKey()
    N.B.: this method should not try to perform authorization.
    JavaContext getContext()  
    java.util.Map<java.lang.String,​java.lang.Object> getExtraIIIF2InformationResponseKeys()
    Adds additional keys to an Image API 2.x information response.
    java.util.Map<java.lang.String,​java.lang.Object> getExtraIIIF3InformationResponseKeys()
    Adds additional keys to an Image API 2.x information response.
    java.lang.String getFilesystemSourcePathname()
    N.B.: this method should not try to perform authorization.
    java.util.Map<java.lang.String,​java.lang.Object> getHTTPSourceResourceInfo()
    Returns one of the following:
    java.lang.String getJDBCSourceDatabaseIdentifier()
    N.B.: this method should not try to perform authorization.
    java.lang.String getJDBCSourceLookupSQL()  
    java.lang.String getJDBCSourceMediaType()
    Returns either the media (MIME) type of an image, or an SQL statement that can be used to retrieve it, if it is stored in the database.
    java.lang.String getMetadata()
    Returns XMP metadata to embed in the derivative image.
    java.util.Map<java.lang.String,​java.lang.Object> getOverlay()
    Tells the server what overlay, if any, to apply to an image.
    java.util.List<java.util.Map<java.lang.String,​java.lang.Long>> getRedactions()
    Tells the server what regions of an image to redact in response to a request.
    java.util.Map<java.lang.String,​java.lang.String> getS3SourceObjectInfo()
    N.B.: this method should not try to perform authorization.
    java.lang.String getSource()
    Tells the server which source for the identifier in the context.
    java.lang.Object preAuthorize()
    Returns authorization status for the current request.
    java.lang.String serializeMetaIdentifier​(java.util.Map<java.lang.String,​java.lang.Object> metaIdentifier)
    Serializes the given meta-identifier map.
    void setContext​(JavaContext context)
    Invoked automatically early in the request cycle and not for public use.

  • Method Details

    • getContext

      JavaContext getContext()
      Returns:
      Object containing information about the current request.

    • setContext

      void setContext​(JavaContext context)
      Invoked automatically early in the request cycle and not for public use.

    • preAuthorize

      java.lang.Object preAuthorize()

      Returns authorization status for the current request. This method is called upon all requests to all public endpoints early in the request cycle, before any image has been accessed. This means that some context properties (like full_size) 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. A boolean indicating whether the request is fully authorized or not. If not, the client will receive a 403 Forbidden response.
      2. Map 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 map also contains a location key corresponding to a URI string, the request will be redirected to that URI using that code.
          2. If the map also contains scale_numerator and scale_denominator keys, the request will be redirected using thhat code to a virtual reduced- scale version of the source image.
        3. If it corresponds to 401, the map must include a challenge key corresponding to a WWW-Authenticate header value.

    • authorize

      java.lang.Object authorize()

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

      This is a counterpart of preAuthorize() that is invoked later in the request cycle, once more information about the underlying image has become available. It should only contain logic that depends on context properties that contain information about the source image (like JavaContext.getFullSize(), JavaContext.getMetadata(), etc.

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

      The available return values are the same as for preAuthorize().

    • deserializeMetaIdentifier

      java.util.Map<java.lang.String,​java.lang.Object> deserializeMetaIdentifier​(java.lang.String metaIdentifier)

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

      This method is called only when the meta_identifier.transformer configuration key is set to DelegateMetaIdentifierTransformer.

      The map contains the following keys:

      identifier (required)
      String identifier.
      page_number (optional)
      Integer page number.
      scale_constraint (optional>
      Two-element array with scale constraint numerator at position 0 and denominator at position 1.
      Returns:
      See above. The return value should be compatible with the argument to serializeMetaIdentifier(Map).
      See Also:
      serializeMetaIdentifier(Map)

    • getExtraIIIF2InformationResponseKeys

      java.util.Map<java.lang.String,​java.lang.Object> getExtraIIIF2InformationResponseKeys()
      Adds additional keys to an Image API 2.x information response. See the IIIF Image API 2.1 specification and "endpoints" section of the user manual.
      Returns:
      Map to merge into an Image API 2.x information response. Return an empty map to add nothing.

    • getExtraIIIF3InformationResponseKeys

      java.util.Map<java.lang.String,​java.lang.Object> getExtraIIIF3InformationResponseKeys()
      Adds additional keys to an Image API 2.x information response. See the IIIF Image API 3.0 specification and "endpoints" section of the user manual.
      Returns:
      Map to merge into an Image API 3.x information response. Return an empty map to add nothing.

    • getSource

      java.lang.String getSource()
      Tells the server which source for the identifier in the context.
      Returns:
      Source name.

    • getAzureStorageSourceBlobKey

      java.lang.String getAzureStorageSourceBlobKey()
      N.B.: this method should not try to perform authorization. preAuthorize() and authorize() should be used instead.
      Returns:
      Blob key of the image corresponding to the identifier in the context, or null if not found.

    • getFilesystemSourcePathname

      java.lang.String getFilesystemSourcePathname()
      N.B.: this method should not try to perform authorization. preAuthorize() and authorize() should be used instead.
      Returns:
      Absolute pathname of the image corresponding to the identifier in the context, or null if not found.

    • getHTTPSourceResourceInfo

      java.util.Map<java.lang.String,​java.lang.Object> getHTTPSourceResourceInfo()

      Returns one of the following:

      1. String URI
      2. Map with the following keys:
        uri
        String (required)
        username
        String (required for HTTP Basic authentication)
        secret
        String (required for HTTP Basic authentication)
        headers
        Map of request header name-value pairs (optional)
      3. null if not found

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

    • getJDBCSourceDatabaseIdentifier

      java.lang.String getJDBCSourceDatabaseIdentifier()

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

      Returns:
      Database identifier of the image corresponding to the identifier in the context, or null if not found.

    • getJDBCSourceMediaType

      java.lang.String getJDBCSourceMediaType()
      Returns either the media (MIME) type of an image, or an SQL statement that can be used to retrieve it, if it is stored in the database. In the latter case, the SELECT and FROM clauses should be in uppercase in order to be autodetected. If null is returned, the media type will be inferred some other way, such as by identifier extension or magic bytes.

    • getJDBCSourceLookupSQL

      java.lang.String getJDBCSourceLookupSQL()
      Returns:
      SQL statement that selects the BLOB corresponding to the value returned by getJDBCSourceDatabaseIdentifier().

    • getS3SourceObjectInfo

      java.util.Map<java.lang.String,​java.lang.String> getS3SourceObjectInfo()
      N.B.: this method should not try to perform authorization. preAuthorize() and authorize() should be used instead.
      Returns:
      Map containing bucket and key keys, or null if not found.

    • getOverlay

      java.util.Map<java.lang.String,​java.lang.Object> getOverlay()

      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 ScriptStrategy in the application configuration.

      Possible return values:

      1. For string overlays, a map with the following keys:
        background_color
        CSS-compliant RGB(A) color.
        color
        CSS-compliant RGB(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 right, etc.
        string
        String to render.
        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.
      2. For image overlays, a map with the following keys:
        image
        Image pathname or URL.
        position
        See above.
        inset
        See above.
      3. null for no overlay.

    • getRedactions

      java.util.List<java.util.Map<java.lang.String,​java.lang.Long>> getRedactions()
      Tells the server what regions of an image to redact in response to a request. Will be called upon all image requests to any endpoint.
      Returns:
      List of maps, each with x, y, width, and height keys; or an empty list if no redactions are to be applied.

    • getMetadata

      java.lang.String getMetadata()

      Returns XMP metadata to embed in the derivative image.

      Source image metadata is available in the metadata context property.

      Only XMP can be embedded in derivative images. See the user manual for examples of working with the XMP model programmatically.

      Returns:
      String or containing XMP data to embed in the derivative image, or null to not embed anything.

    • serializeMetaIdentifier

      java.lang.String serializeMetaIdentifier​(java.util.Map<java.lang.String,​java.lang.Object> metaIdentifier)

      Serializes the given meta-identifier map.

      This method is called only when the meta_identifier.transformer configuration key is set to DelegateMetaIdentifierTransformer.

      Parameters:
      metaIdentifier - See deserializeMetaIdentifier(String) for a description of the map structure.
      Returns:
      Serialized meta-identifier compatible with the argument to deserializeMetaIdentifier(String).
      See Also:
      deserializeMetaIdentifier(String)