Package org.apache.sis.metadata.iso.content

## Class DefaultBand

- Object
- - AbstractMetadata
  - - ModifiableMetadata
    - - ISOMetadata
      - - DefaultRangeDimension
        - - DefaultSampleDimension
          - - DefaultBand

- All Implemented Interfaces:
    `Serializable`, `Emptiable`, `LenientComparable`, `IdentifiedObject`, `Band`, `RangeDimension`

      public class DefaultBand
      extends DefaultSampleDimension
      implements Band

  Range of wavelengths in the electromagnetic spectrum. The following property is conditional (i.e. mandatory under some circumstances) in a well-formed metadata according ISO 19115:
  `MD_Band` `└─units……` Units of data in each dimension included in the resource.

  Limitations:

  - Instances of this class are not synchronized for multi-threading. Synchronization, if needed, is caller's responsibility.
  - Serialized objects of this class are not guaranteed to be compatible with future Apache SIS releases. Serialization support is appropriate for short term storage or RMI between applications running the same version of Apache SIS. For long term storage, use `XML` instead.
  Since:
    0.3
  See Also:
    Serialized Form

  Defined in the `sis-metadata` module

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class ModifiableMetadata

      `ModifiableMetadata​.State`

  - ### Field Summary

    - ### Fields inherited from class ISOMetadata

      `identifiers`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DefaultBand()` | Constructs an initially empty band.
    `DefaultBand​(Band object)` | Constructs a new instance initialized with the values from the specified metadata object.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static DefaultBand` | `castOrCopy​(Band object)` | Returns a SIS metadata implementation with the values of the given arbitrary implementation.
    `BandDefinition` | `getBandBoundaryDefinition()` | Returns the designation of criterion for defining maximum and minimum wavelengths for a spectral band.
    `Double` | `getBoundMax()` | Returns the longest wavelength that the sensor is capable of collecting within a designated band.
    `Double` | `getBoundMin()` | Returns the shortest wavelength that the sensor is capable of collecting within a designated band.
    `Unit<Length>` | `getBoundUnits()` | Returns units in which sensor wavelengths are expressed.
    `PolarizationOrientation` | `getDetectedPolarization()` | Returns polarization of the radiation detected.
    `Double` | `getNominalSpatialResolution()` | Returns the smallest distance between which separate points can be distinguished, as specified in instrument design.
    `Double` | `getPeakResponse()` | Returns the wavelength at which the response is the highest.
    `Integer` | `getToneGradation()` | Returns the number of discrete numerical values in the grid data.
    `TransferFunctionType` | `getTransferFunctionType()` | Returns type of transfer function to be used when scaling a physical value for a given element.
    `PolarizationOrientation` | `getTransmittedPolarization()` | Returns the polarization of the radiation transmitted.
    `Unit<Length>` | `getUnits()` | Returns the units of data as a unit of length.
    `void` | `setBandBoundaryDefinition​(BandDefinition newValue)` | Sets designation of criterion for defining maximum and minimum wavelengths for a spectral band.
    `void` | `setBoundMax​(Double newValue)` | Sets the longest wavelength that the sensor is capable of collecting within a designated band.
    `void` | `setBoundMin​(Double newValue)` | Sets the shortest wavelength that the sensor is capable of collecting within a designated band.
    `void` | `setBoundUnits​(Unit<Length> newValue)` | Sets a new units in which sensor wavelengths are expressed.
    `void` | `setDetectedPolarization​(PolarizationOrientation newValue)` | Sets the polarization of the radiation detected.
    `void` | `setNominalSpatialResolution​(Double newValue)` | Sets the smallest distance between which separate points can be distinguished, as specified in instrument design.
    `void` | `setPeakResponse​(Double newValue)` | Sets the wavelength at which the response is the highest.
    `void` | `setToneGradation​(Integer newValue)` | Sets the number of discrete numerical values in the grid data.
    `void` | `setTransferFunctionType​(TransferFunctionType newValue)` | Sets the type of transfer function to be used when scaling a physical value for a given element.
    `void` | `setTransmittedPolarization​(PolarizationOrientation newValue)` | Sets the polarization of the radiation transmitted.
    `void` | `setUnits​(Unit<?> newValue)` | Sets the units of data as a unit of length.

    - ### Methods inherited from class DefaultSampleDimension

      `getBitsPerValue, getMaxValue, getMeanValue, getMinValue, getNumberOfValues, getOffset, getOtherProperty, getOtherPropertyType, getScaleFactor, getStandardDeviation, setBitsPerValue, setMaxValue, setMeanValue, setMinValue, setNumberOfValues, setOffset, setOtherProperty, setOtherPropertyType, setScaleFactor, setStandardDeviation`

    - ### Methods inherited from class DefaultRangeDimension

      `castOrCopy, getDescription, getDescriptor, getNames, getSequenceIdentifier, setDescription, setDescriptor, setNames, setSequenceIdentifier`

    - ### Methods inherited from class ISOMetadata

      `getIdentifier, getIdentifierMap, getIdentifiers, getStandard, setIdentifier, transitionTo`

    - ### Methods inherited from class ModifiableMetadata

      `checkWritePermission, checkWritePermission, collectionType, copyCollection, copyList, copyMap, copySet, freeze, isModifiable, nonNullCollection, nonNullList, nonNullMap, nonNullSet, singleton, state, unmodifiable, writeCollection, writeList, writeMap, writeSet`

    - ### Methods inherited from class AbstractMetadata

      `asMap, asTreeTable, equals, equals, getInterface, hashCode, isEmpty, prune, toString`

    - ### Methods inherited from class Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface Band

      `getBitsPerValue, getMaxValue, getMinValue, getOffset, getScaleFactor`

    - ### Methods inherited from interface RangeDimension

      `getDescriptor, getSequenceIdentifier`

- - ### Constructor Detail

    - #### DefaultBand

          public DefaultBand()

      Constructs an initially empty band.

    - #### DefaultBand

          public DefaultBand​(Band object)

      Constructs a new instance initialized with the values from the specified metadata object. This is a shallow copy constructor, since the other metadata contained in the given object are not recursively copied.
      Note on properties validation: This constructor does not verify the property values of the given metadata (e.g. whether it contains unexpected negative values). This is because invalid metadata exist in practice, and verifying their validity in this copy constructor is often too late. Note that this is not the only hole, as invalid metadata instances can also be obtained by unmarshalling an invalid XML document.
      Parameters:
        `object` - the metadata to copy values from, or `null` if none.
      See Also:
        `castOrCopy(Band)`

  - ### Method Detail

    - #### castOrCopy

          public static DefaultBand castOrCopy​(Band object)

      Returns a SIS metadata implementation with the values of the given arbitrary implementation. This method performs the first applicable action in the following choices:
      - If the given object is `null`, then this method returns `null`.
      - Otherwise if the given object is already an instance of `DefaultBand`, then it is returned unchanged.
      - Otherwise a new `DefaultBand` instance is created using the copy constructor and returned. Note that this is a shallow copy operation, since the other metadata contained in the given object are not recursively copied.
      Parameters:
        `object` - the object to get as a SIS implementation, or `null` if none.
      Returns:
        a SIS implementation containing the values of the given object (may be the given object itself), or `null` if the argument was null.

    - #### getBoundMin

          @ValueRange(minimum=0.0)
          @UML(identifier="boundMin",
               obligation=OPTIONAL,
               specification=ISO_19115)
          public Double getBoundMin()

      Returns the shortest wavelength that the sensor is capable of collecting within a designated band. The units of measurement is given by `getBoundUnits()`.
      Returns:
        Shortest wavelength that the sensor is capable of collecting within a designated band, or `null` if unspecified.
      Since:
        0.5

    - #### setBoundMin

          public void setBoundMin​(Double newValue)

      Sets the shortest wavelength that the sensor is capable of collecting within a designated band.
      Parameters:
        `newValue` - the new shortest wavelength, or `null`.
      Throws:
        `IllegalArgumentException` - if the given value is negative.
      Since:
        0.5

    - #### getBoundMax

          @ValueRange(minimum=0.0)
          @UML(identifier="boundMax",
               obligation=OPTIONAL,
               specification=ISO_19115)
          public Double getBoundMax()

      Returns the longest wavelength that the sensor is capable of collecting within a designated band. The units of measurement is given by `getUnits()`.
      Returns:
        longest wavelength that the sensor is capable of collecting within a designated band, or `null` if unspecified.
      Since:
        0.5

    - #### setBoundMax

          public void setBoundMax​(Double newValue)

      Sets the longest wavelength that the sensor is capable of collecting within a designated band.
      Parameters:
        `newValue` - the new longest wavelength, or `null`.
      Throws:
        `IllegalArgumentException` - if the given value is negative.
      Since:
        0.5

    - #### getBoundUnits

          @UML(identifier="boundUnits",
               obligation=OPTIONAL,
               specification=ISO_19115)
          public Unit<Length> getBoundUnits()

      Returns units in which sensor wavelengths are expressed.
      Returns:
        units in which sensor wavelengths are expressed.
      Since:
        0.5
      See Also:
        `Units​.NANOMETRE`

    - #### setBoundUnits

          public void setBoundUnits​(Unit<Length> newValue)

      Sets a new units in which sensor wavelengths are expressed.
      Parameters:
        `newValue` - the new unit.
      Since:
        0.5

    - #### getBandBoundaryDefinition

          public BandDefinition getBandBoundaryDefinition()

      Returns the designation of criterion for defining maximum and minimum wavelengths for a spectral band.
      Specified by:
        `getBandBoundaryDefinition` in interface `Band`
      Returns:
        criterion for defining maximum and minimum wavelengths, or `null`.

    - #### setBandBoundaryDefinition

          public void setBandBoundaryDefinition​(BandDefinition newValue)

      Sets designation of criterion for defining maximum and minimum wavelengths for a spectral band.
      Parameters:
        `newValue` - the new band definition.

    - #### getUnits

          public Unit<Length> getUnits()

      Returns the units of data as a unit of length.
      Upcoming API change — generalization
      As of ISO 19115:2014, the units of wavelength is rather `boundUnits`. The restriction for units of length in this `units` property may be relaxed in GeoAPI 4.0.
      Specified by:
        `getUnits` in interface `Band`
      Overrides:
        `getUnits` in class `DefaultSampleDimension`
      Returns:
        The units of data.

    - #### setUnits

          public void setUnits​(Unit<?> newValue)

      Sets the units of data as a unit of length.
      Upcoming precondition change — relaxation
      The current implementation requires the unit to be an instance of `Unit<Length>`, otherwise a `ClassCastException` is thrown. This is because the value returned by `getUnits()` was restricted by ISO 19115:2003 to units of length. However this restriction may be relaxed in GeoAPI 4.0.
      Overrides:
        `setUnits` in class `DefaultSampleDimension`
      Parameters:
        `newValue` - The new units of data as an instance of `Unit<Length>`.

    - #### getPeakResponse

          @ValueRange(minimum=0.0)
          public Double getPeakResponse()

      Returns the wavelength at which the response is the highest. The units of measurement is given by `getBoundUnits()`.
      Specified by:
        `getPeakResponse` in interface `Band`
      Returns:
        wavelength at which the response is the highest, or `null` if unspecified.

    - #### setPeakResponse

          public void setPeakResponse​(Double newValue)

      Sets the wavelength at which the response is the highest.
      Parameters:
        `newValue` - the new peak response, or `null`.
      Throws:
        `IllegalArgumentException` - if the given value is negative.

    - #### getToneGradation

          @ValueRange(minimum=0.0)
          public Integer getToneGradation()

      Returns the number of discrete numerical values in the grid data.
      Specified by:
        `getToneGradation` in interface `Band`
      Returns:
        number of discrete numerical values in the grid data, or `null` if none.

    - #### setToneGradation

          public void setToneGradation​(Integer newValue)

      Sets the number of discrete numerical values in the grid data.
      Parameters:
        `newValue` - the new tone gradation.

    - #### getNominalSpatialResolution

          @ValueRange(minimum=0.0,
                      isMinIncluded=false)
          public Double getNominalSpatialResolution()

      Returns the smallest distance between which separate points can be distinguished, as specified in instrument design.
      Specified by:
        `getNominalSpatialResolution` in interface `Band`
      Overrides:
        `getNominalSpatialResolution` in class `DefaultSampleDimension`
      Returns:
        smallest distance between which separate points can be distinguished, or `null`.

    - #### setNominalSpatialResolution

          public void setNominalSpatialResolution​(Double newValue)

      Sets the smallest distance between which separate points can be distinguished, as specified in instrument design.
      Overrides:
        `setNominalSpatialResolution` in class `DefaultSampleDimension`
      Parameters:
        `newValue` - the new nominal spatial resolution.

    - #### getTransferFunctionType

          public TransferFunctionType getTransferFunctionType()

      Returns type of transfer function to be used when scaling a physical value for a given element.
      Specified by:
        `getTransferFunctionType` in interface `Band`
      Overrides:
        `getTransferFunctionType` in class `DefaultSampleDimension`
      Returns:
        type of transfer function, or `null`.

    - #### setTransferFunctionType

          public void setTransferFunctionType​(TransferFunctionType newValue)

      Sets the type of transfer function to be used when scaling a physical value for a given element.
      Overrides:
        `setTransferFunctionType` in class `DefaultSampleDimension`
      Parameters:
        `newValue` - the new transfer function value.

    - #### getTransmittedPolarization

          public PolarizationOrientation getTransmittedPolarization()

      Returns the polarization of the radiation transmitted.
      Upcoming API change
      This method may be renamed `getTransmittedPolarization` and its return type replaced by `PolarisationOrientation` ("z" letter replaced by "s" letter) in GeoAPI 4.0 for compliance with ISO 19115-2:2019.
      Specified by:
        `getTransmittedPolarization` in interface `Band`
      Returns:
        polarization of the radiation transmitted, or `null`.

    - #### setTransmittedPolarization

          public void setTransmittedPolarization​(PolarizationOrientation newValue)

      Sets the polarization of the radiation transmitted.
      Upcoming API change
      This method may be renamed `setTransmittedPolarization` and its argument type replaced by `PolarisationOrientation` ("z" letter replaced by "s" letter) in GeoAPI 4.0 for compliance with ISO 19115-2:2019.
      Parameters:
        `newValue` - the new transmitted polarization.

    - #### getDetectedPolarization

          public PolarizationOrientation getDetectedPolarization()

      Returns polarization of the radiation detected.
      Upcoming API change
      This method may be renamed `getDetectedPolarization` and its return type replaced by `PolarisationOrientation` ("z" letter replaced by "s" letter) in GeoAPI 4.0 for compliance with ISO 19115-2:2019.
      Specified by:
        `getDetectedPolarization` in interface `Band`
      Returns:
        polarization of the radiation detected, or `null`.

    - #### setDetectedPolarization

          public void setDetectedPolarization​(PolarizationOrientation newValue)

      Sets the polarization of the radiation detected.
      Upcoming API change
      This method may be renamed `setDetectedPolarization` and its argument type replaced by `PolarisationOrientation` ("z" letter replaced by "s" letter) in GeoAPI 4.0 for compliance with ISO 19115-2:2019.
      Parameters:
        `newValue` - the new detected polarization.