it.tidalwave.metadata.MetadataFactory Maven / Gradle / Ivy

Go to download
/*******************************************************************************
 *
 * blueMarine - open source photo workflow
 * =======================================
 *
 * Copyright (C) 2003-2009 by Fabrizio Giudici
 * Project home page: http://bluemarine.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. 
 *
 *******************************************************************************
 *
 * $Id: MetadataFactory.java,v d60681e7fc1d 2009/09/17 23:59:23 fabrizio $
 *
 ******************************************************************************/
package it.tidalwave.metadata;

import javax.annotation.Nonnull;
import org.openide.util.Lookup;
import org.openide.loaders.DataObject;

/*******************************************************************************
 *
 * A factory for {@link Metadata}. This interface is only for providers of 
 * {@link DataObject} implementations (see the {@link Metadata} documentation
 * for more information). 

 *
 * {@link Metadata} instances should be created together with their bound
 * {@link DataObject}: there are no performance issues, since items inside
 * a {@link Metadata} instance are lazily loaded. Here is an example of how to
 * implement a {@link DataObject} with {@link Metadata} support:
 * 
 *  * public class MyDataObject extends MultiDataObject
 *   {
 *     private final Metadata metadata;
 *     private final Lookup lookup;
 *     
 *     protected MyDataObject (final FileObject fileObject, final MultiFileLoader fileLoader) 
 *       throws DataObjectExistsException
 *       {
 *         super(fileObject, fileLoader);
 *         metadata = MetadataFactory.Locator.findMetadataFactory().findOrCreateMetadata(this);
 *         lookup = new ProxyLookup(super.getLookup(), Lookups.fixed(metadata));
 *       }
 *     
 *     @Override
 *     public Lookup getLookup()
 *       {
 *         return lookup;
 *       }
 *   }
 * 
 *
 * @stereotype factory
 * @assoc      1 "" 1 org.openide.loaders.DataObject
 *
 * @author  Fabrizio Giudici
 * @version $Id: MetadataFactory.java,v d60681e7fc1d 2009/09/17 23:59:23 fabrizio $
 *
 ******************************************************************************/
public interface MetadataFactory 
  {
    /***************************************************************************
     *
     * Finds or creates a {@link Metadata} instance for the given {@link DataObject}. 
     * If this method is called for the first time on the given 
     * DataObject, a new instance of Metadata is 
     * created.
     * Multiple invocations of this method will return the same instance of the
     * Metadata object. 
     *  
     * @param   dataObject  the {@link DataObject}
     * @return              the {@link Metadata}
     *
     **************************************************************************/
    @Nonnull 
    public Metadata findOrCreateMetadata (@Nonnull DataObject dataObject);
    
    /***************************************************************************
     *
     * The service locator for {@link MetadataFactory}.
     *
     * @hidden
     *
     **************************************************************************/
    public final static class Locator
      {
        private Locator()
          {
          }
        
        @Nonnull 
        public final static MetadataFactory findMetadataFactory()
          {
            final MetadataFactory metadataFactory = Lookup.getDefault().lookup(MetadataFactory.class);

            if (metadataFactory == null)
              {
                throw new RuntimeException("MetadataFactory not found");
              }

            return metadataFactory;
          }
      }
  }