/*
    * Licensed to The Apereo Foundation under one or more contributor license
    * agreements. See the NOTICE file distributed with this work for additional
    * information regarding copyright ownership.
    *
    *
    * The Apereo Foundation licenses this file to you under the Educational
    * Community License, Version 2.0 (the "License"); you may not use this file
    * except in compliance with the License. You may obtain a copy of the License
   * at:
   *
   *   http://opensource.org/licenses/ecl2.txt
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
   * License for the specific language governing permissions and limitations under
   * the License.
   *
   */
  
  
  package org.opencastproject.metadata.mpeg7;
  
  /**
   * A video segment represents a temporal decomposition of the video stream that may have properties like text
   * annotations attached to it.
   *
   * <pre>
   * &lt;complexType name=&quot;VideoSegmentType&quot;&gt;
   *   &lt;complexContent&gt;
   *       &lt;extension base=&quot;mpeg7:SegmentType&quot;&gt;
   *           &lt;sequence&gt;
   *               &lt;choice minOccurs=&quot;0&quot;&gt;
   *                   &lt;element name=&quot;MediaTime&quot; type=&quot;mpeg7:MediaTimeType&quot;/&gt;
   *                   &lt;element name=&quot;TemporalMask&quot; type=&quot;mpeg7:TemporalMaskType&quot;/&gt;
   *               &lt;/choice&gt;
   *               &lt;choice minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot;&gt;
   *                   &lt;element name=&quot;VisualDescriptor&quot; type=&quot;mpeg7:VisualDType&quot;/&gt;
   *                   &lt;element name=&quot;VisualDescriptionScheme&quot; type=&quot;mpeg7:VisualDSType&quot;/&gt;
   *                   &lt;element name=&quot;VisualTimeSeriesDescriptor&quot;
   *                   type=&quot;mpeg7:VisualTimeSeriesType&quot;/&gt;
   *               &lt;/choice&gt;
   *               &lt;element name=&quot;MultipleView&quot; type=&quot;mpeg7:MultipleViewType&quot;
   *               minOccurs=&quot;0&quot;/&gt;
   *               &lt;element name=&quot;Mosaic&quot; type=&quot;mpeg7:MosaicType&quot; minOccurs=&quot;0&quot;
   *               maxOccurs=&quot;unbounded&quot;/&gt;
   *               &lt;choice minOccurs=&quot;0&quot; maxOccurs=&quot;unbounded&quot;&gt;
   *                   &lt;element name=&quot;SpatialDecomposition&quot;
   *                   type=&quot;mpeg7:VideoSegmentSpatialDecompositionType&quot;/&gt;
   *                   &lt;element name=&quot;TemporalDecomposition&quot;
   *                   type=&quot;mpeg7:VideoSegmentTemporalDecompositionType&quot;/&gt;
   *                   &lt;element name=&quot;SpatioTemporalDecomposition&quot;
   *                   type=&quot;mpeg7:VideoSegmentSpatioTemporalDecompositionType&quot;/&gt;
   *                   &lt;element name=&quot;MediaSourceDecomposition&quot;
   *                   type=&quot;mpeg7:VideoSegmentMediaSourceDecompositionType&quot;/&gt;
   *               &lt;/choice&gt;
   *           &lt;/sequence&gt;
   *       &lt;/extension&gt;
   *   &lt;/complexContent&gt;
   * &lt;/complexType&gt;
   * </pre>
   */
  public interface VideoSegment extends Segment {
  
    /**
     * Returns <code>true</code> if there is a spatio temporal decomposition as part of this segment.
     *
     * @return <code>true</code> if there is a spatio temporal decomposition
     */
    boolean hasSpatioTemporalDecomposition();
  
    /**
     * Creates a spatio temporal decomposition in this video segment.
     *
     * @param gap
     *          <code>true</code> if there may be gap between the elements
     * @param overlap
     *          <code>true</code> if elements may overlap
     * @return the new decomposition
     * @throws IllegalStateException
     *           if there is already such a decomposition
     */
    SpatioTemporalDecomposition createSpatioTemporalDecomposition(boolean gap, boolean overlap)
            throws IllegalStateException;
  
    /**
     * Returns the spatio temporal decomposition that contains information about elements on the segment such as text
     * elements.
     *
     * @return the spatio temporal decomposition
     */
    SpatioTemporalDecomposition getSpatioTemporalDecomposition();
  
  }