Class OperationList

java.lang.Object
is.galia.operation.OperationList
All Implemented Interfaces:
Iterable<Operation>
public final class OperationList extends Object implements Iterable<Operation>

Normalized list of image transform operations associated with a source image that is identified by either a MetaIdentifier or Identifier.

This class has dual purposes:

  1. To describe a list of image transform operations;
  2. To uniquely identify a post-processed ("variant") image created using the instance. For example, the return values of toString() or toFilename() may be used in cache keys.

Endpoints translate request arguments into instances of this class in order to pass them off to processors and caches.

Processors should iterate the operations in the list and apply them (generally in order) as best they can. They must take the scale constraint into account when cropping and scaling.

  • Constructor Details

    • OperationList

      public OperationList()
      Creates a new empty instance.

    • OperationList

      public OperationList(Identifier identifier)

    • OperationList

      public OperationList(MetaIdentifier identifier)

  • Method Details

    • builder

      public static OperationList.Builder builder()

    • add

      public void add(Operation op)
      Adds an operation to the end of the list.
      Parameters:
      op - Operation to add. null values are silently discarded.
      Throws:
      IllegalStateException - if the instance is frozen.

    • add

      public void add(int index, Operation op)
      Inserts an operation at the given index in the list.
      Parameters:
      op - Operation to add. null values are silently discarded.
      Throws:
      IllegalStateException - if the instance is frozen.

    • addAfter

      public void addAfter(Operation op, Class<? extends Operation> afterClass)
      Adds an operation immediately after the last instance of the given class in the list. If there are no such instances in the list, the operation will be added to the end of the list.
      Parameters:
      op - Operation to add. null values are silently discarded.
      afterClass - The operation will be added after the last instance of this class in the list.
      Throws:
      IllegalStateException - if the instance is frozen.

    • addBefore

      public void addBefore(Operation op, Class<? extends Operation> beforeClass)
      Adds an operation immediately before the first instance of the given class in the list. If there are no such instances in the list, the operation will be added to the end of the list.
      Parameters:
      op - Operation to add.
      beforeClass - The operation will be added before the first instance of this class in the list.
      Throws:
      IllegalStateException - if the instance is frozen.

    • applyNonEndpointMutations

      public void applyNonEndpointMutations(Info info, Delegate delegate)

      Most image processing operations (crop, scale, etc.) are supplied by a client in a request to an endpoint. This method adds any other operations or options that endpoints have nothing to do with, and also adjusts existing operations according to either/both the application configuration and delegate method return values.

      This method must be called after all endpoint operations have been added, as it may modify them. The instance's identifier must also be set.

      Subsequent invocations will have no effect.

      Parameters:
      info - Source image info.
      delegate - Delegate for the current request.

    • clear

      public void clear()
      Throws:
      IllegalStateException - If the instance is frozen.

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • freeze

      public void freeze()
      "Freezes" the instance and all of its operations so that they can no longer be mutated.

    • getFirst

      public Operation getFirst(Class<? extends Operation> opClass)
      Parameters:
      opClass - Class to get the first instance of.
      Returns:
      The first instance of opClass in the list, or null if there is no operation of that class in the list.

    • getIdentifier

      public Identifier getIdentifier()
      Returns:
      The identifier ascribed to the instance, if set; otherwise the meta-identifier's identifier, if set; otherwise null.

    • getMetaIdentifier

      public MetaIdentifier getMetaIdentifier()

    • getOperations

      public List<Operation> getOperations()
      Returns:
      Unmodifiable instance.

    • getOptions

      public Map<String,Object> getOptions()
      Returns:
      Map of auxiliary options separate from the basic crop/scale/etc., such as URI query arguments, etc. If the instance is frozen, the map is unmodifiable.

    • getOutputFormat

      public Format getOutputFormat()

      Used for quickly checking the Encode operation's format.

      N.B.: applyNonEndpointMutations(is.galia.image.Info, is.galia.delegate.Delegate) may mutate the Encode operation.

      Returns:
      The output format.

    • getPageIndex

      public int getPageIndex()
      Convenience method.
      Returns:
      the effective page index of the meta-identifier, if set, or 0 otherwise.

    • getResultingSize

      public Size getResultingSize(Size fullSize)
      Parameters:
      fullSize - Full size of the source image to which the instance is being applied.
      Returns:
      Resulting dimensions when all operations are applied in sequence to an image of the given full size.

    • getScaleConstraint

      public ScaleConstraint getScaleConstraint()
      Convenience method that returns the instance ascribed to the meta-identifier, if set, or a neutral instance otherwise.

    • hasEffect

      public boolean hasEffect(Size fullSize, Format format)
      Determines whether the operations are effectively calling for the unmodified source image, based on the given source format.
      Parameters:
      fullSize - Full size of the source image.
      format - Source image format.
      Returns:
      Whether the operations are effectively calling for the unmodified source image.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • iterator

      public Iterator<Operation> iterator()
      Specified by:
      iterator in interface Iterable<Operation>
      Returns:
      Iterator over the instance's operations. If the instance is frozen, Iterator.remove() will throw an UnsupportedOperationException.

    • remove

      public void remove(Operation op)

    • replace

      public void replace(Operation op, Operation newOp)

    • setIdentifier

      public void setIdentifier(Identifier identifier)
      Parameters:
      identifier -
      Throws:
      IllegalStateException - if the instance is frozen.
      See Also:

    • setMetaIdentifier

      public void setMetaIdentifier(MetaIdentifier metaIdentifier)

      Sets the effective base scale of the source image upon which the instance is to be applied.

      Parameters:
      metaIdentifier -
      Throws:
      IllegalStateException - if the instance is frozen.
      See Also:

    • stream

      public Stream<Operation> stream()

    • toFilename

      public String toFilename()

      Returns a filename-safe string guaranteed to uniquely represent the instance. The filename is in the format:

      [hashed identifier]_[page number + hashed scale constraint + operation list + options list].[output format extension]

      Returns:
      Filename string.

    • toMap

      public Map<String,Object> toMap(Size fullSize)

      Returns a map representing the instance with the following format (expressed in JSON, with Maps expressed as objects and Lists expressed as arrays):

      {
     "identifier": "result of Identifier.toString()",
     "scale_constraint": result of ScaleConstraint.toMap()
     "operations": [
         result of Operation.toMap(is.galia.image.Size, is.galia.image.ScaleConstraint)
     ],
     "options": {
         "key": value
     }
 }
      Parameters:
      fullSize - Full size of the source image on which the instance is being applied.
      Returns:
      Unmodifiable Map representation of the instance.

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Returns:
      String representation of the instance, guaranteed to uniquely represent the instance, but not guaranteed to have any particular format.

    • validate

      public void validate(Size fullSize, Format sourceFormat) throws VariantFormatException, OperationException
      1. Checks that an identifier is set
      2. Checks that an Encode is present
      3. Calls Operation.validate(is.galia.image.Size, is.galia.image.ScaleConstraint) on each Operation
      4. Checks that the resulting scale is not larger than allowed by the scale constraint
      5. Checks that the resulting pixel area is greater than zero and less than or equal to Key.MAX_PIXELS (if set)
      These are all general validations that are not endpoint-specific.
      Parameters:
      fullSize - Full size of the source image on which the instance is being applied.
      sourceFormat - Source image format.
      Throws:
      IllegalSizeException - if the resulting size exceeds Key.MAX_PIXELS.
      IllegalScaleException - if the resulting scale exceeds that allowed by the scale constraint, if set.
      OperationException - if the instance is invalid in some other way.
      VariantFormatException