Class IngestDocument


  • public final class IngestDocument
    extends java.lang.Object
    Represents a single document being captured before indexing and holds the source and metadata (like id, type and index).
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String INGEST_KEY  
    • Constructor Summary

      Constructors 
      Constructor Description
      IngestDocument​(java.lang.String index, java.lang.String type, java.lang.String id, java.lang.String routing, java.lang.Long version, VersionType versionType, java.util.Map<java.lang.String,​java.lang.Object> source)  
      IngestDocument​(java.util.Map<java.lang.String,​java.lang.Object> sourceAndMetadata, java.util.Map<java.lang.String,​java.lang.Object> ingestMetadata)
      Constructor needed for testing that allows to create a new IngestDocument given the provided elasticsearch metadata, source and ingest metadata.
      IngestDocument​(IngestDocument other)
      Copy constructor that creates a new IngestDocument which has exactly the same properties as the one provided as argument
    • Method Summary

      Modifier and Type Method Description
      void appendFieldValue​(java.lang.String path, java.lang.Object value)
      Appends the provided value to the provided path in the document.
      void appendFieldValue​(TemplateScript.Factory fieldPathTemplate, ValueSource valueSource)
      Appends the provided value to the provided path in the document.
      static <K,​V>
      java.util.Map<K,​V>
      deepCopyMap​(java.util.Map<K,​V> source)  
      boolean equals​(java.lang.Object obj)  
      IngestDocument executePipeline​(Pipeline pipeline)
      Executes the given pipeline with for this document unless the pipeline has already been executed for this document.
      java.util.Map<IngestDocument.MetaData,​java.lang.Object> extractMetadata()
      one time operation that extracts the metadata fields from the ingest document and returns them.
      <T> T getFieldValue​(java.lang.String path, java.lang.Class<T> clazz)
      Returns the value contained in the document for the provided path
      <T> T getFieldValue​(java.lang.String path, java.lang.Class<T> clazz, boolean ignoreMissing)
      Returns the value contained in the document for the provided path
      <T> T getFieldValue​(TemplateScript.Factory pathTemplate, java.lang.Class<T> clazz)
      Returns the value contained in the document with the provided templated path
      byte[] getFieldValueAsBytes​(java.lang.String path)
      Returns the value contained in the document for the provided path as a byte array.
      byte[] getFieldValueAsBytes​(java.lang.String path, boolean ignoreMissing)
      Returns the value contained in the document for the provided path as a byte array.
      java.util.Map<java.lang.String,​java.lang.Object> getIngestMetadata()
      Returns the available ingest metadata fields, by default only timestamp, but it is possible to set additional ones.
      java.util.Map<IngestDocument.MetaData,​java.lang.Object> getMetadata()
      Does the same thing as extractMetadata() but does not mutate the map.
      java.util.Map<java.lang.String,​java.lang.Object> getSourceAndMetadata()
      Returns the document including its metadata fields, unless extractMetadata() has been called, in which case the metadata fields will not be present anymore.
      boolean hasField​(java.lang.String path)
      Checks whether the document contains a value for the provided path
      boolean hasField​(java.lang.String path, boolean failOutOfRange)
      Checks whether the document contains a value for the provided path
      boolean hasField​(TemplateScript.Factory fieldPathTemplate)
      Checks whether the document contains a value for the provided templated path
      int hashCode()  
      void removeField​(java.lang.String path)
      Removes the field identified by the provided path.
      void removeField​(TemplateScript.Factory fieldPathTemplate)
      Removes the field identified by the provided path.
      java.lang.String renderTemplate​(TemplateScript.Factory template)  
      void setFieldValue​(java.lang.String path, java.lang.Object value)
      Sets the provided value to the provided path in the document.
      void setFieldValue​(TemplateScript.Factory fieldPathTemplate, ValueSource valueSource)
      Sets the provided value to the provided path in the document.
      java.lang.String toString()  
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • IngestDocument

        public IngestDocument​(java.lang.String index,
                              java.lang.String type,
                              java.lang.String id,
                              java.lang.String routing,
                              java.lang.Long version,
                              VersionType versionType,
                              java.util.Map<java.lang.String,​java.lang.Object> source)
      • IngestDocument

        public IngestDocument​(IngestDocument other)
        Copy constructor that creates a new IngestDocument which has exactly the same properties as the one provided as argument
      • IngestDocument

        public IngestDocument​(java.util.Map<java.lang.String,​java.lang.Object> sourceAndMetadata,
                              java.util.Map<java.lang.String,​java.lang.Object> ingestMetadata)
        Constructor needed for testing that allows to create a new IngestDocument given the provided elasticsearch metadata, source and ingest metadata. This is needed because the ingest metadata will be initialized with the current timestamp at init time, which makes equality comparisons impossible in tests.
    • Method Detail

      • getFieldValue

        public <T> T getFieldValue​(java.lang.String path,
                                   java.lang.Class<T> clazz)
        Returns the value contained in the document for the provided path
        Parameters:
        path - The path within the document in dot-notation
        clazz - The expected class of the field value
        Returns:
        the value for the provided path if existing, null otherwise
        Throws:
        java.lang.IllegalArgumentException - if the path is null, empty, invalid, if the field doesn't exist or if the field that is found at the provided path is not of the expected type.
      • getFieldValue

        public <T> T getFieldValue​(java.lang.String path,
                                   java.lang.Class<T> clazz,
                                   boolean ignoreMissing)
        Returns the value contained in the document for the provided path
        Parameters:
        path - The path within the document in dot-notation
        clazz - The expected class of the field value
        ignoreMissing - The flag to determine whether to throw an exception when `path` is not found in the document.
        Returns:
        the value for the provided path if existing, null otherwise.
        Throws:
        java.lang.IllegalArgumentException - only if ignoreMissing is false and the path is null, empty, invalid, if the field doesn't exist or if the field that is found at the provided path is not of the expected type.
      • getFieldValue

        public <T> T getFieldValue​(TemplateScript.Factory pathTemplate,
                                   java.lang.Class<T> clazz)
        Returns the value contained in the document with the provided templated path
        Parameters:
        pathTemplate - The path within the document in dot-notation
        clazz - The expected class fo the field value
        Returns:
        the value fro the provided path if existing, null otherwise
        Throws:
        java.lang.IllegalArgumentException - if the pathTemplate is null, empty, invalid, if the field doesn't exist, or if the field that is found at the provided path is not of the expected type.
      • getFieldValueAsBytes

        public byte[] getFieldValueAsBytes​(java.lang.String path)
        Returns the value contained in the document for the provided path as a byte array. If the path value is a string, a base64 decode operation will happen. If the path value is a byte array, it is just returned
        Parameters:
        path - The path within the document in dot-notation
        Returns:
        the byte array for the provided path if existing
        Throws:
        java.lang.IllegalArgumentException - if the path is null, empty, invalid, if the field doesn't exist or if the field that is found at the provided path is not of the expected type.
      • getFieldValueAsBytes

        public byte[] getFieldValueAsBytes​(java.lang.String path,
                                           boolean ignoreMissing)
        Returns the value contained in the document for the provided path as a byte array. If the path value is a string, a base64 decode operation will happen. If the path value is a byte array, it is just returned
        Parameters:
        path - The path within the document in dot-notation
        ignoreMissing - The flag to determine whether to throw an exception when `path` is not found in the document.
        Returns:
        the byte array for the provided path if existing
        Throws:
        java.lang.IllegalArgumentException - if the path is null, empty, invalid, if the field doesn't exist or if the field that is found at the provided path is not of the expected type.
      • hasField

        public boolean hasField​(TemplateScript.Factory fieldPathTemplate)
        Checks whether the document contains a value for the provided templated path
        Parameters:
        fieldPathTemplate - the template for the path within the document in dot-notation
        Returns:
        true if the document contains a value for the field, false otherwise
        Throws:
        java.lang.IllegalArgumentException - if the path is null, empty or invalid
      • hasField

        public boolean hasField​(java.lang.String path)
        Checks whether the document contains a value for the provided path
        Parameters:
        path - The path within the document in dot-notation
        Returns:
        true if the document contains a value for the field, false otherwise
        Throws:
        java.lang.IllegalArgumentException - if the path is null, empty or invalid.
      • hasField

        public boolean hasField​(java.lang.String path,
                                boolean failOutOfRange)
        Checks whether the document contains a value for the provided path
        Parameters:
        path - The path within the document in dot-notation
        failOutOfRange - Whether to throw an IllegalArgumentException if array is accessed outside of its range
        Returns:
        true if the document contains a value for the field, false otherwise
        Throws:
        java.lang.IllegalArgumentException - if the path is null, empty or invalid.
      • removeField

        public void removeField​(TemplateScript.Factory fieldPathTemplate)
        Removes the field identified by the provided path.
        Parameters:
        fieldPathTemplate - Resolves to the path with dot-notation within the document
        Throws:
        java.lang.IllegalArgumentException - if the path is null, empty, invalid or if the field doesn't exist.
      • removeField

        public void removeField​(java.lang.String path)
        Removes the field identified by the provided path.
        Parameters:
        path - the path of the field to be removed
        Throws:
        java.lang.IllegalArgumentException - if the path is null, empty, invalid or if the field doesn't exist.
      • appendFieldValue

        public void appendFieldValue​(java.lang.String path,
                                     java.lang.Object value)
        Appends the provided value to the provided path in the document. Any non existing path element will be created. If the path identifies a list, the value will be appended to the existing list. If the path identifies a scalar, the scalar will be converted to a list and the provided value will be added to the newly created list. Supports multiple values too provided in forms of list, in that case all the values will be appended to the existing (or newly created) list.
        Parameters:
        path - The path within the document in dot-notation
        value - The value or values to append to the existing ones
        Throws:
        java.lang.IllegalArgumentException - if the path is null, empty or invalid.
      • appendFieldValue

        public void appendFieldValue​(TemplateScript.Factory fieldPathTemplate,
                                     ValueSource valueSource)
        Appends the provided value to the provided path in the document. Any non existing path element will be created. If the path identifies a list, the value will be appended to the existing list. If the path identifies a scalar, the scalar will be converted to a list and the provided value will be added to the newly created list. Supports multiple values too provided in forms of list, in that case all the values will be appended to the existing (or newly created) list.
        Parameters:
        fieldPathTemplate - Resolves to the path with dot-notation within the document
        valueSource - The value source that will produce the value or values to append to the existing ones
        Throws:
        java.lang.IllegalArgumentException - if the path is null, empty or invalid.
      • setFieldValue

        public void setFieldValue​(java.lang.String path,
                                  java.lang.Object value)
        Sets the provided value to the provided path in the document. Any non existing path element will be created. If the last item in the path is a list, the value will replace the existing list as a whole. Use appendFieldValue(String, Object) to append values to lists instead.
        Parameters:
        path - The path within the document in dot-notation
        value - The value to put in for the path key
        Throws:
        java.lang.IllegalArgumentException - if the path is null, empty, invalid or if the value cannot be set to the item identified by the provided path.
      • setFieldValue

        public void setFieldValue​(TemplateScript.Factory fieldPathTemplate,
                                  ValueSource valueSource)
        Sets the provided value to the provided path in the document. Any non existing path element will be created. If the last element is a list, the value will replace the existing list.
        Parameters:
        fieldPathTemplate - Resolves to the path with dot-notation within the document
        valueSource - The value source that will produce the value to put in for the path key
        Throws:
        java.lang.IllegalArgumentException - if the path is null, empty, invalid or if the value cannot be set to the item identified by the provided path.
      • extractMetadata

        public java.util.Map<IngestDocument.MetaData,​java.lang.Object> extractMetadata()
        one time operation that extracts the metadata fields from the ingest document and returns them. Metadata fields that used to be accessible as ordinary top level fields will be removed as part of this call.
      • getIngestMetadata

        public java.util.Map<java.lang.String,​java.lang.Object> getIngestMetadata()
        Returns the available ingest metadata fields, by default only timestamp, but it is possible to set additional ones. Use only for reading values, modify them instead using setFieldValue(String, Object) and removeField(String)
      • getSourceAndMetadata

        public java.util.Map<java.lang.String,​java.lang.Object> getSourceAndMetadata()
        Returns the document including its metadata fields, unless extractMetadata() has been called, in which case the metadata fields will not be present anymore. Modify the document instead using setFieldValue(String, Object) and removeField(String)
      • deepCopyMap

        public static <K,​V> java.util.Map<K,​V> deepCopyMap​(java.util.Map<K,​V> source)
      • executePipeline

        public IngestDocument executePipeline​(Pipeline pipeline)
                                       throws java.lang.Exception
        Executes the given pipeline with for this document unless the pipeline has already been executed for this document.
        Parameters:
        pipeline - Pipeline to execute
        Throws:
        java.lang.Exception - On exception in pipeline execution
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object