Merge pull request #3 from yetanalytics/more_packaging

More packaging

.github/workflows/cd.yml

@@ -0,0 +1,43 @@
+name: CD
+
+on:
+  push:
+    tags:
+      - 'v*.*.*' # Enforce Semantic Versioning
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      packages: write
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: '11'
+          distribution: 'temurin'
+          server-id: central
+          server-username: MAVEN_USERNAME
+          server-password: MAVEN_PASSWORD
+      - name: Publish package
+        run: mvn --batch-mode deploy -Dpublish=true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          MAVEN_GPG_PASSPHRASE: ${{ secrets.RELEASES_GPG_PASSPHRASE }}
+          MAVEN_GPG_KEY: ${{ secrets.RELEASES_GPG_PRIVATE_KEY }}
+          MAVEN_USERNAME: ${{ secrets.MAVEN_CENTRAL_TOKEN_USERNAME }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_CENTRAL_TOKEN_PASSWORD }}
+      - name: Prep Docs
+        run: | 
+          cd target
+          export DOCZIP=$(ls | grep javadoc.jar$)
+          mkdir -p apidocs
+          unzip $DOCZIP -d apidocs
+      - name: Deploy Docs
+        uses: JamesIves/[email protected]
+        with:
+          branch: gh-pages
+          folder: target/apidocs
+

pom.xml

@@ -6,31 +6,46 @@
   <packaging>jar</packaging>
   <version>0.0.1</version>
   <name>xAPI Tools</name>
-  <description>xAPI Serialization Model and Tools for Java</description>
+  <description>Java Serialization Model and Tools for xAPI Standard (IEEE 9274.1.1)</description>
   <url>https://github.com/yetanalytics/java-xapi-tools</url>
+  <scm>
+    <url>https://github.com/yetanalytics/java-xapi-tools</url>
+    <connection>scm:git:https://github.com/yetanalytics/java-xapi-tools.git</connection>
+    <developerConnection>scm:git:https://github.com/yetanalytics/java-xapi-tools.git</developerConnection>
+  </scm>
   <licenses>
     <license>
       <name>Apache License, Version 2.0</name>
       <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
       <distribution>repo</distribution>
     </license>
   </licenses>
+  <developers>
+    <developer>
+      <organization>Yet Analytics Inc.</organization>
+      <organizationUrl>https://www.yetanalytics.com</organizationUrl>
+      <name>Cliff Casey</name>
+      <email>[email protected]</email>
+      <url>https://github.com/cliffcaseyyet</url>
+    </developer>
+  </developers>
   <properties>
     <maven.compiler.source>11</maven.compiler.source>
     <maven.compiler.target>11</maven.compiler.target>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
+    <jackson.version>2.18.1</jackson.version>
   </properties>
   <dependencies>
     <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-databind</artifactId>
-      <version>2.18.1</version>
+      <version>${jackson.version}</version>
     </dependency>
     <dependency>
       <groupId>com.fasterxml.jackson.datatype</groupId>
       <artifactId>jackson-datatype-jsr310</artifactId>
-      <version>2.18.1</version>
+      <version>${jackson.version}</version>
     </dependency>
     <dependency>
       <groupId>com.jayway.jsonpath</groupId>
@@ -50,6 +65,47 @@
       <scope>test</scope>
     </dependency>
   </dependencies>
+  <profiles>
+    <profile>
+      <id>publish-build</id>
+      <activation>
+          <property>
+              <name>publish</name>
+              <value>true</value>
+          </property>
+      </activation>
+      <build>
+        <plugins>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-gpg-plugin</artifactId>
+            <version>3.2.7</version>
+            <executions>
+              <execution>
+                <id>sign-artifacts</id>
+                <phase>install</phase>
+                <goals>
+                  <goal>sign</goal>
+                </goals>
+                <configuration>
+                  <signer>bc</signer>
+                </configuration>
+              </execution>
+            </executions>
+          </plugin>
+          <plugin>
+            <groupId>org.sonatype.central</groupId>
+            <artifactId>central-publishing-maven-plugin</artifactId>
+            <version>0.6.0</version>
+            <extensions>true</extensions>
+            <configuration>
+              <publishingServerId>central</publishingServerId>
+            </configuration>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
+  </profiles>
   <build>
     <plugins>
       <plugin>
@@ -68,7 +124,45 @@
             </goals>
           </execution>
         </executions>
+      </plugin>    
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-surefire-plugin</artifactId>
+        <version>3.5.2</version>
+      </plugin>
+      <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-source-plugin</artifactId>
+          <version>3.3.1</version>
+          <executions>
+              <execution>
+                  <id>attach-sources</id>
+                  <goals>
+                      <goal>jar-no-fork</goal>
+                  </goals>
+              </execution>
+          </executions>
+      </plugin>
+      <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-javadoc-plugin</artifactId>
+          <version>3.11.1</version>
+          <executions>
+              <execution>
+                  <id>attach-javadocs</id>
+                  <goals>
+                      <goal>jar</goal>
+                  </goals>
+              </execution>
+          </executions>
       </plugin>
     </plugins>
   </build>
+  <distributionManagement>
+    <repository>
+      <id>github</id>
+      <name>GitHub Packages</name>
+      <url>https://maven.pkg.github.com/yetanalytics/java-xapi-tools</url>
+    </repository>
+  </distributionManagement>
 </project>

src/main/java/com/yetanalytics/xapi/model/AbstractActor.java

@@ -3,6 +3,9 @@
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.yetanalytics.xapi.model.deserializers.AbstractActorDeserializer;
 
+/**
+* Abstract Class for serialization and deserialization of xAPI Actors
+*/
 @JsonDeserialize(using = AbstractActorDeserializer.class)
 public abstract class AbstractActor extends AbstractObject {
 

src/main/java/com/yetanalytics/xapi/model/AbstractObject.java

@@ -3,6 +3,9 @@
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.yetanalytics.xapi.model.deserializers.AbstractObjectDeserializer;
 
+/**
+* Abstract Class for serialization and deserialization of xAPI Objects
+*/
 @JsonDeserialize(using = AbstractObjectDeserializer.class)
 public class AbstractObject {
 

src/main/java/com/yetanalytics/xapi/model/Account.java

@@ -3,6 +3,10 @@
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 
+/**
+* Class representation of the Account Component of the 
+* <a href="https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#2424-account-object">9274.1.1 xAPI Specification</a>.
+*/
 @JsonInclude(Include.NON_NULL)
 public class Account {
 

src/main/java/com/yetanalytics/xapi/model/Activity.java

@@ -4,6 +4,10 @@
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 
+/**
+* Class representation of the Activity Object Type of the 
+* <a href="https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#2441-when-the-objecttype-is-activity">9274.1.1 xAPI Specification</a>.
+*/
 @JsonInclude(Include.NON_NULL)
 @JsonDeserialize
 public class Activity extends AbstractObject {

src/main/java/com/yetanalytics/xapi/model/ActivityDefinition.java

@@ -5,6 +5,10 @@
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 
+/**
+* Class representation of the Activity Definition Component of the 
+* <a href="https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#activity-definition">9274.1.1 xAPI Specification</a>.
+*/
 @JsonInclude(Include.NON_NULL)
 public class ActivityDefinition {
 

src/main/java/com/yetanalytics/xapi/model/Agent.java

@@ -4,6 +4,11 @@
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 
+/**
+* A concrete class representation of the Agent Component of the 
+* <a href="https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#2421-when-the-actor-objecttype-is-agent">9274.1.1 xAPI Specification</a>.
+* This class has no fields because it only contains what it inherits from AbstractActor.
+*/
 @JsonInclude(Include.NON_NULL)
 @JsonDeserialize
 public class Agent extends AbstractActor {

src/main/java/com/yetanalytics/xapi/model/Attachment.java

@@ -3,6 +3,10 @@
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 
+/**
+ * Class representation of the Attachment Component of the 
+ * <a href="https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#2411-attachments">9274.1.1 xAPI Specification</a>.
+ */
 @JsonInclude(Include.NON_NULL)
 public class Attachment {
 
@@ -13,7 +17,7 @@ public class Attachment {
     private Integer length;
     private String sha2;
     private String fileUrl;
-
+    
     public String getUsageType() {
         return usageType;
     }

src/main/java/com/yetanalytics/xapi/model/Context.java

@@ -4,6 +4,10 @@
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 
+/**
+* Class representation of the Context Component of the 
+* <a href="https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#246-context">9274.1.1 xAPI Specification</a>.
+*/
 @JsonInclude(Include.NON_NULL)
 public class Context {
 

src/main/java/com/yetanalytics/xapi/model/ContextActivities.java

@@ -7,6 +7,10 @@
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 
+/**
+* Class representation of the Context Activities Component of the 
+* <a href="https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#2462-contextactivities-property">9274.1.1 xAPI Specification</a>.
+*/
 @JsonInclude(Include.NON_NULL)
 public class ContextActivities {
 

src/main/java/com/yetanalytics/xapi/model/Extensions.java

@@ -13,6 +13,13 @@
 import com.yetanalytics.xapi.model.serializers.ExtensionSerializer;
 import com.yetanalytics.xapi.util.Mapper;
 
+/**
+ * A wrapper object for using <a href="https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#41-extensions">xAPI Extensions</a>.
+ * 
+ * The extension JSON data is stored in a combination of LinkedHashMap and 
+ * ArrayList depending on the JSON elements. It can be accessed directly
+ * or through a JSONPath API.
+ */
 @JsonDeserialize(using = ExtensionDeserializer.class)
 @JsonSerialize(using = ExtensionSerializer.class)
 public class Extensions {
@@ -23,14 +30,32 @@ public Extensions(Map<String, Object> input) {
         extMap = input;
     }
 
+    /**
+     * Sets an entry in the Extensions Map
+     * @param key the IRI key of the extension
+     * @param value The Collections API representation of the JSON Data
+     */
     public void put(String key, Object value) {
         extMap.put(key, value);
     }
 
+    /**
+     * Retrieve extension data
+     * @param key The IRI of the extension
+     * @return The Collections API representation of the JSON Data
+     */
     public Object get(String key) {
         return extMap.get(key);
     }
 
+    /**
+     * Attempt a JSONPath query of the Extension data.
+     * @param key The IRI key of the extension in which to perform the query
+     * @param jsonPathExpression A JSONPath query to perform in the Extension data
+     * @param typeKey The typereference for the type that the query is expecting to retrieve
+     * @param <T> The type that the query is expecting to convert the results to
+     * @return Object of type T that is the result of deserialization from the query
+     */
     @SuppressWarnings("unchecked")
     public <T> T read(String key, String jsonPathExpression, Class<T> typeKey) {
         try {
@@ -47,14 +72,25 @@ public <T> T read(String key, String jsonPathExpression, Class<T> typeKey) {
         return null;
     }
 
+    /**
+     * Remove an extension by IRI key
+     * @param key the IRI of the extension to remove
+     */
     public void remove(String key) {
         extMap.remove(key);
     }
 
+    /**
+     * Returns a set of all IRI Extension keys
+     * @return Set of IRI keys
+     */
     public Set<String> getKeys() {
         return extMap.keySet();
     }
-
+    /**
+     * Returns the full raw Extension Map as a HashMap&lt;String, Object&gt;
+     * @return The raw Extensions Map
+     */
     public Map<String, Object> getMap() {
         return extMap;
     }

src/main/java/com/yetanalytics/xapi/model/Group.java

@@ -6,6 +6,10 @@
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 
+/**
+* Class representation of the Group Component of the 
+* <a href="https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#2422-when-the-actor-objecttype-is-group">9274.1.1 xAPI Specification</a>.
+*/
 @JsonInclude(Include.NON_NULL)
 @JsonDeserialize
 public class Group extends AbstractActor {

src/main/java/com/yetanalytics/xapi/model/InteractionComponent.java

@@ -2,6 +2,10 @@
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonInclude.Include;
 
+/**
+* Class representation of the Interaction Component of the 
+* <a href="https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Data.md#interaction-components">9274.1.1 xAPI Specification</a>.
+*/
 @JsonInclude(Include.NON_NULL)
 public class InteractionComponent {