This is an automated email from the ASF dual-hosted git repository.
bdelacretaz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-whiteboard.git
The following commit(s) were added to refs/heads/master by this push:
new 3805de1 SLING-10551 - docs tweak + add syntax capability
3805de1 is described below
commit 3805de101ddb64650c7b0f7c0cc5222471fbdfb8
Author: Bertrand Delacretaz <[email protected]>
AuthorDate: Wed Jul 7 16:58:00 2021 +0200
SLING-10551 - docs tweak + add syntax capability
---
sling-org-apache-sling-graphql-schema/bnd.bnd | 3 ++-
.../schema/aggregator/api/SchemaAggregator.java | 14 ++++++++++--
.../impl/BundleEntryPartialProvider.java | 3 +++
.../aggregator/impl/DefaultSchemaAggregator.java | 10 +--------
.../aggregator/impl/PartialSchemaProvider.java | 4 ++--
.../aggregator/impl/ProviderBundleTracker.java | 4 ++--
.../servlet/SchemaAggregatorServlet.java | 26 +++++++++++++++++++++-
.../apache/sling/graphql/schema/aggregator/U.java | 7 +++---
.../aggregator/it/SchemaAggregatorServletIT.java | 4 ++--
9 files changed, 53 insertions(+), 22 deletions(-)
diff --git a/sling-org-apache-sling-graphql-schema/bnd.bnd
b/sling-org-apache-sling-graphql-schema/bnd.bnd
index d1c6fc4..5cbd9b4 100644
--- a/sling-org-apache-sling-graphql-schema/bnd.bnd
+++ b/sling-org-apache-sling-graphql-schema/bnd.bnd
@@ -1 +1,2 @@
-# nothing so far
\ No newline at end of file
+# Define the syntax that we support for schema partials
+Provide-Capability:
org.apache.sling.graphql.schema.aggregator;syntax:Version="0.1"
\ No newline at end of file
diff --git
a/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/api/SchemaAggregator.java
b/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/api/SchemaAggregator.java
index 540adfb..cba4fe2 100644
---
a/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/api/SchemaAggregator.java
+++
b/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/api/SchemaAggregator.java
@@ -26,6 +26,16 @@ import org.osgi.annotation.versioning.ConsumerType;
@ConsumerType
public interface SchemaAggregator {
- /** Writes an aggregated Schema to the supplied Writer */
- void aggregate(Writer target, String ... providerNames) throws IOException;
+ /** Aggregate the schemas supplied by partial schame providers which match
the exact names
+ * or patterns supplied.
+ *
+ * @param target where to write the output
+ *
+ * @param providerNamesOrRegexp a value that starts and ends with a slash
is used a a regular
+ * expression to match provider names (after removing the starting
and ending slash), other
+ * values are used as exact provider names, which are then required.
+ *
+ * @throws IOException if an exact provider name is not found
+ */
+ void aggregate(Writer target, String ... providerNamesOrRegexp) throws
IOException;
}
diff --git
a/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/BundleEntryPartialProvider.java
b/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/BundleEntryPartialProvider.java
index 027d9dc..5758f8f 100644
---
a/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/BundleEntryPartialProvider.java
+++
b/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/BundleEntryPartialProvider.java
@@ -51,6 +51,9 @@ class BundleEntryPartialProvider implements
PartialSchemaProvider {
return lastDot > 0 ? result.substring(0, lastDot) : result;
}
+ /** @return a BundleEntryPartialProvider for the entryPath in
+ * the supplied Bundle, or null if none can be built.
+ */
static BundleEntryPartialProvider forBundle(Bundle b, String entryPath) {
final URL entry = b.getEntry(entryPath);
if(entry == null) {
diff --git
a/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/DefaultSchemaAggregator.java
b/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/DefaultSchemaAggregator.java
index 5c9a0de..fd40d04 100644
---
a/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/DefaultSchemaAggregator.java
+++
b/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/DefaultSchemaAggregator.java
@@ -21,8 +21,6 @@ package org.apache.sling.graphql.schema.aggregator.impl;
import java.io.IOException;
import java.io.Writer;
-import java.util.ArrayList;
-import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.regex.Pattern;
@@ -76,13 +74,7 @@ public class DefaultSchemaAggregator implements
SchemaAggregator {
target.write(String.format("%n# %s.source=%s%n",
getClass().getSimpleName(), psp.getName()));
}
- /** Aggregate the schemas supplied by providers which match the exact
names or patterns supplied
- * @param target where to write the output
- * @param providerNamesOrRegexp a value that starts and ends with a slash
is used a a regular
- * expression to match provider names (after removing the starting
and ending slash), other
- * values are used as exact provider names.
- * @throws IOException if an exact provider name is not found
- */
+ @Override
public void aggregate(Writer target, String ...providerNamesOrRegexp)
throws IOException {
final String info = String.format("Schema aggregated by %s%n",
getClass().getSimpleName());
target.write(String.format("# %s", info));
diff --git
a/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/PartialSchemaProvider.java
b/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/PartialSchemaProvider.java
index c25fd12..be3f87b 100644
---
a/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/PartialSchemaProvider.java
+++
b/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/PartialSchemaProvider.java
@@ -24,10 +24,10 @@ import java.io.Reader;
import org.jetbrains.annotations.NotNull;
import org.osgi.annotation.versioning.ProviderType;
-/** A provider of partial OSGI schemas */
+/** A provider of partial GraphQL schemas */
@ProviderType
public interface PartialSchemaProvider {
- /** A unique name for this partial */
+ /** A unique name for this partial, partials duplicate names are ignored
with a WARN log message */
@NotNull String getName();
/** Return a Reader that provides the contents of the specific schema
section, like "query" or "mutation" */
diff --git
a/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/ProviderBundleTracker.java
b/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/ProviderBundleTracker.java
index 2abc914..2944c4d 100644
---
a/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/ProviderBundleTracker.java
+++
b/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/impl/ProviderBundleTracker.java
@@ -31,8 +31,8 @@ import org.osgi.util.tracker.BundleTracker;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
-/** Tracks bundles which provide partial schemas, and registers
- * a {@PartialSchemaProvider} service for each partial schema
+/** Tracks bundles which provide partial schemas, and collects
+ * the corresponding set of {@PartialSchemaProvider}
*/
public class ProviderBundleTracker extends BundleTracker<Object> {
diff --git
a/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/servlet/SchemaAggregatorServlet.java
b/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/servlet/SchemaAggregatorServlet.java
index a0e7d1c..4ccfa03 100644
---
a/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/servlet/SchemaAggregatorServlet.java
+++
b/sling-org-apache-sling-graphql-schema/src/main/java/org/apache/sling/graphql/schema/aggregator/servlet/SchemaAggregatorServlet.java
@@ -53,9 +53,33 @@ import org.slf4j.LoggerFactory;
})
@Designate(ocd = SchemaAggregatorServlet.Config.class, factory=true)
+/** Servlet that aggregates GraphQL schemas provided by bundles
+ * that have a Sling-GraphQL-Schema header. The value of that
+ * header is a path under which bundle entries are found which
+ * follow the rules defined by our minimal parser to be used
+ * as partial GraphQL schemas ("partial").
+ *
+ * The name of such a partial is defined by its filename in the bundle,
+ * omitting the file extension. A partial found at /p/partial.1.txt
+ * is named 'partial.1', for example.
+ *
+ * The servlet must be mounted with at least one selector, and the first
selector
+ * of the request is mapped to a configurable set of names or regular
+ * expressions used to select partial schema providers by name.
+ *
+ * If used with the Sling GraphQL Core module, the servlet must be
+ * configured with the 'GQLschema' extension as that module makes
+ * an internal request with this extension (+ selectors) to retrieve
+ * a GraphQL schema that uses the SDL syntax.
+ *
+ * Multiple selectors can be mapped to different sets of partial names
+ * or regular expressions. This can be used to define "API planes" which
+ * each have their own GraphQL schemas and are each addressed with a
+ * specific selector.
+ */
public class SchemaAggregatorServlet extends SlingSafeMethodsServlet {
- private final Logger log = LoggerFactory.getLogger(getClass().getName());
+ private final transient Logger log =
LoggerFactory.getLogger(getClass().getName());
@ObjectClassDefinition(
name = "Apache Sling GraphQL Schema Aggregator Servlet",
diff --git
a/sling-org-apache-sling-graphql-schema/src/test/java/org/apache/sling/graphql/schema/aggregator/U.java
b/sling-org-apache-sling-graphql-schema/src/test/java/org/apache/sling/graphql/schema/aggregator/U.java
index 85417d7..51aff0b 100644
---
a/sling-org-apache-sling-graphql-schema/src/test/java/org/apache/sling/graphql/schema/aggregator/U.java
+++
b/sling-org-apache-sling-graphql-schema/src/test/java/org/apache/sling/graphql/schema/aggregator/U.java
@@ -64,14 +64,15 @@ public class U {
return b;
}
- public static Option providerBundleOption(String symbolicName, String ...
schemaNames) {
+ public static Option tinyProviderBundle(String symbolicName, String ...
partialsNames) {
final String schemaPath = symbolicName + "/schemas";
final TinyBundle b = bundle()
.set(ProviderBundleTracker.SCHEMA_PATH_HEADER, schemaPath)
- .set(Constants.BUNDLE_SYMBOLICNAME, symbolicName);
+ .set(Constants.BUNDLE_SYMBOLICNAME, symbolicName)
+ .set(Constants.REQUIRE_CAPABILITY,
"org.apache.sling.graphql.schema.aggregator;filter:=\"(syntax>=0.1)\"")
;
- for(String name : schemaNames) {
+ for(String name : partialsNames) {
final String resourcePath = schemaPath + "/" + name + ".txt";
final String content = "Fake schema at " + resourcePath;
b.add(resourcePath, new ByteArrayInputStream(content.getBytes()));
diff --git
a/sling-org-apache-sling-graphql-schema/src/test/java/org/apache/sling/graphql/schema/aggregator/it/SchemaAggregatorServletIT.java
b/sling-org-apache-sling-graphql-schema/src/test/java/org/apache/sling/graphql/schema/aggregator/it/SchemaAggregatorServletIT.java
index 96eff50..1d50c2b 100644
---
a/sling-org-apache-sling-graphql-schema/src/test/java/org/apache/sling/graphql/schema/aggregator/it/SchemaAggregatorServletIT.java
+++
b/sling-org-apache-sling-graphql-schema/src/test/java/org/apache/sling/graphql/schema/aggregator/it/SchemaAggregatorServletIT.java
@@ -42,8 +42,8 @@ public class SchemaAggregatorServletIT extends
SchemaAggregatorTestSupport {
return new Option[]{
baseConfiguration(),
- U.providerBundleOption("firstProvider", "firstA",
"firstB","secondN"),
- U.providerBundleOption("secondProvider", "secondA",
"secondB","secondOther"),
+ U.tinyProviderBundle("firstProvider", "firstA",
"firstB","secondN"),
+ U.tinyProviderBundle("secondProvider", "secondA",
"secondB","secondOther"),
// The aggregator servlet is disabled by default
factoryConfiguration(AGGREGATOR_SERVLET_CONFIG_PID)
