timeseries.java

Web图形化的Java库

        return result;

    }

    /**
     * Returns the index for the item (if any) that corresponds to a time period.
     *
     * @param period  the time period (<code>null</code> not permitted).
     *
     * @return The index.
     */
    public int getIndex(RegularTimePeriod period) {

        // check argument...
        if (period == null) {
            throw new IllegalArgumentException("TimeSeries.getIndex(...) : null not permitted.");
        }
        
        // fetch the value...
        TimeSeriesDataItem dummy = new TimeSeriesDataItem(period, new Integer(0));
        int index = Collections.binarySearch(data, dummy);
        return index;

    }

    /**
     * Returns the value at the specified index.
     *
     * @param index  index of a value.
     *
     * @return the value at the specified index.
     */
    public Number getValue(int index) {
        return getDataPair(index).getValue();
    }

    /**
     * Returns the value for a time period.
     *
     * @param period  time period to lookup.
     *
     * @return the value or <code>null</code> if the time period is not in the series.
     */
    public Number getValue(RegularTimePeriod period) {

        int index = getIndex(period);
        if (index >= 0) {
            return getValue(index);
        }
        else {
            return null;
        }

    }

    /**
     * Adds a data item to the series.
     *
     * @param pair  the (timeperiod, value) pair.
     *
     * @throws SeriesException if there is a problem adding the data.
     */
    public void add(TimeSeriesDataItem pair) throws SeriesException {

        // check arguments...
        if (pair == null) {
            throw new IllegalArgumentException("TimeSeries.add(...): null item not allowed.");
        }

        if (!pair.getPeriod().getClass().equals(timePeriodClass)) {
            String message = "TimeSeries.add(): you are trying to add data where the time ";
            message = message + "period class is " + pair.getPeriod().getClass().getName() + ", ";
            message = message + "but the TimeSeries is expecting an instance of "
                              + timePeriodClass.getName() + ".";
            throw new SeriesException(message);
        }


        // make the change (if it's not a duplicate time period)...
        int index = Collections.binarySearch(data, pair);
        if (index < 0) {
            this.data.add(-index - 1, pair);

            // check if this addition will exceed the maximum item count...
            if (getItemCount() > this.maximumItemCount) {
                this.data.remove(0);
            }

            // check if there are any values earlier than specified by the history count...
            ageHistoryCountItems();
            fireSeriesChanged();
        }
        else {
            throw new SeriesException("TimeSeries.add(...): time period already exists.");
        }

    }

    /**
     * Adds a new data item to the series.
     *
     * @param period  the time period.
     * @param value  the value.
     *
     * @throws SeriesException if there is a problem adding the data.
     */
    public void add(RegularTimePeriod period, double value) throws SeriesException {

        TimeSeriesDataItem pair = new TimeSeriesDataItem(period, value);
        add(pair);

    }

    /**
     * Adds a new data item to the series.
     *
     * @param period  the time period.
     * @param value  the value.
     *
     * @throws SeriesException if there is a problem adding the data.
     */
    public void add(RegularTimePeriod period, Number value) throws SeriesException {

        TimeSeriesDataItem pair = new TimeSeriesDataItem(period, value);
        add(pair);

    }

    /**
     * Updates (changes) the value for a time period.  Ignores the update if
     * the period does not exist.
     *
     * @param period  the period to update.
     * @param value  the new value.
     *
     * @throws SeriesException if there is a problem adding the data.
     */
    public void update(RegularTimePeriod period, Number value) throws SeriesException {

        TimeSeriesDataItem temp = new TimeSeriesDataItem(period, value);
        int index = Collections.binarySearch(data, temp);
        if (index >= 0) {
            TimeSeriesDataItem pair = (TimeSeriesDataItem) data.get(index);
            pair.setValue(value);
            fireSeriesChanged();
        }
        else {
            throw new SeriesException("TimeSeries.update(TimePeriod, Number): "
                                      + "period does not exist.");
        }

    }

    /**
     * Updates (changes) the value of a data pair.
     *
     * @param index  the index of the data pair to update.
     * @param value  the new value.
     */
    public void update(int index, Number value) {

        TimeSeriesDataItem pair = getDataPair(index);
        pair.setValue(value);
        fireSeriesChanged();

    }

    /**
     * Adds or updates data from one series to another.  Returns another series
     * containing the values that were overwritten.
     *
     * @param series  the series to merge with this.
     *
     * @return series containing the values that were overwritten.
     */
    public TimeSeries addAndOrUpdate(TimeSeries series) {

        TimeSeries overwritten = new TimeSeries("Overwritten values from: " + getName());

        for (int i = 0; i < series.getItemCount(); i++) {
            TimeSeriesDataItem pair = series.getDataPair(i);
            TimeSeriesDataItem oldPair = addOrUpdate(pair.getPeriod(), pair.getValue());
            if (oldPair != null) {
                try {
                    overwritten.add(oldPair);
                }
                catch (SeriesException e) {  // should not get here...
                    System.err.println("TimeSeries.addAndOrUpdate(series): "
                                       + "unable to add data to overwritten series.");
                }
            }
        }
        return overwritten;
    }

    /**
     * Adds or updates the times series.
     *
     * @param period  the time period to add/update.
     * @param value  the new value.
     *
     * @return a copy of the overwritten data pair (or null).
     */
    public TimeSeriesDataItem addOrUpdate(RegularTimePeriod period, Number value) {

        TimeSeriesDataItem overwritten = null;

        TimeSeriesDataItem key = new TimeSeriesDataItem(period, value);
        int index = Collections.binarySearch(data, key);
        if (index >= 0) {
            TimeSeriesDataItem existing = (TimeSeriesDataItem) data.get(index);
            overwritten = (TimeSeriesDataItem) existing.clone();
            existing.setValue(value);
            ageHistoryCountItems();
            fireSeriesChanged();
        }
        else {
            data.add(-index - 1, new TimeSeriesDataItem(period, value));
            ageHistoryCountItems();
            fireSeriesChanged();
        }
        return overwritten;

    }

    /**
     * age items in the series.  Ensure that the timespan from the youngest to the oldest record
     * in the series does not exceed history count.  oldest items will be removed if required
     */
    public void ageHistoryCountItems() {
      // check if there are any values earlier than specified by the history count...
      if ((getItemCount() > 1) && (this.historyCount > 0)) {
        long latest = getTimePeriod(getItemCount() - 1).getSerialIndex();
        while ((latest - getTimePeriod(0).getSerialIndex()) >= historyCount) {
          this.data.remove(0);
        }
      }
    }

    /**
     * age items in the series.  Ensure that the timespan from the supplied time to the
     * oldest record in the series does not exceed history count.  oldest items will be
     * removed if required
     *
     * @param latest the time to be compared against when aging data.
     */
    public void ageHistoryCountItems(long latest) {
      // check if there are any values earlier than specified by the history count...
      if ((getItemCount() > 1) && (this.historyCount > 0)) {
        while ((latest - getTimePeriod(0).getSerialIndex()) >= historyCount) {
          this.data.remove(0);
        }
      }
    }

    /**
     * Deletes data for the given time period.
     *
     * @param period  period to delete.
     */
    public void delete(RegularTimePeriod period) {
        int index = getIndex(period);
        data.remove(index);
    }

    /**
     * Deletes data from start until end index (end inclusive).
     *
     * @param start  the index of the first period to delete.
     * @param end  the index of the last period to delete.
     */
    public void delete(int start, int end) {

        for (int i = 0; i <= (end - start); i++) {
            this.data.remove(start);
        }
        fireSeriesChanged();

    }

    /**
     * Returns a clone of the time series.
     * <P>
     * Notes:
     * <ul>
     *   <li>no need to clone the domain and range descriptions, since String object is 
     *     immutable;</li>
     *   <li>we pass over to the more general method clone(start, end).</li>
     * </ul>
     *
     * @return a clone of the time series.
     */
    public Object clone() {

        Object clone = createCopy(0, getItemCount() - 1);
        return clone;

    }

    /**
     * Creates a new timeseries by copying a subset of the data in this time
     * series.
     *
     * @param start  the index of the first time period to copy.
     * @param end  the index of the last time period to copy.
     *
     * @return a series containing a copy of this times series from start until end.
     */
    public TimeSeries createCopy(int start, int end) {

        TimeSeries copy = (TimeSeries) super.clone();

        copy.data = new java.util.ArrayList();
        if (data.size() > 0) {
            for (int index = start; index <= end; index++) {
                TimeSeriesDataItem item = (TimeSeriesDataItem) this.data.get(index);
                TimeSeriesDataItem clone = (TimeSeriesDataItem) item.clone();
                try {
                    copy.add(clone);
                }
                catch (SeriesException e) {
                    System.err.println("TimeSeries.createCopy(): unable to add cloned data pair.");
                }
            }
        }

        return copy;

    }

    /**
     * Creates a new timeseries by copying a subset of the data in this time series.
     *
     * @param start  the first time period to copy.
     * @param end  the last time period to copy.
     *
     * @return a time series containing a copy of this time series from start until end.
     */
    public TimeSeries createCopy(RegularTimePeriod start, RegularTimePeriod end) {

        int startIndex = getIndex(start);
        if (startIndex < 0) {
            startIndex = -(startIndex + 1);
        }
        int endIndex = getIndex(end);
        if (endIndex < 0) {               // end period is not in original series
            endIndex = -(endIndex + 1);  // this gives first item AFTER end period
            endIndex = endIndex - 1;      // so this gives last item BEFORE end period
        }
        
        TimeSeries result = createCopy(startIndex, endIndex);        
        
        return result;

    }

    /**
     * Tests the series for equality with another object.
     *
     * @param object  the object.
     *
     * @return <code>true</code> or <code>false</code>.
     */
    public boolean equals(Object object) {

        if (object == null) {
            return false;
        }

        if (object == this) {
            return true;
        }

        boolean result = super.equals(object);

        if (object instanceof TimeSeries) {
            TimeSeries s = (TimeSeries) object;
            boolean b1 = getDomainDescription().equals(s.getDomainDescription());
            boolean b2 = getRangeDescription().equals(s.getRangeDescription());
            boolean b3 = getClass().equals(s.getClass());
            boolean b4 = getHistoryCount() == s.getHistoryCount();
            boolean b5 = getMaximumItemCount() == s.getMaximumItemCount();

            result = result && b1 && b2 && b3 && b4 && b5;

            if (result == true) {

                boolean match = true;
                int count = getItemCount();
                if (count == s.getItemCount()) {
                    for (int i = 0; i < count; i++) {
                        match = match && getDataPair(i).equals(s.getDataPair(i));
                        if (!match) {
                            continue;
                        }
                    }
                    result = match;
                }
                else {
                    result = false;
                }
            }
        }

        return result;

    }

}