first commit

Signed-off-by: Stephan Richter <s.richter@srsoftware.de>

de.srsoftware.cal.api/build.gradle.kts

@@ -0,0 +1,4 @@
+description = "OpenCloudCal : API"
+
+dependencies {
+}

de.srsoftware.cal.api/src/main/java/de/srsoftware/cal/api/Appointment.java

@@ -0,0 +1,70 @@
+/* © SRSoftware 2024 */
+package de.srsoftware.cal.api;
+
+import java.time.LocalDateTime;
+import java.util.Optional;
+import java.util.Set;
+
+/**
+ * This is the central object of the calendar: An appointment
+ */
+public interface Appointment {
+
+	/**
+	 * list of attachments associated with the appointment. may be used for flyers or images
+	 * @return list of attachments
+	 */
+	Set<Attachment> attachments();
+
+	/**
+	 * defines the location of the event
+	 * @return optional location
+	 */
+	Optional<Coords> coords();
+
+	/**
+	 * Descriptive text of the event
+	 * @return the description
+	 */
+	String description();
+
+
+	/**
+	 * The date and time when the appointment is scheduled to end
+	 * @return an optionals LocalDateTime
+	 */
+	Optional<LocalDateTime> end();
+
+	/**
+	 * ID of the appointment – unique within this system
+	 * @return the appointment`s id
+	 */
+	long id();
+
+
+	/**
+	 * descriptive text of the location, e.g. address
+	 * @return location text
+	 */
+	String location();
+
+	/**
+	 * The date and time, when the appointment starts
+	 * @return the start time as LocalDateTime
+	 */
+	LocalDateTime start();
+
+
+	/**
+	 * tags i.e. keywords may be used to filter appointments
+	 * @return the set of tags associated with the current appointment
+	 */
+	Set<String> tags();
+
+	/**
+	 * set of Links that point to related information
+	 * @return set of links
+	 */
+	Set<Link> urls();
+
+}

de.srsoftware.cal.api/src/main/java/de/srsoftware/cal/api/Attachment.java

@@ -0,0 +1,22 @@
+/* © SRSoftware 2024 */
+package de.srsoftware.cal.api;
+
+import java.net.URL;
+
+/**
+ * attachments may provide additional information about an appointment
+ */
+public interface Attachment {
+
+	/**
+	 * the mime type of the attached document
+	 * @return a mime type
+	 */
+	String mime();
+
+	/**
+	 * the URL of the attached document
+	 * @return the attachment URL
+	 */
+	URL url();
+}

de.srsoftware.cal.api/src/main/java/de/srsoftware/cal/api/Coords.java

@@ -0,0 +1,20 @@
+/* © SRSoftware 2024 */
+package de.srsoftware.cal.api;
+
+/**
+ * cartesian coordinates
+ */
+public interface Coords {
+
+	/**
+	 * the longitude
+	 * @return the longitude
+	 */
+	double longitude();
+
+	/**
+	 * the latitude
+	 * @return the latitude
+	 */
+	double latitude();
+}

de.srsoftware.cal.api/src/main/java/de/srsoftware/cal/api/Link.java

@@ -0,0 +1,22 @@
+/* © SRSoftware 2024 */
+package de.srsoftware.cal.api;
+
+import java.net.URL;
+
+/**
+ * Links are additional content that may be added to appointments
+ */
+public interface Link{
+
+	/**
+	 * some information about the target of the link
+	 * @return descriptive text
+	 */
+	String description();
+
+	/**
+	 * the URL of the link
+	 * @return the link`s URL
+	 */
+	URL url();
+}