001 /* =========================================================== 002 * JFreeChart : a free chart library for the Java(tm) platform 003 * =========================================================== 004 * 005 * (C) Copyright 2000-2007, by Object Refinery Limited and Contributors. 006 * 007 * Project Info: http://www.jfree.org/jfreechart/index.html 008 * 009 * This library is free software; you can redistribute it and/or modify it 010 * under the terms of the GNU Lesser General Public License as published by 011 * the Free Software Foundation; either version 2.1 of the License, or 012 * (at your option) any later version. 013 * 014 * This library is distributed in the hope that it will be useful, but 015 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 016 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 017 * License for more details. 018 * 019 * You should have received a copy of the GNU Lesser General Public 020 * License along with this library; if not, write to the Free Software 021 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 022 * USA. 023 * 024 * [Java is a trademark or registered trademark of Sun Microsystems, Inc. 025 * in the United States and other countries.] 026 * 027 * ------------- 028 * Timeline.java 029 * ------------- 030 * (C) Copyright 2000-2007, by Object Refinery Limited and Contributors. 031 * 032 * Original Author: Bill Kelemen; 033 * Contributor(s): David Gilbert (for Object Refinery Limited); 034 * 035 * $Id: Timeline.java,v 1.2.2.2 2007/02/02 14:32:42 mungady Exp $ 036 * 037 * Changes 038 * ------- 039 * 23-May-2003 : Version 1 (BK); 040 * 09-Sep-2003 : Changed some method and parameter names (DG); 041 * 02-Feb-2007 : Removed author tags all over JFreeChart sources (DG); 042 * 043 */ 044 045 package org.jfree.chart.axis; 046 047 import java.util.Date; 048 049 /** 050 * An interface that defines the contract for a Timeline. 051 * <P> 052 * A Timeline will present a series of values to be used for an axis. Each 053 * Timeline must provide transformation methods between domain values and 054 * timeline values. In theory many transformations are possible. This interface 055 * has been implemented completely in 056 * {@link org.jfree.chart.axis.SegmentedTimeline}. 057 * <P> 058 * A timeline can be used as parameter to a 059 * {@link org.jfree.chart.axis.DateAxis} to define the values that this axis 060 * supports. As an example, the {@link org.jfree.chart.axis.SegmentedTimeline} 061 * implements a timeline formed by segments of equal length (ex. days, hours, 062 * minutes) where some segments can be included in the timeline and others 063 * excluded. Therefore timelines like "working days" or "working hours" can be 064 * created where non-working days or non-working hours respectively can be 065 * removed from the timeline, and therefore from the axis. This creates a smooth 066 * plot with equal separation between all included segments. 067 * <P> 068 * Because Timelines were created mainly for Date related axis, values are 069 * represented as longs instead of doubles. In this case, the domain value is 070 * just the number of milliseconds since January 1, 1970, 00:00:00 GMT as 071 * defined by the getTime() method of {@link java.util.Date}. 072 * 073 * @see org.jfree.chart.axis.SegmentedTimeline 074 * @see org.jfree.chart.axis.DateAxis 075 */ 076 public interface Timeline { 077 078 /** 079 * Translates a millisecond (as defined by java.util.Date) into an index 080 * along this timeline. 081 * 082 * @param millisecond the millisecond. 083 * 084 * @return A timeline value. 085 */ 086 long toTimelineValue(long millisecond); 087 088 /** 089 * Translates a date into a value on this timeline. 090 * 091 * @param date the date. 092 * 093 * @return A timeline value 094 */ 095 long toTimelineValue(Date date); 096 097 /** 098 * Translates a value relative to this timeline into a domain value. The 099 * domain value obtained by this method is not always the same domain value 100 * that could have been supplied to 101 * translateDomainValueToTimelineValue(domainValue). 102 * This is because the original tranformation may not be complete 103 * reversable. 104 * 105 * @see org.jfree.chart.axis.SegmentedTimeline 106 * 107 * @param timelineValue a timeline value. 108 * 109 * @return A domain value. 110 */ 111 long toMillisecond(long timelineValue); 112 113 /** 114 * Returns <code>true</code> if a value is contained in the timeline values. 115 * 116 * @param millisecond the millisecond. 117 * 118 * @return <code>true</code> if value is contained in the timeline and 119 * <code>false</code> otherwise. 120 */ 121 boolean containsDomainValue(long millisecond); 122 123 /** 124 * Returns <code>true</code> if a date is contained in the timeline values. 125 * 126 * @param date the date to verify. 127 * 128 * @return <code>true</code> if value is contained in the timeline and 129 * <code>false</code> otherwise. 130 */ 131 boolean containsDomainValue(Date date); 132 133 /** 134 * Returns <code>true</code> if a range of values are contained in the 135 * timeline. 136 * 137 * @param fromMillisecond the start of the range to verify. 138 * @param toMillisecond the end of the range to verify. 139 * 140 * @return <code>true</code> if the range is contained in the timeline or 141 * <code>false</code> otherwise 142 */ 143 boolean containsDomainRange(long fromMillisecond, long toMillisecond); 144 145 /** 146 * Returns <code>true</code> if a range of dates are contained in the 147 * timeline. 148 * 149 * @param fromDate the start of the range to verify. 150 * @param toDate the end of the range to verify. 151 * 152 * @return <code>true</code> if the range is contained in the timeline or 153 * <code>false</code> otherwise 154 */ 155 boolean containsDomainRange(Date fromDate, Date toDate); 156 157 }