Frames | No Frames |
1: /* =========================================================== 2: * JFreeChart : a free chart library for the Java(tm) platform 3: * =========================================================== 4: * 5: * (C) Copyright 2000-2005, by Object Refinery Limited and Contributors. 6: * 7: * Project Info: http://www.jfree.org/jfreechart/index.html 8: * 9: * This library is free software; you can redistribute it and/or modify it 10: * under the terms of the GNU Lesser General Public License as published by 11: * the Free Software Foundation; either version 2.1 of the License, or 12: * (at your option) any later version. 13: * 14: * This library is distributed in the hope that it will be useful, but 15: * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 16: * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 17: * License for more details. 18: * 19: * You should have received a copy of the GNU Lesser General Public 20: * License along with this library; if not, write to the Free Software 21: * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 22: * USA. 23: * 24: * [Java is a trademark or registered trademark of Sun Microsystems, Inc. 25: * in the United States and other countries.] 26: * 27: * ------------- 28: * Timeline.java 29: * ------------- 30: * (C) Copyright 2000-2004, by Object Refinery Limited and Contributors. 31: * 32: * Original Author: Bill Kelemen; 33: * Contributor(s): David Gilbert (for Object Refinery Limited); 34: * 35: * $Id: Timeline.java,v 1.2.2.1 2005/10/25 20:37:34 mungady Exp $ 36: * 37: * Changes 38: * ------- 39: * 23-May-2003 : Version 1 (BK); 40: * 09-Sep-2003 : Changed some method and parameter names (DG); 41: * 42: */ 43: 44: package org.jfree.chart.axis; 45: 46: import java.util.Date; 47: 48: /** 49: * An interface that defines the contract for a Timeline. 50: * <P> 51: * A Timeline will present a series of values to be used for an axis. Each 52: * Timeline must provide transformation methods between domain values and 53: * timeline values. In theory many transformations are possible. This interface 54: * has been implemented completely in 55: * {@link org.jfree.chart.axis.SegmentedTimeline}. 56: * <P> 57: * A timeline can be used as parameter to a 58: * {@link org.jfree.chart.axis.DateAxis} to define the values that this axis 59: * supports. As an example, the {@link org.jfree.chart.axis.SegmentedTimeline} 60: * implements a timeline formed by segments of equal length (ex. days, hours, 61: * minutes) where some segments can be included in the timeline and others 62: * excluded. Therefore timelines like "working days" or "working hours" can be 63: * created where non-working days or non-working hours respectively can be 64: * removed from the timeline, and therefore from the axis. This creates a smooth 65: * plot with equal separation between all included segments. 66: * <P> 67: * Because Timelines were created mainly for Date related axis, values are 68: * represented as longs instead of doubles. In this case, the domain value is 69: * just the number of milliseconds since January 1, 1970, 00:00:00 GMT as 70: * defined by the getTime() method of {@link java.util.Date}. 71: * 72: * @see org.jfree.chart.axis.SegmentedTimeline 73: * @see org.jfree.chart.axis.DateAxis 74: * 75: * @author Bill Kelemen 76: */ 77: public interface Timeline { 78: 79: /** 80: * Translates a millisecond (as defined by java.util.Date) into an index 81: * along this timeline. 82: * 83: * @param millisecond the millisecond. 84: * 85: * @return A timeline value. 86: */ 87: long toTimelineValue(long millisecond); 88: 89: /** 90: * Translates a date into a value on this timeline. 91: * 92: * @param date the date. 93: * 94: * @return A timeline value 95: */ 96: long toTimelineValue(Date date); 97: 98: /** 99: * 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: }