homepage/docs/en-gb/projects/calendar-toolbox/api.md at main

onixbyte/homepage

Fork 0

Files

T

zihluwang ad6a11b1b4

docs: add docs for calendar toolbox

2026-05-23 08:42:52 +08:00

18 KiB

Raw Permalink Blame History

title

title
Calendar Toolbox API

Package Overview

The library is organised under the base package com.onixbyte.calendar with the following structure:

Package	Description
`com.onixbyte.calendar`	Root calendar object
`com.onixbyte.calendar.component`	iCalendar components (VEVENT, VTODO, etc.)
`com.onixbyte.calendar.component.property`	Component-level properties
`com.onixbyte.calendar.property`	Calendar-level properties
`com.onixbyte.calendar.parameter`	iCalendar property parameters
`com.onixbyte.calendar.recurrence`	Recurrence rule types
`com.onixbyte.calendar.value`	Value types
`com.onixbyte.calendar.util`	Formatting utilities

Calendar

The top-level object representing an iCalendar (RFC 5545) VCALENDAR container.

Calendar calendar = Calendar.builder()
    .withCalendarScale(...)
    .withMethod(...)
    .withProductIdentifier(...)
    .withVersion(...)
    .withOwner(...)
    .withPrimaryCalendar(...)
    .withPublishedTTL(...)
    .withCalendarDescription(...)
    .withCalendarName(...)
    .withCalendarId(...)
    .withCustomProperties(...)
    .withComponents(event, todo, ...)
    .build();

String icsContent = calendar.formatted();

Calendar Properties

All calendar-level properties live in com.onixbyte.calendar.property and implement CalendarProperty.

Class	iCalendar Property	Description
`CalendarScale`	`CALSCALE`	Calendar system (e.g., GREGORIAN)
`Method`	`METHOD`	iCalendar method (e.g., PUBLISH, REQUEST)
`ProductIdentifier`	`PRODID`	Product identifier of the calendar
`Version`	`VERSION`	iCalendar version (e.g., 2.0)
`Owner`	`X-OWNER`	Owner of the calendar
`PrimaryCalendar`	`X-PRIMARY-CALENDAR`	Whether this is a primary calendar
`PublishedTTL`	`X-PUBLISHED-TTL`	Time-to-live for published calendar
`CalendarDescription`	`X-CALENDAR-DESC`	Calendar description
`CalendarName`	`X-CALENDAR-NAME`	Calendar name
`CalendarId`	`X-CALENDAR-ID`	Calendar identifier
`CustomCalendarProperty`	`X-*`	Custom calendar properties

Custom properties are created using a builder:

var customProp = CustomCalendarProperty.builder()
    .withParameters(...)
    .build("X-MY-PROPERTY", "my-value");

Note: Custom property names must start with X-.

Components

Components represent the core entities in an iCalendar object. Each component implements CalendarComponent and is rendered between BEGIN:TYPE and END:TYPE delimiters.

Event (VEVENT)

Represents a scheduled event.

Event event = Event.builder()
    .withDateTimeStamp(dtstamp)        // required
    .withUniqueIdentifier(uid)         // required
    .withDateTimeStart(dtstart)
    .withDateTimeEnd(dtend)            // mutually exclusive with duration
    .withDuration(duration)            // mutually exclusive with dtend
    .withSummary(summary)
    .withDescription(description)
    .withClassification(classification)
    .withDateTimeCreated(dateTimeCreated)
    .withGeographicPosition(geoPos)
    .withLastModified(lastModified)
    .withLocation(location)
    .withOrganiser(organiser)
    .withPriority(priority)
    .withSequenceNumber(seqNumber)
    .withStatus(status)
    .withTimeTransparency(transparency)
    .withUniformResourceLocator(url)
    .withRecurrenceId(recurrenceId)
    .withRecurrenceRule(rrule)
    .withAttachments(attachments)
    .withAttendees(attendees)
    .withCategories(categories)
    .withComments(comments)
    .withContacts(contacts)
    .withExceptionDateTimes(exDates)
    .withRequestStatuses(statuses)
    .withRelated(related)
    .withResources(resources)
    .withRecurrenceDateTimes(rDates)
    .build();

Todo (VTODO)

Represents a to-do item or task.

Todo todo = Todo.builder()
    .withDateTimeStamp(dtstamp)        // required
    .withUniqueIdentifier(uid)         // required
    .withSummary(summary)
    .withDateTimeStart(dtstart)
    .withDateTimeDue(due)              // mutually exclusive with duration
    .withDuration(duration)            // mutually exclusive with due
    .withDateTimeCompleted(completed)
    .withPercentComplete(percent)
    .withClassification(classification)
    .withDateTimeCreated(created)
    .withDescription(description)
    .withGeographicPosition(geoPos)
    .withLastModified(lastModified)
    .withLocation(location)
    .withOrganiser(organiser)
    .withPriority(priority)
    .withSequenceNumber(seq)
    .withStatus(status)
    .withRecurrenceId(recurId)
    .withRecurrenceRule(rrule)
    .withUniformResourceLocator(url)
    .withAttachments(attachments)
    .withAttendees(attendees)
    .withCategories(categories)
    .withComments(comments)
    .withContacts(contacts)
    .withExceptionDateTimes(exDates)
    .withRequestStatuses(statuses)
    .withRelatedToList(related)
    .withResources(resources)
    .withRecurrenceDateTimes(rDates)
    .build();

Journal (VJOURNAL)

Represents a journal entry or diary note.

Journal journal = Journal.builder()
    .withDateTimeStamp(dtstamp)        // required
    .withUniqueIdentifier(uid)         // required
    .withSummary(summary)
    .withClassification(classification)
    .withDateTimeCreated(created)
    .withDateTimeStart(dtstart)
    .withLastModified(lastModified)
    .withOrganiser(organiser)
    .withRecurrenceId(recurId)
    .withSequenceNumber(seq)
    .withStatus(status)
    .withUniformResourceLocator(url)
    .withRecurrenceRule(rrule)
    .withAttachments(attachments)
    .withAttendees(attendees)
    .withCategories(categories)
    .withComments(comments)
    .withContacts(contacts)
    .withDescriptions(descriptions)
    .withExceptionDateTimes(exDates)
    .withRelatedToList(related)
    .withRecurrenceDate(rDates)
    .withRequestStatuses(statuses)
    .build();

FreeBusy (VFREEBUSY)

Represents free/busy time information.

FreeBusy freeBusy = FreeBusy.builder()
    .withDateTimeStamp(dtstamp)        // required
    .withUniqueIdentifier(uid)         // required
    .withContact(contact)
    .withDateTimeStart(dtstart)
    .withDateTimeEnd(dtend)
    .withOrganiser(organiser)
    .withUniformResourceLocator(url)
    .withAttendees(attendees)
    .withComments(comments)
    .withFreeBusyTimes(freeBusyTimes)
    .withRequestStatuses(statuses)
    .build();

TimeZone (VTIMEZONE)

Defines time zone rules including standard and daylight saving time transitions.

TimeZone timezone = TimeZone.builder()
    .withTimeZoneIdentifier(tzId)
    .withLastModified(lastModified)
    .withTimeZoneUrl(tzUrl)
    .withTimeZoneProperties(standardProp, daylightProp)
    .build();

Time zone properties define the actual transition rules:

TimeZoneProperty standard = TimeZoneProperty.builder()
    .withDateTimeStart(dtstart)
    .withTimeZoneOffsetTo(offsetTo)
    .withTimeZoneOffsetFrom(offsetFrom)
    .withRecurrenceRule(rrule)
    .withTimeZoneNames(tzName)
    .buildStandard();                  // or buildDaylight()

TimeZoneProperty daylight = TimeZoneProperty.builder()
    .withDateTimeStart(dtstart)
    .withTimeZoneOffsetTo(offsetTo)
    .withTimeZoneOffsetFrom(offsetFrom)
    .buildDaylight();

Alarm (VALARM)

Defines alarm/reminder notifications. Three alarm types are supported:

// Audio alarm
Alarm audioAlarm = Alarm.builder()
    .withTrigger(trigger)
    .withDuration(duration)
    .withRepeatCount(repeatCount)
    .withAttachments(audioAttachment)
    .buildAudio();

// Display alarm
Alarm displayAlarm = Alarm.builder()
    .withTrigger(trigger)
    .withDescription(description)      // required
    .withDuration(duration)
    .withRepeatCount(repeatCount)
    .buildDisplay();

// Email alarm
Alarm emailAlarm = Alarm.builder()
    .withTrigger(trigger)
    .withDescription(description)      // required
    .withSummary(summary)              // required
    .withAttendees(attendees)          // required
    .withDuration(duration)
    .withRepeatCount(repeatCount)
    .buildEmail();

Component Properties

Component properties live in com.onixbyte.calendar.component.property and implement ComponentProperty.

Class	iCalendar Property	Description
`Action`	`ACTION`	Alarm action type (AUDIO, DISPLAY, EMAIL)
`Attachment`	`ATTACH`	Document attachment
`Attendee`	`ATTENDEE`	Event/task attendee
`Categories`	`CATEGORIES`	Categories or tags
`Classification`	`CLASS`	Access classification (PUBLIC, PRIVATE, CONFIDENTIAL)
`Comment`	`COMMENT`	Comment
`Contact`	`CONTACT`	Contact information
`DateTimeCompleted`	`COMPLETED`	Completion date-time
`DateTimeCreated`	`CREATED`	Creation date-time
`DateTimeDue`	`DUE`	Due date-time
`DateTimeEnd`	`DTEND`	End date-time
`DateTimeStamp`	`DTSTAMP`	Date-time stamp
`DateTimeStart`	`DTSTART`	Start date-time
`Description`	`DESCRIPTION`	Description
`ExceptionDateTimes`	`EXDATE`	Exception date-times
`FreeBusyTime`	`FREEBUSY`	Free/busy time periods
`GeographicPosition`	`GEO`	Geographic position (lat/long)
`LastModified`	`LAST-MODIFIED`	Last modified date-time
`Location`	`LOCATION`	Location
`Organiser`	`ORGANIZER`	Event organiser
`PercentComplete`	`PERCENT-COMPLETE`	Completion percentage
`Priority`	`PRIORITY`	Priority level
`RecurrenceDateTimes`	`RDATE`	Recurrence date-times
`RecurrenceId`	`RECURRENCE-ID`	Recurrence instance identifier
`RecurrenceRule`	`RRULE`	Recurrence rule
`RelatedTo`	`RELATED-TO`	Related component reference
`RepeatCount`	`REPEAT`	Alarm repeat count
`RequestStatus`	`REQUEST-STATUS`	Request status
`Resources`	`RESOURCES`	Resources
`SequenceNumber`	`SEQUENCE`	Sequence number (revision)
`Status`	`STATUS`	Component status (TENTATIVE, CONFIRMED, CANCELLED, etc.)
`Summary`	`SUMMARY`	Title or summary
`TimeTransparency`	`TRANSP`	Time transparency (OPAQUE, TRANSPARENT)
`TimeZoneIdentifier`	`TZID`	Time zone identifier
`TimeZoneName`	`TZNAME`	Time zone name
`TimeZoneOffsetFrom`	`TZOFFSETFROM`	Time zone offset from UTC
`TimeZoneOffsetTo`	`TZOFFSETTO`	Time zone offset to UTC
`TimeZoneUrl`	`TZURL`	Time zone URL
`Trigger`	`TRIGGER`	Alarm trigger
`UniformResourceLocator`	`URL`	Associated URL
`UniqueIdentifier`	`UID`	Unique identifier
`CustomComponentProperty`	`X-*`	Custom component properties

Parameters

Parameters in com.onixbyte.calendar.parameter provide additional qualifiers on component properties.

Class	iCalendar Parameter	Description
`AlarmTriggerRelationship`	`RELATED`	Trigger relationship (START, END)
`AlternateTextRepresentation`	`ALTREP`	Alternate text URI
`CalendarUserType`	`CUTYPE`	Calendar user type (INDIVIDUAL, GROUP, RESOURCE, etc.)
`CommonName`	`CN`	Common name
`Delegatees`	`DELEGATED-TO`	Delegatees
`Delegators`	`DELEGATED-FROM`	Delegators
`DirectoryEntryReference`	`DIR`	Directory entry URI
`FormatType`	`FMTTYPE`	Format type (MIME type)
`FreeBusyTimeType`	`FBTYPE`	Free/busy time type
`InlineEncoding`	`ENCODING`	Inline encoding (BASE64)
`Language`	`LANGUAGE`	Language
`Membership`	`MEMBER`	Group membership
`ParticipationRole`	`ROLE`	Participation role (CHAIR, REQ-PARTICIPANT, etc.)
`ParticipationStatus`	`PARTSTAT`	Participation status (ACCEPTED, DECLINED, etc.)
`RecurrenceIdentifierRange`	`RANGE`	Recurrence range (THISANDPRIOR, THISANDFUTURE)
`RelationshipType`	`RELTYPE`	Relationship type (PARENT, CHILD, SIBLING)
`RsvpExpectation`	`RSVP`	RSVP expectation (TRUE, FALSE)
`SentBy`	`SENT-BY`	Sent by
`TimeZoneIdentifier`	`TZID`	Time zone identifier
`ValueDataType`	`VALUE`	Value data type (DATE, DATE-TIME, etc.)

Recurrence Types

Located in com.onixbyte.calendar.recurrence.

Class	Description
`Frequency`	Frequency constants (DAILY, WEEKLY, MONTHLY, YEARLY) for recurrence rules
`WeekdayNum`	Weekday number for recurrence rules (e.g., 2nd Monday)

Value Types

Located in com.onixbyte.calendar.value.

Class	Description
`FreeBusyTimeValue`	Represents free/busy time value
`PeriodOfTime`	Represents a period of time with start and end
`PropertyValue`	Base value type for properties
`UtcOffset`	UTC offset value (e.g., `-05:00`, `+01:00`)

Formatted Output

All components and properties provide a formatted() method that returns an iCalendar-compliant string representation. The Calendar.formatted() method produces a complete .ics output wrapped in BEGIN:VCALENDAR/END:VCALENDAR.

String ics = calendar.formatted();
// BEGIN:VCALENDAR
// CALSCALE:GREGORIAN
// METHOD:PUBLISH
// ...
// END:VCALENDAR

18 KiB Raw Permalink Blame History