onixbyte/onixbyte-bom
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(webcal): Optimised javadoc

Browse Source
This commit is contained in:
Zihlu Wang
2023-08-06 21:05:11 +08:00
parent 3cb6805185
commit aea5266da5
6 changed files with 297 additions and 302 deletions
Download Patch File Download Diff File Expand all files Collapse all files
webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendar.java
+61 -52
View File
@@ -21,71 +21,74 @@ import java.util.ArrayList;
import java.util.List;
/**
* WebCalendar
* The WebCalendar class represents a web calendar in iCalendar format.
*
* <p>
* It allows users to create and customize calendar components and events and
* generate an iCalendar string containing all the calendar information.
*
* <p>Usage Example:
* <pre>
* WebCalendar calendar = new WebCalendar()
* .setName("My Web Calendar")
* .setCompanyName("CodeCrafters Inc.")
* .setProductName("WebCal")
* .setDomainName("codecrafters.org.cn")
* .setMethod("PUBLISH")
* .addEvent(event1)
* .addEvent(event2);
* String iCalendarString = calendar.resolve();
* </pre>
*
* <p>
* The WebCalendar class is designed to generate an iCalendar string conforming
* to the iCalendar specification, which can be used to share calendar data
* with other calendar applications or services.
*
* @author Zihlu Wang
* @version 1.0.0
* @since 1.0.0
*/
public final class WebCalendar {
//
// Constants
//
// Tag
/**
* The VCALENDAR tag for iCalendar format
*/
private final static String TAG = "VCALENDAR";
//
// Fields
//
// Calendar properties
private String name;
/**
* Company name. This value is to specify the {@code productIdentifier}
* property.
*/
private String companyName;
/**
* Product name. This value is to specify the {@code productIdentifier}
* property.
*/
private String productName;
private String domainName;
/**
* Calendar scale, referenced from <a href="https://icalendar.org/iCalendar-RFC-5545/3-7-1-calendar-scale.html"
* >RFC 5545 - 3.7.1. Calendar Scale</a>.
*/
private final String scale = "GREGORIAN";
/**
* Method, referenced from <a href="https://icalendar.org/iCalendar-RFC-5545/3-7-2-method.html"
* >RFC 5545 - 3.7.2. Method</a>.
*/
private String method;
private final String version = "2.0";
private List<WebCalendarNode> nodes;
/**
* List of calendar components and events
*/
private final List<WebCalendarNode> nodes;
//
// Constructors
//
/**
* Constructor for WebCalendar class, initializes the list of calendar
* components and events.
*/
public WebCalendar() {
this.nodes = new ArrayList<>();
}
//
// Methods
//
/**
* Set the name for this calendar.
* Set the name of the web calendar.
*
* @param name The name for the calendar.
* @return The calendar instance.
* @param name the name of the web calendar
* @return the WebCalendar object
*/
public WebCalendar setName(String name) {
this.name = name;
@@ -93,26 +96,32 @@ public final class WebCalendar {
}
/**
* Set the company name for this calendar.
* Set the company name associated with the web calendar.
*
* @param companyName The company name for the calendar.
* @return The calendar instance.
* @param companyName the company name
* @return the WebCalendar object
*/
public WebCalendar setCompanyName(String companyName) {
this.companyName = companyName;
return this;
}
/**
* Set the domain name associated with the web calendar.
*
* @param domainName the domain name
* @return the WebCalendar object
*/
public WebCalendar setDomainName(String domainName) {
this.domainName = domainName;
return this;
}
/**
* Set the product name for this calendar.
* Set the product name of the web calendar.
*
* @param productName The product name for the calendar.
* @return The calendar instance.
* @param productName the product name
* @return the WebCalendar object
*/
public WebCalendar setProductName(String productName) {
this.productName = productName;
@@ -120,10 +129,10 @@ public final class WebCalendar {
}
/**
* Set the method for this calendar.
* Set the method for publishing the web calendar.
*
* @param method The product name for the calendar.
* @return The calendar instance.
* @param method the publishing method
* @return the WebCalendar object
*/
public WebCalendar setMethod(String method) {
this.method = method;
@@ -131,10 +140,10 @@ public final class WebCalendar {
}
/**
* Add a calendar node to this calendar.
* Add an event to the web calendar.
*
* @param node Any calendar node.
* @return The calendar instance.
* @param node the calendar component or event to be added
* @return the WebCalendar object
*/
public WebCalendar addEvent(WebCalendarNode node) {
this.nodes.add(node);
@@ -142,13 +151,13 @@ public final class WebCalendar {
}
/**
* Resolve the calendar instance to a text that implements RFC-5545.
* Generate and resolve the iCalendar string for the web calendar.
*
* @return A string includes all events in this calendar.
* @return the resolved iCalendar string
*/
public String resolve() {
var events = new StringBuilder();
if (nodes != null && !nodes.isEmpty()) {
if (!nodes.isEmpty()) {
nodes.forEach(item ->
events.append(item.setDomainName(domainName)
.resolve()));
webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarEvent.java
+73 -52
View File
@@ -28,19 +28,31 @@ import java.util.Optional;
import java.util.UUID;
/**
* WebCalendarEvent
* The WebCalendarEvent class represents an event in the web calendar. It
* extends the abstract class WebCalendarNode and provides additional methods
* to set properties specific to events.
*
* <p>
* Users can use the methods in this class to add categories, set the
* classification, add comments, descriptions, locations, set percent complete
* , set priority, set summary, set start time, set end time, set duration, set
* URL, set UID, and set timezone for the event. After setting the properties,
* users can call the {@link #resolve()} method to generate the corresponding
* iCalendar content for the event.
*
* @author Zihlu Wang
* @version 1.0.0
* @since 1.0.0
*/
public final class WebCalendarEvent extends WebCalendarNode {
private final static String TAG = "VEVENT";
/**
* Add a batch of categories.
* Add categories to the event.
*
* @param categories A batch of categories.
* @return The Event instance.
* @param categories the categories to add
* @return the WebCalendarEvent object
*/
public WebCalendarEvent addCategories(String... categories) {
this.categories.addAll(Arrays.asList(categories));
@@ -48,10 +60,10 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Add a batch of categories.
* Add a collection of categories to the event.
*
* @param categories A batch of categories.
* @return The Event instance.
* @param categories the collection of categories to add
* @return the WebCalendarEvent object
*/
public WebCalendarEvent addCategories(Collection<String> categories) {
this.categories.addAll(categories);
@@ -59,10 +71,10 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Add a category.
* Add a single category to the event.
*
* @param category A category.
* @return The Event instance.
* @param category the category to add
* @return the WebCalendarEvent object
*/
public WebCalendarEvent addCategory(String category) {
this.categories.add(category);
@@ -70,10 +82,10 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Set the classification.
* Set the classification of the event.
*
* @param classification The specified classification value.
* @return The Event instance.
* @param classification the classification to set
* @return the WebCalendarEvent object
*/
public WebCalendarEvent setClassification(Classification classification) {
this.classification = classification;
@@ -81,10 +93,10 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Set the comment.
* Set the comment for the event.
*
* @param comment The comment.
* @return The Event instance.
* @param comment the comment to set
* @return the WebCalendarEvent object
*/
public WebCalendarEvent setComment(String comment) {
this.comment = comment;
@@ -92,10 +104,10 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Set the description.
* Set the description for the event.
*
* @param description The description.
* @return The Event instance.
* @param description the description to set
* @return the WebCalendarEvent object
*/
public WebCalendarEvent setDescription(String description) {
this.description = description;
@@ -103,10 +115,10 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Set the location.
* Set the location for the event.
*
* @param location The location.
* @return The Event instance.
* @param location the location to set
* @return the WebCalendarEvent object
*/
public WebCalendarEvent setLocation(String location) {
this.location = location;
@@ -114,10 +126,11 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Set the percent complete value.
* Set the percent complete for the event.
*
* @param percentComplete The percent complete value.
* @return The Event instance.
* @param percentComplete the percent complete to set
* @return the WebCalendarEvent object
* @throws IllegalArgumentException if the percent complete is out of range (0 ~ 100)
*/
public WebCalendarEvent setPercentComplete(Integer percentComplete) {
if (percentComplete < 0 || percentComplete > 100) {
@@ -128,10 +141,11 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Set a priority.
* Set the priority for the event.
*
* @param priority The priority to be set.
* @return The Event instance.
* @param priority the priority to set
* @return the WebCalendarEvent object
* @throws IllegalArgumentException if the priority is out of range (0 ~ 9)
*/
public WebCalendarEvent setPriority(Integer priority) {
if (priority < 0 || priority > 9) {
@@ -142,10 +156,10 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Set the summary.
* Set the summary for the event.
*
* @param summary The summary (you can also call it as a title).
* @return The Event instance.
* @param summary the summary to set
* @return the WebCalendarEvent object
*/
public WebCalendarEvent setSummary(String summary) {
this.summary = summary;
@@ -153,10 +167,11 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Set the end of this node.
* Set the end time for the event.
*
* @param end The end time of this event.
* @return The Event instance.
* @param end the end time to set
* @return the WebCalendarEvent object
* @throws IllegalStateException if the field DURATION has been set before
*/
public WebCalendarEvent setEnd(LocalDateTime end) {
if (this.duration != null) {
@@ -167,10 +182,10 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Set the start of this event.
* Set the start time for the event.
*
* @param start The date time specify the start time of this event.
* @return The Event instance.
* @param start the start time to set
* @return the WebCalendarEvent object
*/
public WebCalendarEvent setStart(LocalDateTime start) {
this.start = start;
@@ -178,10 +193,11 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Set the duration of this event.
* Set the duration for the event.
*
* @param duration The duration of this event.
* @return The Event instance.
* @param duration the duration to set
* @return the WebCalendarEvent object
* @throws IllegalStateException if the field END has been set before
*/
public WebCalendarEvent setDuration(Duration duration) {
if (this.end != null) {
@@ -192,10 +208,10 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Set the URL.
* Set the URL for the event.
*
* @param url The URL.
* @return The Event instance.
* @param url the URL to set
* @return the WebCalendarEvent object
*/
public WebCalendarEvent setUrl(String url) {
this.url = url;
@@ -203,10 +219,10 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Set the uid of this event.
* Set the UID for the event.
*
* @param uid The uid.
* @return The Event instance.
* @param uid the UID to set
* @return the WebCalendarEvent object
*/
public WebCalendarEvent setUid(String uid) {
this.uid = uid;
@@ -214,10 +230,10 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Set the domain name of this event.
* Set the domain name for the event.
*
* @param domainName The domain name.
* @return The Event instance.
* @param domainName the domain name to set
* @return the WebCalendarEvent object
*/
public WebCalendarEvent setDomainName(String domainName) {
this.domainName = domainName;
@@ -225,16 +241,21 @@ public final class WebCalendarEvent extends WebCalendarNode {
}
/**
* Set the timezone of this event.
* Set the timezone for the event.
*
* @param timezone The time zone to set.
* @return The Event instance.
* @param timezone the timezone to set
* @return the WebCalendarEvent object
*/
public WebCalendarEvent setTimezone(String timezone) {
this.timezone = timezone;
return this;
}
/**
* Generate and resolve the iCalendar content for the event.
*
* @return the resolved iCalendar content for the event
*/
@Override
public String resolve() {
return "\nBEGIN:" + TAG + "\n" +
webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarNode.java
+32 -197
View File
@@ -25,220 +25,45 @@ import java.util.ArrayList;
import java.util.List;
/**
* WebCalendarNode
* The abstract sealed class WebCalendarNode represents a node in the web
* calendar, such as an event, a to-do item, or an alarm. It provides common
* properties and methods for all calendar components and events.
*
* <p>
* Subclasses of WebCalendarNode should implement the {@link #resolve()} method
* to generate the corresponding iCalendar content for the specific calendar
* component or event.
*
* @author Zihlu Wang
* @version 1.0.0
* @since 1.0.0
*/
public abstract sealed class WebCalendarNode
permits WebCalendarEvent {
/**
* <p>
* Categories, is used to specify categories or subtypes of the calendar component. The categories are useful in
* searching for a calendar component of a particular type and category.
* </p>
*
* Template:
* <pre>CATEGORIES:APPOINTMENT,EDUCATION</pre>
* <pre>CATEGORIES:MEETING</pre>
*
* <p>Referenced from <a href="https://icalendar.org/iCalendar-RFC-5545/3-8-1-2-categories.html"
* >RFC-5545 - 3.8.1.2. Categories</a></p>
*/
// Common properties for all calendar components and events
protected List<String> categories;
/**
* <p>
* Classification, An access classification is only one component of the general security system within a calendar
* application. It provides a method of capturing the scope of the access the calendar owner intends for information
* within an individual calendar entry.
* </p>
*
* Template:
* <pre>CLASS:protected</pre>
*
* <p>Referenced from <a href="https://icalendar.org/iCalendar-RFC-5545/3-8-1-3-classification.html"
* >RFC-5545 - 3.8.1.3. Classification</a></p>
*/
protected Classification classification;
/**
* <p>
* Comment, is used to specify a comment to the calendar user.
* </p>
*
* Template:
* <pre>
* COMMENT:The meeting really needs to include both ourselves
* and the customer. We can't hold this meeting without them.
* As a matter of fact\, the venue for the meeting ought to be at
* their site. - - John
* </pre>
*
* <p>Referenced from <a href="https://icalendar.org/iCalendar-RFC-5545/3-8-1-4-comment.html"
* >RFC-5545 - 3.8.1.4. Comment</a></p>
*/
protected String comment;
/**
* <p>
* Description is used in the {@link WebCalendarEvent} and <em>to-do</em> to capture lengthy extual descriptions associated with
* the activity.
* </p>
* <p>
* Description is used in the <em>Journal</em> calendar component to capture one or more textual journal entries.
* </p>
* <p>
* Description is used in the <em>Alarm</em> calendar component to capture the display text for a DISPLAY category of
* alarm, and to capture the body text for an EMAIL category of alarm.
* </p>
*
* Template:
* <pre>
* DESCRIPTION:Meeting to provide technical review for "Phoenix"
* design.\nHappy Face Conference Room. Phoenix design team
* MUST attend this meeting.\nRSVP to team leader.
* </pre>
*
* <p>Referenced from <a href="https://icalendar.org/iCalendar-RFC-5545/3-8-1-5-description.html"
* >RFC-5545 - 3.8.1.5. Description</a></p>
*/
protected String description;
/**
* <p>
* Location, Specific venues such as conference or meeting rooms may be explicitly specified using this property.
* </p>
*
* <p>
* <b>Note</b><br>
* This location has not implement the URI of the location.
* </p>
*
* Template:
* <pre>LOCATION:Conference Room - F123\, Bldg. 002</pre>
* <pre>LOCATION;ALTREP="http://xyzcorp.com/conf-rooms/f123.vcf":
* Conference Room - F123\, Bldg. 002</pre>
*
* <p>Referenced from <a href="https://icalendar.org/iCalendar-RFC-5545/3-8-1-7-location.html"
* >RFC-5545 - 3.8.1.7. Location</a></p>
*/
protected String location;
/**
* <p>
* Percent Complete, is a positive integer between 0 and 100. A value of "0" indicates the to-do has not yet been
* started. A value of "100" indicates that the to-do has been completed. Integer values in between indicate the
* percent partially complete.
* </p>
*
* Template:
* <pre>PERCENT-COMPLETE:39</pre>
*
* <p>Referenced from <a href="https://icalendar.org/iCalendar-RFC-5545/3-8-1-8-percent-complete.html"
* >RFC-5545 - 3.8.1.8. Percent Complete</a></p>
*/
protected Integer percentComplete;
/**
* <p>
* Priority, is specified as an integer in the range 0 to 9. A value of 0 specifies an undefined priority. A value
* of 1 is the highest priority. A value of 2 is the second-highest priority. Subsequent numbers specify a
* decreasing ordinal priority. A value of 9 is the lowest priority.
* </p>
*
* Example:
* <ul style="list-style-type: none;">
* <li>
* The following is an example of a property with the highest priority:
* <pre>PRIORITY:1</pre>
* </li>
* <li>
* The following is an example of a property with a next highest priority:
* <pre>PRIORITY:2</pre>
* </li>
* </ul>
*/
protected Integer priority;
/**
* <p>
* Summary, is used to capture a short, one-line summary about the activity or journal entry.
* </p>
*
* Example:
* <pre>SUMMARY:Department Party</pre>
*/
protected String summary;
// /**
// * Completed defines the date and time that a to-do was actually completed.
// *
// * <p>
// * Example:
// * <pre>COMPLETED:19960401T150000Z</pre>
// * </p>
// */
// protected DateTime completed;
//
// /**
// * Set the specific time of the completion of this to-do event.
// *
// * @param completed The complete time.
// */
// protected void setCompleted(DateTime completed) {
// this.completed = completed;
// }
/**
* End defines the date and time by which the event ends.
*
* Example:
* <pre>DTEND:19960401T150000Z</pre>
* <pre>DTEND;VALUE=DATE:19980704</pre>
*/
protected LocalDateTime end;
/**
* Start defines the start date and time for the event.
*
* Example:
* <pre>DTSTART:19980118T073000Z</pre>
* <pre>DTSTART;VALUE=DATE:19980118</pre>
*/
protected LocalDateTime start;
/**
* Duration may be used to specify a duration of the event, instead of an explicit end DATE-TIME.
*
* Example:
* <pre>DURATION:PT100000S</pre>
*/
protected Duration duration;
/**
* URL may be used in a calendar component to convey a location where a more dynamic rendition of the calendar
* information associated with the calendar component can be found.
*
* Example:
* <pre>URL:http://example.com/pub/calendars/jsmith/mytime.ics</pre>
*/
protected String url;
protected String uid;
@@ -247,23 +72,30 @@ public abstract sealed class WebCalendarNode
protected String timezone;
//
// Constructors
//
/**
* Constructor for WebCalendarNode class, initializes the list of
* categories associated with the calendar component or event.
*/
protected WebCalendarNode() {
this.categories = new ArrayList<>();
}
/**
* Set the domain name associated with the calendar component or event.
*
* @param domainName the domain name
* @return the WebCalendarNode object
*/
public WebCalendarNode setDomainName(String domainName) {
this.domainName = domainName;
return this;
}
//
// Protected methods
//
/**
* Resolve the list of categories into a comma-separated string.
*
* @return the comma-separated string of categories
*/
protected String resolveCategories() {
var builder = new StringBuilder();
if (categories != null && !categories.isEmpty()) {
@@ -273,9 +105,12 @@ public abstract sealed class WebCalendarNode
return builder.toString();
}
//
// Abstract methods
//
/**
* Generate and resolve the iCalendar content for the calendar component or
* event.
*
* @return the resolved iCalendar content
*/
public abstract String resolve();
}
webcal/src/main/java/cn/org/codecrafters/webcal/config/Classification.java
+53 -1
View File
@@ -18,25 +18,77 @@
package cn.org.codecrafters.webcal.config;
/**
* WebCalClassification
* The Classification enum represents the classification levels of calendar
* content based on RFC 5545.
*
* <p>
* Calendar events or components can be classified as one of the following
* levels:
* <ul>
* <li>
* {@link #PUBLIC}: Indicates that the calendar content is public and
* can be freely distributed.
* </li>
* <li>
* {@link #PRIVATE}: Indicates that the calendar content is private and
* should not be shared with others.
* </li>
* <li>
* {@link #CONFIDENTIAL}: Indicates that the calendar content is
* confidential and should be kept strictly private.
* </li>
* </ul>
*
* @author Zihlu Wang
* @version 1.0.0
* @since 1.0.0
*/
public enum Classification {
/**
* Public classification level.
*
* <p>
* Indicates that the calendar content is public and can be freely
* distributed.
*/
PUBLIC("PUBLIC"),
/**
* Private classification level.
*
* <p>
* Indicates that the calendar content is private and should not be shared
* with others.
*/
PRIVATE("PRIVATE"),
/**
* Confidential classification level.
*
* <p>
* Indicates that the calendar content is confidential and should be kept
* strictly private.
*/
CONFIDENTIAL("CONFIDENTIAL"),
;
private final String classification;
/**
* Constructor for Classification enum.
*
* @param classification the classification level as a string representation
*/
Classification(String classification) {
this.classification = classification;
}
/**
* Get the string representation of the classification level.
*
* @return the string representation of the classification level
*/
public String getClassification() {
return classification;
}
webcal/src/main/java/cn/org/codecrafters/webcal/config/package-info.java
+34
View File
@@ -0,0 +1,34 @@
/*
* Copyright (C) 2023 CodeCraftersCN.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
*
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* The package cn.org.codecrafters.webcal.config contains classes related to
* the configuration and settings of the web calendar module. It provides
* various configurations and constants used in the generation and resolution
* of iCalendar content.
*
* <p>The classes in this package include:</p>
* <ul>
* <li>
* {@link cn.org.codecrafters.webcal.config.Classification}: An enum
* representing the classification of events in the web calendar.
* </li>
* </ul>
*
* @since 1.0.0
*/
package cn.org.codecrafters.webcal.config;
webcal/src/main/java/cn/org/codecrafters/webcal/package-info.java
+44
View File
@@ -0,0 +1,44 @@
/*
* Copyright (C) 2023 CodeCraftersCN.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
*
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* The package {@code cn.org.codecrafters.webcal} contains classes and modules
* related to web calendar generation and resolution. It provides functionality
* to create and manage iCalendar content for web-based calendar applications.
*
* <p>
* The main classes and modules in this package include:
* <ul>
* <li>
* {@link cn.org.codecrafters.webcal.WebCalendar}: A class for
* generating web calendars with customizable settings and events.
* </li>
* <li>
* {@link cn.org.codecrafters.webcal.WebCalendarEvent}: A class
* representing a single event in a web calendar with various
* attributes and options.
* </li>
* <li>
* {@link cn.org.codecrafters.webcal.WebCalendarNode}: An abstract
* class serving as the base class for web calendar nodes, providing
* common attributes and functionality for events.
* </li>
* </ul>
*
* @since 1.0.0
*/
package cn.org.codecrafters.webcal;