001 /* =========================================================== 002 * JFreeChart : a free chart library for the Java(tm) platform 003 * =========================================================== 004 * 005 * (C) Copyright 2000-2005, 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-2004, 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.1 2005/10/25 20:37:34 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 * 042 */ 043 044 package org.jfree.chart.axis; 045 046 import java.util.Date; 047 048 /** 049 * An interface that defines the contract for a Timeline. 050 * <P> 051 * A Timeline will present a series of values to be used for an axis. Each 052 * Timeline must provide transformation methods between domain values and 053 * timeline values. In theory many transformations are possible. This interface 054 * has been implemented completely in 055 * {@link org.jfree.chart.axis.SegmentedTimeline}. 056 * <P> 057 * A timeline can be used as parameter to a 058 * {@link org.jfree.chart.axis.DateAxis} to define the values that this axis 059 * supports. As an example, the {@link org.jfree.chart.axis.SegmentedTimeline} 060 * implements a timeline formed by segments of equal length (ex. days, hours, 061 * minutes) where some segments can be included in the timeline and others 062 * excluded. Therefore timelines like "working days" or "working hours" can be 063 * created where non-working days or non-working hours respectively can be 064 * removed from the timeline, and therefore from the axis. This creates a smooth 065 * plot with equal separation between all included segments. 066 * <P> 067 * Because Timelines were created mainly for Date related axis, values are 068 * represented as longs instead of doubles. In this case, the domain value is 069 * just the number of milliseconds since January 1, 1970, 00:00:00 GMT as 070 * defined by the getTime() method of {@link java.util.Date}. 071 * 072 * @see org.jfree.chart.axis.SegmentedTimeline 073 * @see org.jfree.chart.axis.DateAxis 074 * 075 * @author Bill Kelemen 076 */ 077 public interface Timeline { 078 079 /** 080 * Translates a millisecond (as defined by java.util.Date) into an index 081 * along this timeline. 082 * 083 * @param millisecond the millisecond. 084 * 085 * @return A timeline value. 086 */ 087 long toTimelineValue(long millisecond); 088 089 /** 090 * Translates a date into a value on this timeline. 091 * 092 * @param date the date. 093 * 094 * @return A timeline value 095 */ 096 long toTimelineValue(Date date); 097 098 /** 099 * Translates a value relative to this timeline into a domain value. The 100 * domain value obtained by this method is not always the same domain value 101 * that could have been supplied to 102 * translateDomainValueToTimelineValue(domainValue). 103 * This is because the original tranformation may not be complete 104 * reversable. 105 * 106 * @see org.jfree.chart.axis.SegmentedTimeline 107 * 108 * @param timelineValue a timeline value. 109 * 110 * @return A domain value. 111 */ 112 long toMillisecond(long timelineValue); 113 114 /** 115 * Returns <code>true</code> if a value is contained in the timeline values. 116 * 117 * @param millisecond the millisecond. 118 * 119 * @return <code>true</code> if value is contained in the timeline and 120 * <code>false</code> otherwise. 121 */ 122 boolean containsDomainValue(long millisecond); 123 124 /** 125 * Returns <code>true</code> if a date is contained in the timeline values. 126 * 127 * @param date the date to verify. 128 * 129 * @return <code>true</code> if value is contained in the timeline and 130 * <code>false</code> otherwise. 131 */ 132 boolean containsDomainValue(Date date); 133 134 /** 135 * Returns <code>true</code> if a range of values are contained in the 136 * timeline. 137 * 138 * @param fromMillisecond the start of the range to verify. 139 * @param toMillisecond the end of the range to verify. 140 * 141 * @return <code>true</code> if the range is contained in the timeline or 142 * <code>false</code> otherwise 143 */ 144 boolean containsDomainRange(long fromMillisecond, long toMillisecond); 145 146 /** 147 * Returns <code>true</code> if a range of dates are contained in the 148 * timeline. 149 * 150 * @param fromDate the start of the range to verify. 151 * @param toDate the end of the range to verify. 152 * 153 * @return <code>true</code> if the range is contained in the timeline or 154 * <code>false</code> otherwise 155 */ 156 boolean containsDomainRange(Date fromDate, Date toDate); 157 158 }