From 00fe74134bd559758feb9d0c7ce431c1db4fe21f Mon Sep 17 00:00:00 2001
From: Jonas Blatt <jonasblatt@uni-koblenz.de>
Date: Sat, 5 Oct 2019 10:46:00 +0200
Subject: [PATCH] Add documentation for simple pojo classes
---
.../fgbks/base/builder/AbstractBuilder.java | 16 ++++++++++++++++
.../fgbks/base/builder/DefaultBuilder.java | 3 +++
.../fgbks/base/domain/Description.java | 5 +++++
.../de/unikoblenz/fgbks/base/domain/Label.java | 5 +++++
.../de/unikoblenz/fgbks/base/domain/Message.java | 5 +++++
.../de/unikoblenz/fgbks/base/domain/Name.java | 5 +++++
.../fgbks/base/domain/StringValue.java | 5 +++++
.../de/unikoblenz/fgbks/base/domain/Text.java | 5 +++++
.../fgbks/base/json/JsonConfiguration.java | 3 +++
.../json/JsonSimpleValueObjectSerializer.java | 3 +++
.../base/json/PrivateVisibilityStrategy.java | 6 +++++-
.../fgbks/base/utils/UniqueIdGenerator.java | 7 +++++++
.../fgbks/base/value/AbstractValueObject.java | 7 +++++--
.../fgbks/base/value/SimpleValueObject.java | 3 +++
.../unikoblenz/fgbks/base/value/ValueObject.java | 4 +++-
15 files changed, 78 insertions(+), 4 deletions(-)
diff --git a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/builder/AbstractBuilder.java b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/builder/AbstractBuilder.java
index c40a5f46..a23b7d59 100644
--- a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/builder/AbstractBuilder.java
+++ b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/builder/AbstractBuilder.java
@@ -3,6 +3,12 @@ package de.unikoblenz.fgbks.base.builder;
import java.io.Serializable;
import java.lang.reflect.Field;
+/**
+ * A abstract builder for creating java pojo classes.
+ *
+ * @param <E> the type of the object being constructed
+ * @param <B> the instance type of the builder
+ */
public abstract class AbstractBuilder<E, B extends AbstractBuilder<E, B>> implements Serializable {
private static final String VALUE_FIELD_NAME = "value";
@@ -46,8 +52,18 @@ public abstract class AbstractBuilder<E, B extends AbstractBuilder<E, B>> implem
protected abstract E newInstance();
+ /**
+ * Check if the fields in the value object are valid.
+ */
protected abstract void validate();
+ /**
+ * Start the building process and return the finished object. While building the new object the
+ * function {@link DefaultBuilder#validate()} is called and should be passed without an exception.
+ * Every time this function is called a new instance of the type is returned.
+ *
+ * @return the new created object
+ */
public E build() {
validate();
E result = value;
diff --git a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/builder/DefaultBuilder.java b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/builder/DefaultBuilder.java
index 59bbb7d6..3b05f202 100644
--- a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/builder/DefaultBuilder.java
+++ b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/builder/DefaultBuilder.java
@@ -31,6 +31,9 @@ public class DefaultBuilder<E> extends AbstractBuilder<E, DefaultBuilder<E>> {
return this;
}
+ /**
+ * {@inheritDoc}
+ */
@Override
protected void validate() {
// nothing to validate
diff --git a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Description.java b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Description.java
index 206d0ac0..5f9382fd 100644
--- a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Description.java
+++ b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Description.java
@@ -2,12 +2,17 @@ package de.unikoblenz.fgbks.base.domain;
import de.unikoblenz.fgbks.base.value.AbstractStringValueObject;
+/**
+ * A value object representing a description.
+ */
public class Description extends AbstractStringValueObject {
+ /** Create a new copy of the given description object. */
public Description(Description initialValue) {
this(initialValue.getValue());
}
+ /** Create a description object with the given {@code initialValue}. */
public Description(String initialValue) {
super(initialValue);
}
diff --git a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Label.java b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Label.java
index 2f462485..d7c899f1 100644
--- a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Label.java
+++ b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Label.java
@@ -2,12 +2,17 @@ package de.unikoblenz.fgbks.base.domain;
import de.unikoblenz.fgbks.base.value.AbstractStringValueObject;
+/**
+ * A value object representing a label.
+ */
public class Label extends AbstractStringValueObject {
+ /** Create a new copy of the given label object. */
public Label(Label initialValue) {
this(initialValue.getValue());
}
+ /** Create a label object with the given {@code initialValue}. */
public Label(String initialValue) {
super(initialValue);
}
diff --git a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Message.java b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Message.java
index cff5d051..76d1c718 100644
--- a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Message.java
+++ b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Message.java
@@ -2,12 +2,17 @@ package de.unikoblenz.fgbks.base.domain;
import de.unikoblenz.fgbks.base.value.AbstractStringValueObject;
+/**
+ * A value object representing a message.
+ */
public class Message extends AbstractStringValueObject {
+ /** Create a new copy of the given message object. */
public Message(Message initialValue) {
this(initialValue.getValue());
}
+ /** Create a message object with the given {@code initialValue}. */
public Message(String initialValue) {
super(initialValue);
}
diff --git a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Name.java b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Name.java
index cdba8c78..6cbfb2b5 100644
--- a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Name.java
+++ b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Name.java
@@ -2,12 +2,17 @@ package de.unikoblenz.fgbks.base.domain;
import de.unikoblenz.fgbks.base.value.AbstractStringValueObject;
+/**
+ * A value object representing a name.
+ */
public class Name extends AbstractStringValueObject {
+ /** Create a new copy of the given name object. */
public Name(Name initialValue) {
this(initialValue.getValue());
}
+ /** Create a name object with the given {@code initialValue}. */
public Name(String initialValue) {
super(initialValue);
}
diff --git a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/StringValue.java b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/StringValue.java
index 83cb5791..03b01255 100644
--- a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/StringValue.java
+++ b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/StringValue.java
@@ -2,12 +2,17 @@ package de.unikoblenz.fgbks.base.domain;
import de.unikoblenz.fgbks.base.value.AbstractStringValueObject;
+/**
+ * A value object representing a string value.
+ */
public class StringValue extends AbstractStringValueObject {
+ /** Create a new copy of the given string value object. */
public StringValue(StringValue initialValue) {
this(initialValue.getValue());
}
+ /** Create a string value object with the given {@code initialValue}. */
public StringValue(String initialValue) {
super(initialValue);
}
diff --git a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Text.java b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Text.java
index f57b2fab..cc58163c 100644
--- a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Text.java
+++ b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/domain/Text.java
@@ -2,12 +2,17 @@ package de.unikoblenz.fgbks.base.domain;
import de.unikoblenz.fgbks.base.value.AbstractStringValueObject;
+/**
+ * A value object representing a text.
+ */
public class Text extends AbstractStringValueObject {
+ /** Create a new copy of the given text object. */
public Text(Text initialValue) {
this(initialValue.getValue());
}
+ /** Create a text object with the given {@code initialValue}. */
public Text(String initialValue) {
super(initialValue);
}
diff --git a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/json/JsonConfiguration.java b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/json/JsonConfiguration.java
index c8410ce3..bba70ba3 100644
--- a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/json/JsonConfiguration.java
+++ b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/json/JsonConfiguration.java
@@ -6,6 +6,9 @@ import javax.json.bind.JsonbConfig;
import javax.ws.rs.ext.ContextResolver;
import javax.ws.rs.ext.Provider;
+/**
+ * A provider for the configuration of jsonb handling. See {@link ContextResolver}
+ */
@Provider
public class JsonConfiguration implements ContextResolver<Jsonb> {
diff --git a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/json/JsonSimpleValueObjectSerializer.java b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/json/JsonSimpleValueObjectSerializer.java
index a5a6eb7b..b3dcb66a 100644
--- a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/json/JsonSimpleValueObjectSerializer.java
+++ b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/json/JsonSimpleValueObjectSerializer.java
@@ -5,6 +5,9 @@ import javax.json.bind.serializer.JsonbSerializer;
import javax.json.bind.serializer.SerializationContext;
import javax.json.stream.JsonGenerator;
+/**
+ * A json serializer for simple value objects ({@link SimpleValueObject})
+ */
public class JsonSimpleValueObjectSerializer implements JsonbSerializer<SimpleValueObject> {
@Override
diff --git a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/json/PrivateVisibilityStrategy.java b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/json/PrivateVisibilityStrategy.java
index 4eb02b8a..8ab6492b 100644
--- a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/json/PrivateVisibilityStrategy.java
+++ b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/json/PrivateVisibilityStrategy.java
@@ -7,6 +7,10 @@ import javax.json.bind.annotation.JsonbProperty;
import javax.json.bind.annotation.JsonbTransient;
import javax.json.bind.config.PropertyVisibilityStrategy;
+/**
+ * The private visibility strategy is used in {@link JsonConfiguration} for the visibility for json
+ * serialization.
+ */
public class PrivateVisibilityStrategy implements PropertyVisibilityStrategy {
@Override
@@ -17,7 +21,7 @@ public class PrivateVisibilityStrategy implements PropertyVisibilityStrategy {
@Override
public boolean isVisible(Method method) {
return Modifier.isPublic(method.getModifiers())
- && !method.isAnnotationPresent(JsonbTransient.class)
+ && !method.isAnnotationPresent(JsonbTransient.class)
|| method.isAnnotationPresent(JsonbProperty.class);
}
}
diff --git a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/utils/UniqueIdGenerator.java b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/utils/UniqueIdGenerator.java
index 58fb304e..2a1291c0 100644
--- a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/utils/UniqueIdGenerator.java
+++ b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/utils/UniqueIdGenerator.java
@@ -1,11 +1,18 @@
package de.unikoblenz.fgbks.base.utils;
+/**
+ * Generate a thread safe synchronized unique application scoped long id by calling the method
+ * {@link UniqueIdGenerator#getNextId()}
+ */
public class UniqueIdGenerator {
private static volatile long id = 0;
private UniqueIdGenerator() {}
+ /**
+ * Return the next id. This method is synchronized.
+ */
public static synchronized long getNextId() {
return id++;
}
diff --git a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/value/AbstractValueObject.java b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/value/AbstractValueObject.java
index 2a4f8c69..fe19ca33 100644
--- a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/value/AbstractValueObject.java
+++ b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/value/AbstractValueObject.java
@@ -6,6 +6,9 @@ import java.io.Serializable;
import java.util.Arrays;
import java.util.stream.Collectors;
+/**
+ * A abstract value object contains a array of objects.
+ */
public abstract class AbstractValueObject implements Serializable, ValueObject {
private transient Object[] values;
@@ -45,8 +48,8 @@ public abstract class AbstractValueObject implements Serializable, ValueObject {
public String toString() {
return "["
+ Arrays.stream(getValues())
- .map(o -> nonNull(o) ? o.toString() : "null")
- .collect(Collectors.joining(", "))
+ .map(o -> nonNull(o) ? o.toString() : "null")
+ .collect(Collectors.joining(", "))
+ "]";
}
diff --git a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/value/SimpleValueObject.java b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/value/SimpleValueObject.java
index 69272d0c..13103a43 100644
--- a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/value/SimpleValueObject.java
+++ b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/value/SimpleValueObject.java
@@ -1,5 +1,8 @@
package de.unikoblenz.fgbks.base.value;
+/**
+ * A simple value object, which contains a value of a given type V.
+ */
public interface SimpleValueObject<V> extends ValueObject {
V getValue();
diff --git a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/value/ValueObject.java b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/value/ValueObject.java
index 5b13cc6c..2cb3798f 100644
--- a/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/value/ValueObject.java
+++ b/dmnverifierapi/src/main/java/de/unikoblenz/fgbks/base/value/ValueObject.java
@@ -2,7 +2,9 @@ package de.unikoblenz.fgbks.base.value;
import java.io.Serializable;
-@SuppressWarnings("checkstyle:all")
+/**
+ * A interface for a value object.
+ */
public interface ValueObject extends Serializable {
String VALUE = "value";
--
GitLab