GH-1374: add copyWithRegisties Context helper method

[sszuev]

Feature request: a convenient way to execute a query against graph in a dedicated context.

If we want to execute a query in isolated context with unique set of independent functions and p-functions,
we will encounter some difficulties:

• the method org.apache.jena.sparql.util.Context#copy performs only shallow copying, not deep
• there is no straightforward way to pass the context while constructing org.apache.jena.query.QueryExecution

So we have to spend some time to find the proper way.
I think this can be simplified by adding two new helper-methods:

• Context#copyWithFunctionRegistries(Context) - the method to create a copy of Context with copied function and p-function registries
• QueryExecutionFactory#create(Query, Graph, Context) - the method to create QueryExceution for a Graph with the given context

---

• Tests are included.
• Documentation change and updates are provided for the Apache Jena website
• Commits have been squashed to remove intermediate development commit messages.
• Key commit messages start with the issue number (GH-xxxx or JENA-xxxx)

By submitting this pull request, I acknowledge that I am making a contribution to the Apache Software Foundation under the terms and conditions of the Contributor's Agreement.

---

See the Apache Jena "Contributing" guide.

[Aklakan]

I suppose the ARQ method to copy the function registries should eventually also copy the service executor registries (one is already available and another for bulk requests is in the works) - they are typically very small and I don't think it makes sense to exclude those when one explicitly asks for a deep copy of the context in order to add isolated extensions.

Maybe instead of naming the method copyWithFunctionRegistries it should be
more generally copyWithRegistries? (Alternatively something like copyWith{User,Plugin,Extension,...}Registries).
So the naming should be clarified with the service executor registry in mind. Are there any further plugin registries in the context by default that would benefit from deep copying too?

For consistency, the ServiceExecutorRegistry registry should provide a createFrom method too but that I can add with a separate PR.

[Aklakan]

Redundant return can be removed if written that way:

        if (from != null) {
            res.registry.putAll(from.registry);
        }
        return res;

[sszuev]

ServiceExecutorRegistry

I suppose the ARQ method to copy the function registries should eventually also copy the service executor registries (one is already available and another for bulk requests is in the works) - they are typically very small and I don't think it makes sense to exclude those when one explicitly asks for a deep copy of the context in order to add isolated extensions.

Maybe instead of naming the method copyWithFunctionRegistries it should be more generally copyWithRegistries? (Alternatively something like copyWith{User,Plugin,Extension,...}Registries). So the naming should be clarified with the service executor registry in mind. Are there any further plugin registries in the context by default that would benefit from deep copying too?

For consistency, the ServiceExecutorRegistry registry should provide a createFrom method too but that I can add with a separate PR.

I think this is a good idea.

[afs]

I suppose the ARQ method to copy the function registries should eventually also copy the service executor registries

Discussion on #1374.

Context should be intent neutral and not know the value of any symbols.

[sszuev]

Context should be intent neutral and not know the value of any symbols.

What is appropriate place to such functionality ?
org.apache.jena.sparql.util.Contexts ?
org.apache.jena.sparql.util.ContextUtils ?

This is static helper, instance of Context itself does not refer to any particular symbol.
There are already static helpers like fromDataset(DatasetGraph).
I don't quite understand why import org.apache.jena.sparql.core.DatasetGraph is ok, but import org.apache.jena.sparql.function.FunctionRegistry is not?
If we move it to some other place it would be harder to find it.

Maybe, in the case of ContextUtils, all other static-helpers should also be moved to that new class (with duplication and @Deprecate for original methods). Such a way makes more sense for me, then the helper-class for a single helper-method.

[afs]

ContextUtils makes sense even if in sparql.util

Context is also used in RIOT - it was originally query-specific and mostly internal use but having such a mechanism, it get reused and escaped.

[sszuev]

ContextUtils makes sense even if in sparql.util

Context is also used in RIOT - it was originally query-specific and mostly internal use but having such a mechanism, it get reused and escaped.

Is there something else I can do in additional in the bounds of this PR ? Maybe marking deprecated all other static-helpers of Context with replacing and moving?

[afs]

Is there something else I can do in additional in the bounds of this PR ?

Thanks for asking.

My first step is to look at #1381 to understand that - and it does currently look like there is a bug managing contexts in QueryExec. A fix may well have knock on-effects.

At the moment, there are several active and time-consuming PRs in flight in unrelated areas.

[afs]

Only thing is {@code null) => {@code null} each time in javadoc but I'll fix that.