ExecTracking with Dispatchers Proposal

jena-arq/src/main/java/org/apache/jena/sparql/ARQConstants.java

@@ -326,6 +326,13 @@ public class ARQConstants
     public static final Symbol registryExtensions =
         SystemARQ.allocSymbol("registryExtensions") ;
 
-    public static void init() {}
+    /** The query dispatcher registry key */
+    public static final Symbol registryQueryDispatchers =
+        SystemARQ.allocSymbol("registryQueryDispatchers") ;
+
+    /** The update dispatcher registry key */
+    public static final Symbol registryUpdateDispatchers =
+        SystemARQ.allocSymbol("registryUpdateDispatchers") ;
 
+    public static void init() {}
 }

jena-arq/src/main/java/org/apache/jena/sparql/engine/Timeouts.java

@@ -236,13 +236,23 @@ public static String toString(Timeout timeout) {
        return result;
     }
 
-    // Set times from context if not set directly. e..g Context provides default values.
-    // Contrast with SPARQLQueryProcessor where the context is limiting values of the protocol parameter.
+    /**
+     * Update unset values in the builder with values from the context.
+     *
+     * Set times from context if not set directly, i.e. context provides default values.
+     * Contrast with SPARQLQueryProcessor where the context is limiting values of the protocol parameter.
+     */
     public static void applyDefaultQueryTimeoutFromContext(TimeoutBuilderImpl builder, Context cxt) {
         Timeout queryTimeout = extractQueryTimeout(cxt);
         applyDefaultTimeout(builder, queryTimeout);
     }
 
+    /** Update unset values in the builder with values from the context. */
+    public static void applyDefaultUpdateTimeoutFromContext(TimeoutBuilderImpl builder, Context cxt) {
+        Timeout queryTimeout = extractUpdateTimeout(cxt);
+        applyDefaultTimeout(builder, queryTimeout);
+    }
+
     /** Returns milliseconds if the given time unit is null. */
     private static TimeUnit nullToMillis(TimeUnit unit) {
         return unit != null ? unit : TimeUnit.MILLISECONDS;

jena-arq/src/main/java/org/apache/jena/sparql/engine/dispatch/ChainingQueryDispatcher.java

@@ -0,0 +1,42 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ *   SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.apache.jena.sparql.engine.dispatch;
+
+import org.apache.jena.query.Query;
+import org.apache.jena.sparql.core.DatasetGraph;
+import org.apache.jena.sparql.exec.QueryExec;
+import org.apache.jena.sparql.util.Context;
+
+/**
+ * A query dispatcher is responsible for taking a query and
+ * preparing it for the execution against a dataset.
+ * The result is a {@linkplain QueryExec} instance.
+ *
+ * Query dispatchers form a chain, and a {@link ChainingQueryDispatcher} acts as a link in such a chain.
+ * A ChainingQueryDispatcher instance can choose to process a query by itself or to delegate processing to the
+ * remainder of the chain.
+ *
+ * @see QueryDispatcherRegistry
+ */
+public interface ChainingQueryDispatcher {
+    QueryExec create(Query query, DatasetGraph dsg, Context context, QueryDispatcher chain);
+}

jena-arq/src/main/java/org/apache/jena/sparql/engine/dispatch/ChainingUpdateDispatcher.java

@@ -0,0 +1,42 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ *   SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.apache.jena.sparql.engine.dispatch;
+
+import org.apache.jena.sparql.core.DatasetGraph;
+import org.apache.jena.sparql.exec.UpdateExec;
+import org.apache.jena.sparql.util.Context;
+import org.apache.jena.update.UpdateRequest;
+
+/**
+ * An update dispatcher is responsible for taking an update request
+ * preparing it for the execution against a dataset.
+ * The result is a {@linkplain UpdateExec} instance.
+ *
+ * Update dispatchers form a chain, and a {@link ChainingUpdateDispatcher} acts as a link in such a chain.
+ * A ChainingUpdateDispatcher instance can choose to process an update request by itself or to delegate processing to the
+ * remainder of the chain.
+ *
+ * @see UpdateDispatcherRegistry
+ */
+public interface ChainingUpdateDispatcher {
+    UpdateExec create(UpdateRequest updateRequest, DatasetGraph dsg, Context context, UpdateDispatcher chain);
+}

jena-arq/src/main/java/org/apache/jena/sparql/engine/dispatch/QueryDispatcher.java

@@ -0,0 +1,31 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ *   SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.apache.jena.sparql.engine.dispatch;
+
+import org.apache.jena.query.Query;
+import org.apache.jena.sparql.core.DatasetGraph;
+import org.apache.jena.sparql.exec.QueryExec;
+import org.apache.jena.sparql.util.Context;
+
+public interface QueryDispatcher {
+    QueryExec create(Query query, DatasetGraph dsg, Context context);
+}

jena-arq/src/main/java/org/apache/jena/sparql/engine/dispatch/QueryDispatcherOverRegistry.java

@@ -0,0 +1,70 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ *   SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.apache.jena.sparql.engine.dispatch;
+
+import java.util.List;
+
+import org.apache.jena.query.Query;
+import org.apache.jena.query.QueryException;
+import org.apache.jena.sparql.core.DatasetGraph;
+import org.apache.jena.sparql.exec.QueryExec;
+import org.apache.jena.sparql.util.Context;
+
+/**
+ * {@link QueryDispatcher} that invokes all dispatchers registered with {@link QueryDispatcherRegistry} in a chain.
+ */
+public class QueryDispatcherOverRegistry
+    implements QueryDispatcher
+{
+    protected QueryDispatcherRegistry registry;
+
+    /** Position in the chain */
+    protected int pos;
+
+    public QueryDispatcherOverRegistry(QueryDispatcherRegistry registry) {
+        this(registry, 0);
+    }
+
+    public QueryDispatcherOverRegistry(QueryDispatcherRegistry registry, int pos) {
+        super();
+        this.registry = registry;
+        this.pos = pos;
+    }
+
+    protected ChainingQueryDispatcher getDispatcher() {
+        List<ChainingQueryDispatcher> queryDispatchers = registry.dispatchers();
+        int n = queryDispatchers.size();
+        if (pos >= n) {
+            throw new QueryException("No more elements in query dispatcher chain (pos=" + pos + ", chain size=" + n + ")");
+        }
+        ChainingQueryDispatcher dispatcher = queryDispatchers.get(pos);
+        return dispatcher;
+    }
+
+    @Override
+    public QueryExec create(Query query, DatasetGraph dsg, Context context) {
+        ChainingQueryDispatcher dispatcher = getDispatcher();
+        QueryDispatcher next = new QueryDispatcherOverRegistry(registry, pos + 1);
+        QueryExec result = dispatcher.create(query, dsg, context, next);
+        return result;
+    }
+}

jena-arq/src/main/java/org/apache/jena/sparql/engine/dispatch/QueryDispatcherRegistry.java

@@ -0,0 +1,131 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ *   SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.apache.jena.sparql.engine.dispatch;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+import org.apache.jena.query.Query;
+import org.apache.jena.sparql.ARQConstants;
+import org.apache.jena.sparql.core.DatasetGraph;
+import org.apache.jena.sparql.exec.ChainingQueryDispatcherMain;
+import org.apache.jena.sparql.exec.QueryExec;
+import org.apache.jena.sparql.exec.QueryExecBuilder;
+import org.apache.jena.sparql.util.Context;
+
+/**
+ * Registry of {@link ChainingQueryDispatcher} instances.
+ * Allows for plugging into the {@link QueryExecBuilder} creation process
+ * based on dataset and context.
+ *
+ * @see ChainingQueryDispatcher
+ * @since 6.1.0
+ */
+public class QueryDispatcherRegistry {
+    List<ChainingQueryDispatcher> dispatchers = Collections.synchronizedList(new ArrayList<>());
+
+    // Singleton
+    private static QueryDispatcherRegistry registry;
+    static { init(); }
+
+    static public QueryDispatcherRegistry get() {
+        return registry;
+    }
+
+    /** If there is a QueryDispatcherRegistry in the context then return it otherwise yield the global instance */
+    static public QueryDispatcherRegistry chooseRegistry(Context context) {
+        QueryDispatcherRegistry result = get(context);
+        if (result == null) {
+            result = get();
+        }
+        return result;
+    }
+
+    /** Get the QueryDispatcherRegistry from the context or null if there is none.
+     *  Returns null if the context is null. */
+    static public QueryDispatcherRegistry get(Context context) {
+        QueryDispatcherRegistry result = context == null
+                ? null
+                : context.get(ARQConstants.registryQueryDispachers);
+        return result;
+    }
+
+    static public void set(Context context, QueryDispatcherRegistry registry) {
+        context.set(ARQConstants.registryQueryDispachers, registry);
+    }
+
+    public QueryDispatcherRegistry copy() {
+        QueryDispatcherRegistry result = new QueryDispatcherRegistry();
+        result.dispatchers.addAll(dispatchers);
+        return result;
+    }
+
+    /** Create a copy of the registry from the context or return a new instance */
+    public static QueryDispatcherRegistry copyFrom(Context context) {
+        QueryDispatcherRegistry tmp = get(context);
+        QueryDispatcherRegistry result = tmp != null
+                ? tmp.copy()
+                : new QueryDispatcherRegistry();
+        return result;
+    }
+
+    public QueryDispatcherRegistry() { }
+
+    private static void init() {
+        registry = new QueryDispatcherRegistry();
+
+        registry.add(ChainingQueryDispatcherMain.get());
+    }
+
+    // ----- Query -----
+
+    /** Add a ChainingQueryDispatcher to the default registry. */
+    public static void addDispatcher(ChainingQueryDispatcher f) { get().add(f); }
+
+    /** Add a ChainingQueryDispatcher. */
+    public void add(ChainingQueryDispatcher f) {
+        // Add to low end so that newer factories are tried first
+        dispatchers.add(0, f);
+    }
+
+    /** Remove a ChainingQueryDispatcher from the default registry. */
+    public static void removeDispatcher(ChainingQueryDispatcher f)  { get().remove(f); }
+
+    /** Remove a ChainingQueryDispatcher. */
+    public void remove(ChainingQueryDispatcher f)  { dispatchers.remove(f); }
+
+    /** Allow <b>careful</b> manipulation of the dispatchers list */
+    public List<ChainingQueryDispatcher> dispatchers() { return dispatchers; }
+
+    /** Check whether a ChainingQueryDispatcher is registered in the default registry. */
+    public static boolean containsDispatcher(ChainingQueryDispatcher f) { return get().contains(f); }
+
+    /** Check whether a ChainingQueryDispatcher is already registered. */
+    public boolean contains(ChainingQueryDispatcher f) { return dispatchers.contains(f); }
+
+    public static QueryExec create(Query query, DatasetGraph dsg, Context context) {
+        QueryDispatcher dispatcher = new QueryDispatcherOverRegistry(registry);
+        QueryExec qe = dispatcher.create(query, dsg, context);
+        return qe;
+    }
+}

jena-arq/src/main/java/org/apache/jena/sparql/engine/dispatch/UpdateDispatcher.java

@@ -0,0 +1,31 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ *   SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.apache.jena.sparql.engine.dispatch;
+
+import org.apache.jena.sparql.core.DatasetGraph;
+import org.apache.jena.sparql.exec.UpdateExec;
+import org.apache.jena.sparql.util.Context;
+import org.apache.jena.update.UpdateRequest;
+
+public interface UpdateDispatcher {
+    UpdateExec create(UpdateRequest updateRequest, DatasetGraph dsg, Context context);
+}