Merge pull request #298 from filip26/feat/processing-limits

Introduce JsonLdOptions.timeout() methods

README.md

@@ -111,6 +111,8 @@ implementation("org.glassfish:jakarta.json:2.0.1")
 
 Titanium provides high-level [JsonLd](https://javadoc.io/doc/com.apicatalog/titanium-json-ld/latest/com/apicatalog/jsonld/JsonLd.html) API to interact with the processor.
 
+#### Transformations
+
 ```javascript
 
 // Expansion
@@ -141,8 +143,9 @@ JsonLd.frame("https://example/document.jsonld", "https://example/frame.jsonld").
 
 ```
 
+#### Local JSON Document
+
 ```javascript
-// Local document
 Document document = JsonDocument.of(InputStream) or JsonDocument.of(Reader) ...
 
 JsonLd.expand(document).get();
@@ -151,6 +154,16 @@ JsonLd.compact(document, contextDocument).get();
 ...
 ```
 
+#### Processing Timeout
+A processor gets terminated eventually after a specified time. Please note 
+the duration does not cover `DocumentLoader` processing time. 
+You have to set-up a read timeout separately.
+
+```javascript
+// since 1.4.0 -
+JsonLd.expand(...).timeout(duration)...get();
+```
+
 #### HTTP Document Loader Timeout
 Configure and set a custom HTTP document loader instance.
 

src/main/java/com/apicatalog/jsonld/JsonLdOptions.java

@@ -16,6 +16,7 @@
 package com.apicatalog.jsonld;
 
 import java.net.URI;
+import java.time.Duration;
 
 import com.apicatalog.jsonld.context.cache.Cache;
 import com.apicatalog.jsonld.context.cache.LruCache;
@@ -29,9 +30,11 @@
 import jakarta.json.JsonValue;
 
 /**
- * The {@link JsonLdOptions} type is used to pass various options to the processor.
+ * The {@link JsonLdOptions} type is used to pass various options to the
+ * processor.
  *
- * @see <a href="https://www.w3.org/TR/json-ld11-api/#the-jsonldoptions-type">The
+ * @see <a href=
+ * "https://www.w3.org/TR/json-ld11-api/#the-jsonldoptions-type">The
  * JsonLdOptions Specification.</a>
  *
  */
@@ -48,35 +51,35 @@ public enum RdfDirection {
  public static final boolean DEFAULT_URI_VALIDATION = true;
 
  /**
- * The base IRI to use when expanding or compacting the document.
- * If set, this overrides the input document's IRI.
+ * The base IRI to use when expanding or compacting the document. If set, this
+ * overrides the input document's IRI.
  */
  private URI base;
 
  /**
- * If set to true, the JSON-LD processor replaces arrays with
- * just one element with that element during compaction.
- * If set to false, all arrays will remain arrays
- * even if they have just one element.
+ * If set to true, the JSON-LD processor replaces arrays with just one element
+ * with that element during compaction. If set to false, all arrays will remain
+ * arrays even if they have just one element.
  */
  private boolean compactArrays;
 
  /**
- * Determines if IRIs are compacted relative to the base option
- * or document location when compacting.
+ * Determines if IRIs are compacted relative to the base option or document
+ * location when compacting.
  */
  private boolean compactToRelative;
 
  /**
- * The callback of the loader to be used to retrieve remote documents and contexts,
- * implementing the LoadDocumentCallback. If specified, it is used to retrieve
- * remote documents and contexts; otherwise, if not specified,
- *  the processor's built-in loader is used.
+ * The callback of the loader to be used to retrieve remote documents and
+ * contexts, implementing the LoadDocumentCallback. If specified, it is used to
+ * retrieve remote documents and contexts; otherwise, if not specified, the
+ * processor's built-in loader is used.
  */
  private DocumentLoader documentLoader;
 
  /**
- * A context that is used to initialize the active context when expanding a document.
+ * A context that is used to initialize the active context when expanding a
+ * document.
  */
  private Document expandContext;
 
@@ -121,6 +124,8 @@ public enum RdfDirection {
  private Cache<String, Document> documentCache;
 
  private boolean uriValidation;
+
+ private Duration timeout;
 
  public JsonLdOptions() {
  this(SchemeRouter.defaultInstance());
@@ -157,6 +162,7 @@ public JsonLdOptions(DocumentLoader loader) {
  this.contextCache = new LruCache<>(256);
  this.documentCache = null;
  this.uriValidation = DEFAULT_URI_VALIDATION;
+ this.timeout = null;
  }
 
  public JsonLdOptions(JsonLdOptions options) {
@@ -188,6 +194,7 @@ public JsonLdOptions(JsonLdOptions options) {
  this.contextCache = options.contextCache;
  this.documentCache = options.documentCache;
  this.uriValidation = options.uriValidation;
+ this.timeout = options.timeout;
  }
 
  /**
@@ -215,8 +222,8 @@ public boolean isCompactArrays() {
  }
 
  /**
- * Determines if IRIs are compacted relative to the {@link #getBase()} option
- * or document location when
+ * Determines if IRIs are compacted relative to the {@link #getBase()} option or
+ * document location when
  * <a href="https://www.w3.org/TR/json-ld11-api/#dfn-compact">compacting</a>.
  *
  * @return <code>true</code> if IRI relativization is enabled
@@ -227,9 +234,9 @@ public boolean isCompactToRelative() {
 
  /**
  * The callback of the loader to be used to retrieve remote documents and
- * contexts, implementing the {@link DocumentLoader}. If specified, it is
- * used to retrieve remote documents and contexts; otherwise, if not specified,
- * the processor's built-in loader is used.
+ * contexts, implementing the {@link DocumentLoader}. If specified, it is used
+ * to retrieve remote documents and contexts; otherwise, if not specified, the
+ * processor's built-in loader is used.
  *
  * @return the loader or <code>null</code> is is not set
  */
@@ -446,7 +453,8 @@ public boolean isRdfStar() {
  }
 
  /**
- * Experimental: Enables JSON-LD-STAR extension. Only expansion is supported. Disabled by default.
+ * Experimental: Enables JSON-LD-STAR extension. Only expansion is supported.
+ * Disabled by default.
  *
  * @see <a href="https://json-ld.github.io/json-ld-star">JSON-LD-STAR Draft</a>
  *
@@ -457,7 +465,8 @@ public void setRdfStar(boolean rdfStar) {
 
  /**
  * if disabled only URIs required for processing are parsed and validated.
- * Disabling URI validation might improve performance depending on the number of processed URIs.
+ * Disabling URI validation might improve performance depending on the number of
+ * processed URIs.
  * <p>
  * <b>Warning:</b> Disabled validation could cause an invalid output.
  * </p>
@@ -473,7 +482,8 @@ public boolean isUriValidation() {
 
  /**
  * if disabled only URIs required for processing are parsed and validated.
- * Disabling URI validation might improve performance depending on the number of processed URIs.
+ * Disabling URI validation might improve performance depending on the number of
+ * processed URIs.
  * <p>
  * <b>Warning:</b> Disabled validation could cause an invalid output.
  * </p>
@@ -486,4 +496,31 @@ public boolean isUriValidation() {
  public void setUriValidation(boolean enabled) {
  this.uriValidation = enabled;
  }
+
+ /**
+ * A processing timeout. An exception is thrown when a processing time exceeds
+ * the duration, if set. There is no currency that processing gets terminated
+ * immediately, but eventually. 
+ * 
+ * Please note, the timeout does not include time consumed by
+ * {@link DocumentLoader}.
+ * 
+ * @return a duration after which a processing is prematurely terminated.
+ */
+ public Duration getTimeout() {
+ return timeout;
+ }
+
+ /**
+ * Set a pressing timeout. A processing is eventually terminated after the 
+ * specified duration. Set <code>null</code> for no timeout. 
+ * 
+ * Please note, the timeout does not include time consumed by
+ * {@link DocumentLoader}.
+ * 
+ * @param timeout to limit processing time
+ */
+ public void setTimeout(Duration timeout) {
+ this.timeout = timeout;
+ }
 }

src/main/java/com/apicatalog/jsonld/compaction/Compaction.java

@@ -25,7 +25,6 @@
 
 import com.apicatalog.jsonld.JsonLdError;
 import com.apicatalog.jsonld.JsonLdErrorCode;
-import com.apicatalog.jsonld.JsonLdVersion;
 import com.apicatalog.jsonld.context.ActiveContext;
 import com.apicatalog.jsonld.context.TermDefinition;
 import com.apicatalog.jsonld.json.JsonMapBuilder;
@@ -169,7 +168,7 @@ public JsonValue compact(final String activeProperty, final JsonValue element) t
  // 7.
  if ((elementObject.containsKey(Keywords.VALUE)
  || elementObject.containsKey(Keywords.ID))
- && (!activeContext.getOptions().isRdfStar() || !elementObject.containsKey(Keywords.ANNOTATION))) {
+ && (!activeContext.runtime().isRdfStar() || !elementObject.containsKey(Keywords.ANNOTATION))) {
 
  final JsonValue result = activeContext.valueCompaction().compact(elementObject, activeProperty);
 
@@ -242,7 +241,7 @@ public JsonValue compact(final String activeProperty, final JsonValue element) t
  compactedValue = JsonUtils.toJsonValue(activeContext.uriCompaction().compact(((JsonString) expandedValue).getString()));
 
  // json-ld-star
- } else if (activeContext.getOptions().isRdfStar() && NodeObject.isEmbeddedNode(expandedValue)) {
+ } else if (activeContext.runtime().isRdfStar() && NodeObject.isEmbeddedNode(expandedValue)) {
  compactedValue = Compaction.with(activeContext)
  .compactArrays(compactArrays)
  .ordered(ordered)
@@ -294,7 +293,7 @@ public JsonValue compact(final String activeProperty, final JsonValue element) t
 
  // 12.2.4.
  final boolean asArray = !compactArrays
- || (activeContext.inMode(JsonLdVersion.V1_1)
+ || (activeContext.runtime().isV11()
  && activeContext.getTerm(alias).filter(t -> t.hasContainerMapping(Keywords.SET)).isPresent());
 
  // 12.2.5.