Frames | No Frames |
1: /* =========================================================== 2: * JFreeChart : a free chart library for the Java(tm) platform 3: * =========================================================== 4: * 5: * (C) Copyright 2000-2007, 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-2007, by Object Refinery Limited and Contributors. 31: * 32: * Original Author: Bill Kelemen; 33: * Contributor(s): David Gilbert (for Object Refinery Limited); 34: * 35: * Changes 36: * ------- 37: * 23-May-2003 : Version 1 (BK); 38: * 09-Sep-2003 : Changed some method and parameter names (DG); 39: * 02-Feb-2007 : Removed author tags all over JFreeChart sources (DG); 40: * 41: */ 42: 43: package org.jfree.chart.axis; 44: 45: import java.util.Date; 46: 47: /** 48: * An interface that defines the contract for a Timeline. 49: * <P> 50: * A Timeline will present a series of values to be used for an axis. Each 51: * Timeline must provide transformation methods between domain values and 52: * timeline values. In theory many transformations are possible. This interface 53: * has been implemented completely in 54: * {@link org.jfree.chart.axis.SegmentedTimeline}. 55: * <P> 56: * A timeline can be used as parameter to a 57: * {@link org.jfree.chart.axis.DateAxis} to define the values that this axis 58: * supports. As an example, the {@link org.jfree.chart.axis.SegmentedTimeline} 59: * implements a timeline formed by segments of equal length (ex. days, hours, 60: * minutes) where some segments can be included in the timeline and others 61: * excluded. Therefore timelines like "working days" or "working hours" can be 62: * created where non-working days or non-working hours respectively can be 63: * removed from the timeline, and therefore from the axis. This creates a smooth 64: * plot with equal separation between all included segments. 65: * <P> 66: * Because Timelines were created mainly for Date related axis, values are 67: * represented as longs instead of doubles. In this case, the domain value is 68: * just the number of milliseconds since January 1, 1970, 00:00:00 GMT as 69: * defined by the getTime() method of {@link java.util.Date}. 70: * 71: * @see org.jfree.chart.axis.SegmentedTimeline 72: * @see org.jfree.chart.axis.DateAxis 73: */ 74: public interface Timeline { 75: 76: /** 77: * Translates a millisecond (as defined by java.util.Date) into an index 78: * along this timeline. 79: * 80: * @param millisecond the millisecond. 81: * 82: * @return A timeline value. 83: */ 84: long toTimelineValue(long millisecond); 85: 86: /** 87: * Translates a date into a value on this timeline. 88: * 89: * @param date the date. 90: * 91: * @return A timeline value 92: */ 93: long toTimelineValue(Date date); 94: 95: /** 96: * Translates a value relative to this timeline into a domain value. The 97: * domain value obtained by this method is not always the same domain value 98: * that could have been supplied to 99: * translateDomainValueToTimelineValue(domainValue). 100: * This is because the original tranformation may not be complete 101: * reversable. 102: * 103: * @see org.jfree.chart.axis.SegmentedTimeline 104: * 105: * @param timelineValue a timeline value. 106: * 107: * @return A domain value. 108: */ 109: long toMillisecond(long timelineValue); 110: 111: /** 112: * Returns <code>true</code> if a value is contained in the timeline values. 113: * 114: * @param millisecond the millisecond. 115: * 116: * @return <code>true</code> if value is contained in the timeline and 117: * <code>false</code> otherwise. 118: */ 119: boolean containsDomainValue(long millisecond); 120: 121: /** 122: * Returns <code>true</code> if a date is contained in the timeline values. 123: * 124: * @param date the date to verify. 125: * 126: * @return <code>true</code> if value is contained in the timeline and 127: * <code>false</code> otherwise. 128: */ 129: boolean containsDomainValue(Date date); 130: 131: /** 132: * Returns <code>true</code> if a range of values are contained in the 133: * timeline. 134: * 135: * @param fromMillisecond the start of the range to verify. 136: * @param toMillisecond the end of the range to verify. 137: * 138: * @return <code>true</code> if the range is contained in the timeline or 139: * <code>false</code> otherwise 140: */ 141: boolean containsDomainRange(long fromMillisecond, long toMillisecond); 142: 143: /** 144: * Returns <code>true</code> if a range of dates are contained in the 145: * timeline. 146: * 147: * @param fromDate the start of the range to verify. 148: * @param toDate the end of the range to verify. 149: * 150: * @return <code>true</code> if the range is contained in the timeline or 151: * <code>false</code> otherwise 152: */ 153: boolean containsDomainRange(Date fromDate, Date toDate); 154: 155: }