doc: improve javadoc for context class

Author: Pfeil

src/main/java/edu/kit/datamanager/ro_crate/context/RoCrateMetadataContext.java

@@ -39,14 +39,16 @@ public class RoCrateMetadataContext implements CrateMetadataContext {
   protected final HashMap<String, String> other = new HashMap<>();
 
   /**
-   * Default constructor for the creation of the default context.
+   * Default constructor for the creation of the v1.1 default context.
    */
   public RoCrateMetadataContext() {
     this.addToContextFromUrl(DEFAULT_CONTEXT);
   }
 
   /**
    * Constructor for creating the context from a list of url.
+   * <p>
+   * Note: Does NOT contain the default context if not explicitly given!
    *
    * @param urls the url list with different context.
    */
@@ -56,6 +58,8 @@ public RoCrateMetadataContext(Collection<String> urls) {
 
   /**
    * Constructor for creating the context from a json object.
+   * <p>
+   * Note: Does NOT contain the default context if not explicitly given!
    *
    * @param context the Json object of the context.
    */
@@ -84,6 +88,28 @@ public RoCrateMetadataContext(JsonNode context) {
     }
   }
 
+  /**
+   * Converts the context into a JSON-LD representation.
+   * <p>
+   * The resulting JSON structure depends on the content:
+   * - If there's only one URL and no key-value pairs: {"@context": "url"}
+   * - If there are multiple URLs and/or key-value pairs: {"@context": ["url1", "url2", {"key1": "value1", "key2": "value2"}]}
+   * <p>
+   * Example output:
+   * <pre>
+   * {
+   *   "@context": [
+   *     "https://w3id.org/ro/crate/1.1/context",
+   *     {
+   *       "schema": "http://schema.org/",
+   *       "rdfs": "http://www.w3.org/2000/01/rdf-schema#"
+   *     }
+   *   ]
+   * }
+   * </pre>
+   *
+   * @return an ObjectNode containing the JSON-LD context representation
+   */
   @Override
   public ObjectNode getContextJsonEntity() {
     ObjectMapper objectMapper = MyObjectMapper.getMapper();
@@ -107,6 +133,21 @@ public ObjectNode getContextJsonEntity() {
     return finalNode;
   }
 
+  /**
+   * Checks if the given entity is valid according to the context.
+   * <p>
+   * - full URLs in the @type and field names are considered valid without further checks.
+   * - The "@id" value is treated as a special case, where it refers to the entity's ID.
+   * - The "@json" type is a linked data built-in type and is always considered valid.
+   * - If a type or field name is not found in the context, it will print an error message and return false.
+   * - This method checks both the types in the @type array and the field names in the entity's properties.
+   * - Prefixes in the context are considered valid if they match the context keys.
+   * - Suffixes after a valid prefix are considered valid in any case. This is not perfect,
+   *   but it would be hard to handle correctly.
+   *
+   * @param entity the entity to check
+   * @return true if the entity is valid, false otherwise
+   */
   @Override
   public boolean checkEntity(AbstractEntity entity) {
     ObjectMapper objectMapper = MyObjectMapper.getMapper();
@@ -161,6 +202,13 @@ public boolean checkEntity(AbstractEntity entity) {
     return true;
   }
 
+  /**
+   * Adds a URL to the context.
+   * <p>
+   * It will try to fetch the context from the URL.
+   *
+   * @param url the URL to add
+   */
   @Override
   public void addToContextFromUrl(String url) {
     this.urls.add(url);
@@ -200,18 +248,31 @@ public void addToContextFromUrl(String url) {
         }));
   }
 
+    /**
+     * Adds a key-value pair to the context.
+     *
+     * @param key   the key to add. It may be a prefix or a term.
+     * @param value the value to add
+     */
   @Override
   public void addToContext(String key, String value) {
     this.contextMap.put(key, value);
     this.other.put(key, value);
   }
 
+  /**
+   * @param key the key for the value to retrieve.
+   * @return the value of the key if it exists in the context, null otherwise.
+   */
   @Override
   public String getValueOf(String key) {
     return Optional.ofNullable(this.contextMap.get(key))
             .orElseGet(() -> this.other.get(key));
   }
 
+  /**
+   * @return the set of all keys in the context.
+   */
   @Override
   public Set<String> getKeys() {
     List<String> merged = new ArrayList<>();
@@ -220,6 +281,11 @@ public Set<String> getKeys() {
     return Set.copyOf(merged);
   }
 
+  /**
+   * @return a map of all key-value pairs in the context. Note that some pairs may come
+   * from URLs or a pair may not be available as a context was not successfully resolved
+   * from a URL.
+   */
   @Override
   public Map<String, String> getPairs() {
     Map<String, String> merged = new HashMap<>();
@@ -228,13 +294,18 @@ public Map<String, String> getPairs() {
     return Map.copyOf(merged);
   }
 
-
+  /**
+   * @param key the key to delete from the context.
+   */
   @Override
   public void deleteValuePairFromContext(String key) {
     this.contextMap.remove(key);
     this.other.remove(key);
   }
 
+  /**
+   * @param url the URL to delete from the context.
+   */
   @Override
   public void deleteUrlFromContext(String url) {
     this.urls.remove(url);