it.tidalwave.metadata.spi.MetadataItemProvider Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of it-tidalwave-metadata-spi Show documentation
The newest version!
/***********************************************************************************************************************
 *
 * blueMarine Metadata - open source media workflow
 * Copyright (C) 2007-2011 by Tidalwave s.a.s. (http://www.tidalwave.it)
 *
 ***********************************************************************************************************************
 *
 * Licensed under the Apache 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://www.apache.org/licenses/LICENSE-2.0
 *
 * 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.
 *
 ***********************************************************************************************************************
 *
 * WWW: http://bluemarine.tidalwave.it
 * SCM: https://kenai.com/hg/bluemarine~metadata-src
 *
 **********************************************************************************************************************/
package it.tidalwave.metadata.spi;

import javax.annotation.Nonnull;
import java.util.List;
import java.util.Set;
import org.openide.loaders.DataObject;
import it.tidalwave.metadata.Metadata.FindOption;
import it.tidalwave.metadata.Metadata.StoreOption;
import it.tidalwave.metadata.MetadataItemHolder;

/*******************************************************************************
 *
 * This interface must be implemented by metadata providers. A metadata provider
 * returns a specific item of metadata for a given {@link DataObject}. Usually 
 * providers aggregate the information from {@link MetadataItemSource}s.
 * 
 * In most cases, it suffices to extend {@link MetadataItemProviderSupport} 
 * which only requires a few lines of code.
 *
 * note  Manages the existence of an Item
 * @stereotype factory
 * @assoc 1 "delegates retrieval" 1..* it.tidalwave.metadata.spi.MetadataItemSource
 * @assoc 1 "delegates storage" 1..* it.tidalwave.metadata.spi.MetadataItemSink
 * 
 * @author  Fabrizio Giudici
 * @version $Id$
 *
 ******************************************************************************/
public interface MetadataItemProvider
  {
    /***************************************************************************
     *
     * Returns the {@link Class} representing the metadata item managed by 
     * this provider.
     * 
     * @return  the metadata item class
     * 
     **************************************************************************/
    @Nonnull 
    public Class getItemClass();
    
    /***************************************************************************
     *
     * Finds all the items of the managed class for a {@link DataObject}. If no
     * items are found, a list containing a single empty item (returning
     * {@link it.tidalwave.metadata.MetadataItem#isAvailable() isAvailable()} == false)
     * must be returned.

     * If multiple items are returned, the ones with the most recent modification
     * time come first.
     * While this method conceptually returns a set (that is, duplicates items are 
     * not allowed in the result), a {@link List} is used instead of a {@link Set}
     * since the contents are not immutable.
     * 
     * @param   dataObject  the bound dataObject
     * @param   sourceType  the source type
     * @param   options     the options (see {@link it.tidalwave.metadata.Metadata#FindOption})
     * @return              a list of holders containing the metadata items
     * 
     **************************************************************************/
    @Nonnull 
    public List> findOrCreateItems (@Nonnull DataObject dataObject, 
                                                             @Nonnull FindOption ... options);
    
    /***************************************************************************
     *
     * Stores an item bound to a given {@link DataObject}.
     * 
     * @param   dataObject  the bound dataObject
     * @param   holder      the metadata holder
     * @param   options     the options (see {@link it.tidalwave.metadata.Metadata#StoreOption})
     * @return              the number of sinks where the item has been stored
     * 
     **************************************************************************/
    public int storeItem (@Nonnull DataObject dataObject, 
                          @Nonnull MetadataItemHolder holder, 
                          @Nonnull StoreOption ... options);
  }