it.tidalwave.metadata.TimestampProvider 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: TimestampProvider.java,v d60681e7fc1d 2009/09/17 23:59:23 fabrizio $
 *
 ******************************************************************************/
package it.tidalwave.metadata;

import java.util.Date;
import javax.annotation.Nonnull;
import org.openide.util.Lookup;

/*******************************************************************************
 *
 * This class provides the value of the current timestamp with the capability of
 * "freezing" it for a short period of time; in this way, a set of operations 
 * that should be performed as a single unit of work can be timestamped with the
 * same value.
 * 
 * Whenever a timestamp must be "frozen", the method {@link #sample()} must be
 * called, and the frozen value can be read with {@link #getSampledTimestamp()}.
 * 
 * Also a method {@link #getTimestamp()} is provided which returns the running
 * timestamp; using it in place of System.currentTimeMillis() makes it 
 * possible to mock the timestamp provider and thus run tests in a more 
 * controlled environment.
 *
 * @author  Fabrizio Giudici
 * @version $Id: TimestampProvider.java,v d60681e7fc1d 2009/09/17 23:59:23 fabrizio $
 *
 ******************************************************************************/
public interface TimestampProvider 
  {
    /***************************************************************************
     *
     * Returns the current timestamp. 
     * 
     * @return  the timestamp
     *
     **************************************************************************/
    @Nonnull 
    public Date getTimestamp();
    
    /***************************************************************************
     *
     * Returns the sampled timestamp. Every thread calling this method will get
     * the same value until {@link #sample()} is called again.
     * 
     * @return  the timestamp
     *
     **************************************************************************/
    @Nonnull 
    public Date getSampledTimestamp();
    
    /***************************************************************************
     *
     * Samples the current time. The thread calling {@link #sample()} will get
     * the same value returning from {@link #getSampledTimestamp()} until the 
     * next invocation of this method.
     * 
     * @return  the timestamp
     *
     **************************************************************************/
    @Nonnull 
    public Date sample();
    
    /***************************************************************************
     *
     * The Service Locator for {@link TimestampProvider}.
     *
     * @hidden
     *
     **************************************************************************/
    public static final class Locator
      {
        private Locator()
          {
          }
        
        @Nonnull 
        public static TimestampProvider findTimestampProvider()
          {
            final TimestampProvider timestampProvider = Lookup.getDefault().lookup(TimestampProvider.class);
            
            if (timestampProvider == null)
              {
                throw new RuntimeException("Cannot find TimestampProvider");  
              }  
            
            return timestampProvider;
          }
      }
  }