16.4. Implementing an Event Provider

An event provider could use the built-in BasicEvent, but it is usually more proper to define a custom event type that is bound directly to the data source. Custom events may be useful for some other purposes as well, such as when you need to add extra information to an event or customize how it is acquired.

Custom events must implement the CalendarEvent interface or extend an existing event class. The built-in BasicEvent class should serve as a good example of implementing simple events. It keeps the data in member variables.

public class BasicEvent
       implements CalendarEventEditor, EventChangeNotifier {
   ...

   public String getCaption() {
        return caption;
    }

    public String getDescription() {
        return description;
    }

    public Date getEnd() {
        return end;
    }

    public Date getStart() {
        return start;
    }

    public String getStyleName() {
        return styleName;
    }

    public boolean isAllDay() {
        return isAllDay;
    }

    public void setCaption(String caption) {
        this.caption = caption;
        fireEventChange();
    }

    public void setDescription(String description) {
        this.description = description;
        fireEventChange();
    }

    public void setEnd(Date end) {
        this.end = end;
        fireEventChange();
    }

    public void setStart(Date start) {
        this.start = start;
        fireEventChange();
    }

    public void setStyleName(String styleName) {
        this.styleName = styleName;
        fireEventChange();
    }

    public void setAllDay(boolean isAllDay) {
        this.isAllDay = isAllDay;
        fireEventChange();
    }

    public void addListener(EventChangeListener listener) {
        ...
    }
    
    public void removeListener(EventChangeListener listener) {
        ...
    }

    protected void fireEventChange() {...}
}

You may have noticed that there was some additional code in the BasicEvent that was not in the CalendarEvent interface. Namely BasicEvent also implements two additional interfaces:

The start time and end time are mandatory, but caption, description, and style name are not. The style name is used as a part of the CSS class name for the HTML DOM element of the event.

In addition to the basic event interfaces, you can enhance the functionality of your event and event provider classes by using the EventChange and EventSetChange events. They let the Calendar component to know about changes in events and update itself accordingly. The BasicEvent and BasicEventProvider examples given earlier include a simple implementation of these interfaces.

An event provider needs to implement the CalendarEventProvider interface. It has only one method to be implemented. Whenever the calendar is painted, getEvents(Date, Date) method is called and it must return a list of events between the given start and end time.

The following example implementation returns only one example event. The event starts from the current time and is five hours long.

public class MyEventProvider implements CalendarEventProvider{
    public List<Event> getEvents(Date startDate, Date endDate){
        List<Event> events = new ArrayList<Event>();
        GregorianCalendar cal = new GregorianCalendar();
        cal.setTime(new Date());

        Date start = cal.getTime();
        cal.add(GregorianCalendar.HOUR, 5);
        Date end = cal.getTime();
        BasicEvent event = new BasicEvent();
        event.setCaption("My Event");
        event.setDescription("My Event Description");
        event.setStart(start);
        event.setEnd(end);
        events.add(event);

        return events;
    }
}

It is important to notice that the Calendar may query for dates beyond the range defined by start date and end date. Particularly, it may expand the date range to make sure the user interface is rendered correctly.