it.tidalwave.metadata.spi.MetadataItemSource 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.Collection;
import org.openide.loaders.DataObject;
import it.tidalwave.metadata.Metadata.FindOption;
import it.tidalwave.metadata.Metadata.StorageType;
import it.tidalwave.metadata.MetadataItemHolder;

/*******************************************************************************
 *
 * This interface represents a concrete source of a metadata item. A concrete
 * source is able to read the item from a file (embedded in a JPEG, or from
 * a XMP file, etc...) or a database or another persistence facility.

 * Metadata item providers can provide any kind of object following these
 * rules:
 * 
 * 
 * they must comply with the JavaBean specifications (events and listeners)
 *     (but see notes below);
 * for each provided property, a special "available" property must be defined;
 * 
 * 
 * While the returned object must be compliant with JavaBeans specifications, it
 * is not necessary that they are directly implemented in the original class; 
 * instead, they can be dynamically provided by bytecode manipulation - see 
 * {@link it.tidalwave.metadata.spi.MetadataItemEnhancer MetadataItemEnhancer}.
 * 
 * For instance, this is a valid class for representing a metadata item:
 * 
 *  * public class ExampleMetadataItem implements Serializable
 *   {
 *     private String name;
 *     private boolean nameAvailable;
 *     
 *     public void setName (final String name)
 *       {
 *         this.name = name;    
 *       }
 *     
 *     public String getName()
 *       {
 *         return name;    
 *       }
 * 
 *     public boolean isNameAvailable() 
 *       {
 *         return nameAvailable;
 *       }
 * 
 *     public void setNameAvailable (final boolean nameAvailable) 
 *       {
 *         this.nameAvailable = nameAvailable;
 *       }
 *   }
 * 
 * 
 * @stereotype factory
 *
 * @author  Fabrizio Giudici
 * @version $Id$
 *
 ******************************************************************************/
public interface MetadataItemSource
  {
    /***************************************************************************
     *
     * Returns the {@link Class} representing the metadata item created by this 
     * source.
     * 
     * @return  the metadata item class
     * 
     **************************************************************************/
    @Nonnull 
    public Class getItemClass();
    
    /***************************************************************************
     *
     * Return the type of this source.
     * 
     * @return  the source type
     * 
     **************************************************************************/
    @Nonnull 
    public StorageType getType();
    
    /***************************************************************************
     *
     * Return the name of this source.
     * 
     * @return  the source name
     * 
     **************************************************************************/
    @Nonnull 
    public String getName();
    
    /***************************************************************************
     *
     * Loads an item for a given {@link DataObject}. This method must return
     * an empty collection if the item is not available.
     * 
     * @param  dataObject  the object to load the item from
     * @param  options     the options
     * @return             the item (null if not available)
     * 
     **************************************************************************/
    @Nonnull 
    public Collection> loadMetadataItems (@Nonnull DataObject dataObject,
                                                                             @Nonnull FindOption ... options)
      throws Exception;
  }