Timeline Markers: Code Example

This code example implements a provider class which defines markers for use in the timeline control of ContentCreator's Multi-Perspective Preview (MPP) toolbar.

As both kinds of timeline provider follow the same structure and differ only in directionality of temporal range and timeline entries, this code example will implement a generic, future timeline provider only. Directionality requirements of both timeline provider interfaces are outlined below:

General Considerations

Both timeline providers return a Collection of TimelineEntry objects.

A timeline's point of origin is always the time at which the MPP timeline was last drawn or updated (in the examples below, this time is called "now"). A timeline provider may specify a range in milliseconds which sets the timeline's scale.

• If a range of zero (0) is specified, ContentCreator will place the timeline entry farthest from the point of origin at the end of the timeline and all other timeline entries within this range accordingly.
• If a range greater than zero (0) is specified, ContentCreator will use this range as the timeline's end point and place any timeline entries within this range accordingly.

Provided timeline entries which do not fall between the point of origin (now) and the timeline's end point as defined by the range may not appear on the timeline.

HistoryTimelineProvider

Developer API documentation: HistoryTimelineProvider

A HistoryTimelineProvider implementation specifies timeline entries in the past, relative to the date and time the MPP timeline was last refreshed.

This class' range specification will be set before the current time ("now") in order to produce an end point to the left of the point of origin. Timeline entries are expected to have a date/time value lower than the current date and time.

FutureTimelineProvider

Developer API documentation: FutureTimelineProvider

A FutureTimelineProvider implementation specifies timeline entries in the future, relative to the date and time the MPP timeline was last refreshed.

This class' range specification is set after the current time ("now") in order to produce an end point to the right of the point of origin. Timeline entries are expected to have a date/time value higher than the current date and time.

Creating TimelineEntry Objects

Developer API documentation: TimelineEntry (Factory)

Timeline provider classes should provide one or more TimelineEntry objects. These entries are instantiated using the factory class TimelineEntry.Factory.

A TimelineEntry object can be configured with the timestamp of a Date or a Revision object and obtained by using the factory class' static create(Date) and create(Revision) methods.

Using a Date object:

// Configure a TimelineEntry with the current time plus one day.
final TimelineEntry dateEntry = TimelineEntry.Factory.create(
    new Date(System.currentTimeMillis() + 24 * 60 * 60 * 1000)
);

Using a Revision object:

Because revisions represent past element states, it is ineffective to use revision-based timeline entries within the context of a FutureTimelineProvider class.

// Assume the object
//     IDProvider anElement
// exists in the scope of this code snippet.

// Retrieve the element's release revision.
final Revision elementReleaseRevision = anElement.getReleaseRevision();

if (elementReleaseRevision != null) {
    // Configure a TimelineEntry with the release revision.
    final TimelineEntry revisionEntry = TimelineEntry.Factory.create(elementReleaseRevision);
}

Code Example

A simple FutureTimelineProvider may be defined as such:

public class ExampleFutureTimelineProvider implements FutureTimelineProvider {

    private static final long MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;

    public void setUp(@NotNull final BaseContext context) {
        // Set up required persistence objects here.
    }

    public void tearDown() {
        // Clean up persistence objects used during run-time here.
    }

    public long getRange() {
        // Set the timeline's length to represent ten days.
        return 10 * MILLISECONDS_PER_DAY;
    }

    public Collection<TimelineEntry> getEntries(@NotNull final IDProvider element) {
        // Get the current Unix time in milliseconds
        final long unixTimeNow = System.currentTimeMillis();

        // Configure a few TimelineEntry objects that represent prime-numbered days
        // from the current time and return them in a list.
        return Arrays.asList(
            TimelineEntry.Factory.create(
                new Date(unixTimeNow + ( 2 * MILLISECONDS_PER_DAY ))
            ),
            TimelineEntry.Factory.create(
                new Date(unixTimeNow + ( 3 * MILLISECONDS_PER_DAY ))
            ),
            TimelineEntry.Factory.create(
                new Date(unixTimeNow + ( 5 * MILLISECONDS_PER_DAY ))
            ),
            TimelineEntry.Factory.create(
                new  Date(unixTimeNow + ( 7 * MILLISECONDS_PER_DAY ))
            )
        );
    }

}

void setUp()

This method is called by ContentCreator to set up the plug-in prior to polling it for range and timeline entries.

void tearDown()

This method is called by ContentCreator as the timeline provider object is about to be destroyed.

long getRange()

This method supplies a range in milliseconds which specifies the timeline's scale along the length of its graphical representation in the user interface. For a FutureTimelineProvider, the end point will be set to the current time plus the value provided by this method and located at the right end of the graph; for a HistoryTimelineProvider, the end point will be set to the current time minus the value provided by this method and located at the left end of the graph.

If a value of zero (0) is returned, ContentCreator will automatically apply a scale that will fit all provided timeline entries after the current time (for FutureTimelineProviders) or prior to now (for HistoryTimelineProviders).

Collection<TimelineEntry> getEntries()

This method provides a list of TimelineEntry objects.

Each TimelineEntry object is created using a static factory class TimelineEntry.Factory (see Creating TimelineEntry Objects) and configured with a Date or a Revision object:

// Configure a TimelineEntry with the current time plus one day.
final TimelineEntry myTimelineEntry = TimelineEntry.Factory.create(
    new Date(
        System.currentTimeMillis() + ( 24 * 60 * 60 * 1000 )
   )
);

The Date or Revision object used to configure the TimelineEntry should adhere to the timeline provider's directionality (future values for FutureTimelineProviders, past values for HistoryTimelineProviders). If the timeline provider specifies a range and a TimelineEntry object is configured to represent a date outside of this range (from the current time), its display on the timeline is not guaranteed.