You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by cz...@apache.org on 2015/05/15 08:52:09 UTC
svn commit: r1679504 - in
/sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource:
observation/ provider/ query/
Author: cziegeler
Date: Fri May 15 06:52:09 2015
New Revision: 1679504
URL: http://svn.apache.org/r1679504
Log:
Update api and add more comments
Added:
sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryInstructions.java (with props)
Modified:
sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/observation/ResourceChange.java
sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/observation/ResourceListener.java
sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/observation/UserAwareResourceListener.java
sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ObservationReporter.java
sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/QueryProvider.java
sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ResourceProvider.java
sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/PropertyBuilder.java
sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/Query.java
sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryBuilder.java
sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryManager.java
Modified: sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/observation/ResourceChange.java
URL: http://svn.apache.org/viewvc/sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/observation/ResourceChange.java?rev=1679504&r1=1679503&r2=1679504&view=diff
==============================================================================
--- sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/observation/ResourceChange.java (original)
+++ sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/observation/ResourceChange.java Fri May 15 06:52:09 2015
@@ -18,30 +18,54 @@
*/
package org.apache.sling.api.resource.observation;
+import javax.annotation.CheckForNull;
+import javax.annotation.Nonnull;
+
+import aQute.bnd.annotation.ConsumerType;
+
/**
- * TODO properties, added/changed/removed, see SlingConstants
- *
- * TODO How do we handle resource provider changes? Currently we have two OSGi events: add/remove with the path
+ * A resource change event might be implemented in a lazy manner, however
+ * it is immutable.
*/
-public interface ResourceChange {
+@ConsumerType
+public abstract class ResourceChange {
public enum ChangeType {
ADDED,
REMOVED,
- CHANGED
+ CHANGED,
+ PROVIDER_ADDED,
+ PROVIDER_REMOVED
+ }
+
+ private final String path;
+ private final ChangeType changeType;
+
+ /**
+ * Create a new change object
+ * @param changeType The change type
+ * @param path The resource path
+ */
+ public ResourceChange(final @Nonnull ChangeType changeType, final @Nonnull String path) {
+ this.path = path;
+ this.changeType = changeType;
}
/**
* Get the resource path.
* @return The path to the resource.
*/
- String getPath();
+ public @Nonnull String getPath() {
+ return this.path;
+ }
/**
* Get the user id of the user initiating the change
* @return The user id or {@code null} if it's not available.
*/
- String getUserId();
+ public @CheckForNull String getUserId() {
+ return null;
+ }
/**
* Get the resource type.
@@ -49,36 +73,39 @@ public interface ResourceChange {
* it might not be available even for added/changed resources.
* @return The resource type or {@code null}
*/
- String getResourceType();
-
- /**
- * Get the super resource type.
- * @return The super resource type or {@code null}
- * TODO Do we really need this?
- */
- String getResourceSuperType();
+ public @CheckForNull String getResourceType() {
+ return null;
+ }
- /**
+ /**
* Get the type of change
* @return The type of change
*/
- ChangeType getType();
+ public @Nonnull ChangeType getType() {
+ return this.changeType;
+ }
/**
* Optional information about changed properties.
* TODO Clarify when these might be available.
*/
- String[] getChangedAttributeNames();
+ public @CheckForNull String[] getChangedAttributeNames() {
+ return null;
+ }
/**
* Optional information about added properties.
* TODO Clarify when these might be available.
*/
- String[] getAddedAttributeNames();
+ public @CheckForNull String[] getAddedAttributeNames() {
+ return null;
+ }
/**
* Optional information about removed properties.
* TODO Clarify when these might be available.
*/
- String[] getRemovedAttributeNames();
+ public @CheckForNull String[] getRemovedAttributeNames() {
+ return null;
+ }
}
Modified: sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/observation/ResourceListener.java
URL: http://svn.apache.org/viewvc/sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/observation/ResourceListener.java?rev=1679504&r1=1679503&r2=1679504&view=diff
==============================================================================
--- sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/observation/ResourceListener.java (original)
+++ sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/observation/ResourceListener.java Fri May 15 06:52:09 2015
@@ -43,16 +43,20 @@ import aQute.bnd.annotation.ConsumerType
@ConsumerType
public interface ResourceListener {
- /** Array of paths - required. */
+ /**
+ * Array of paths - required.
+ */
String PATHS = "resource.paths";
- /** Array of types, optional.
- * TODO - does this make sense, as remove events usually do not have the info?
- * */
- String TYPES = "resource.types";
-
- /** LDAP style filter matching against properties. - TODO do we need this? */
- String FILTER = "resource.filter";
+ /**
+ * Array of change types - optional.
+ * If this property is missing, added, removed and changed events are reported.
+ */
+ String CHANGES = "resources.changes";
+ /**
+ * Report a resource change based on the filter properties of this listener.
+ * @param changes The changes.
+ */
void onChange(@Nonnull List<ResourceChange> changes);
}
Modified: sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/observation/UserAwareResourceListener.java
URL: http://svn.apache.org/viewvc/sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/observation/UserAwareResourceListener.java?rev=1679504&r1=1679503&r2=1679504&view=diff
==============================================================================
--- sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/observation/UserAwareResourceListener.java (original)
+++ sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/observation/UserAwareResourceListener.java Fri May 15 06:52:09 2015
@@ -27,12 +27,40 @@ import org.apache.sling.api.resource.Res
import aQute.bnd.annotation.ConsumerType;
/**
- * TODO Do we need to bind this to a user?
+ * A resource listener which allows to act on the changes in the context of the user
+ * who initiated the changes. If that information is not known, a resolver using the
+ * access rights of a configured service user is used.
*/
@ConsumerType
public interface UserAwareResourceListener {
- /** TODO - define service registration properties for filtering. we can copy those from ResourceListener */
+ /**
+ * Array of paths - required.
+ */
+ String PATHS = "resource.paths";
- void onChange(@Nonnull ResourceResolver resolver, @Nonnull List<ResourceChange> changes);
+ /**
+ * Array of change types - optional.
+ * If this property is missing, added, removed and changed events are reported.
+ */
+ String CHANGES = "resources.changes";
+
+ /**
+ * Required property containing the service user if the change
+ * event does not contain the actual user.
+ * The value of this property must be of type string.
+ */
+ String SERVICE_USER = "resource.serviceuser";
+
+ /**
+ * Report a resource change based on the filter properties of this listener.
+ * @param resolver A resolver using the access rights of the user who initiated
+ * the change or the configured service user
+ * @param changes The changes.
+ * @param usesInitiatingUser {@code true} if the resolver uses the user initiating
+ * the changes.
+ */
+ void onChange(@Nonnull ResourceResolver resolver,
+ @Nonnull List<ResourceChange> changes,
+ boolean usesInitiatingUser);
}
Modified: sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ObservationReporter.java
URL: http://svn.apache.org/viewvc/sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ObservationReporter.java?rev=1679504&r1=1679503&r2=1679504&view=diff
==============================================================================
--- sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ObservationReporter.java (original)
+++ sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ObservationReporter.java Fri May 15 06:52:09 2015
@@ -27,6 +27,8 @@ import org.apache.sling.api.resource.obs
import aQute.bnd.annotation.ProviderType;
/**
+ * A {@code ResourceProvider} must use an observation reporter
+ * to report changes to resources.
*/
@ProviderType
public interface ObservationReporter {
Modified: sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/QueryProvider.java
URL: http://svn.apache.org/viewvc/sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/QueryProvider.java?rev=1679504&r1=1679503&r2=1679504&view=diff
==============================================================================
--- sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/QueryProvider.java (original)
+++ sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/QueryProvider.java Fri May 15 06:52:09 2015
@@ -25,14 +25,21 @@ import javax.annotation.Nonnull;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.query.Query;
-import org.apache.sling.api.resource.query.QueryManager.QueryInstruction;
+import org.apache.sling.api.resource.query.QueryInstructions;
import aQute.bnd.annotation.ConsumerType;
@ConsumerType
public interface QueryProvider <T> {
+ /**
+ * Execute the query within the context of the provided resource resolver
+ * @param ctx The resource context-
+ * @param q The query
+ * @param qi The query instructions
+ * @return An iterator for the resources or {@code null}.
+ */
@CheckForNull Iterator<Resource> find(@Nonnull ResolveContext<T> ctx,
@Nonnull Query q,
- @CheckForNull QueryInstruction qi);
+ @Nonnull QueryInstructions qi);
}
Modified: sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ResourceProvider.java
URL: http://svn.apache.org/viewvc/sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ResourceProvider.java?rev=1679504&r1=1679503&r2=1679504&view=diff
==============================================================================
--- sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ResourceProvider.java (original)
+++ sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/provider/ResourceProvider.java Fri May 15 06:52:09 2015
@@ -368,6 +368,12 @@ public abstract class ResourceProvider<T
return false;
}
+ /**
+ * Get the optional query provider.
+ *
+ * @param ctx The {@link ResolveContext} to which the returned {@link QueryProvider} is attached.
+ * @return A query provider if this resource provider supports querying.
+ */
public @CheckForNull QueryProvider<T> getQueryProvider() {
return null;
}
Modified: sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/PropertyBuilder.java
URL: http://svn.apache.org/viewvc/sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/PropertyBuilder.java?rev=1679504&r1=1679503&r2=1679504&view=diff
==============================================================================
--- sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/PropertyBuilder.java (original)
+++ sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/PropertyBuilder.java Fri May 15 06:52:09 2015
@@ -20,6 +20,12 @@ package org.apache.sling.api.resource.qu
import javax.annotation.Nonnull;
+import aQute.bnd.annotation.ProviderType;
+
+/**
+ * Builder for creating a property part of a query
+ */
+@ProviderType
public interface PropertyBuilder {
@Nonnull QueryBuilder eq(Object value);
Modified: sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/Query.java
URL: http://svn.apache.org/viewvc/sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/Query.java?rev=1679504&r1=1679503&r2=1679504&view=diff
==============================================================================
--- sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/Query.java (original)
+++ sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/Query.java Fri May 15 06:52:09 2015
@@ -21,7 +21,9 @@ package org.apache.sling.api.resource.qu
import javax.annotation.CheckForNull;
import javax.annotation.Nonnull;
+import aQute.bnd.annotation.ProviderType;
+@ProviderType
public interface Query {
public enum PartOperatorType {
Modified: sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryBuilder.java
URL: http://svn.apache.org/viewvc/sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryBuilder.java?rev=1679504&r1=1679503&r2=1679504&view=diff
==============================================================================
--- sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryBuilder.java (original)
+++ sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryBuilder.java Fri May 15 06:52:09 2015
@@ -20,24 +20,109 @@ package org.apache.sling.api.resource.qu
import javax.annotation.Nonnull;
+import aQute.bnd.annotation.ProviderType;
+/**
+ * The query builder can be used to build a query
+ * for resources.
+ */
+@ProviderType
public interface QueryBuilder {
+ /**
+ * Build the query.
+ *
+ * @return The query.
+ *
+ * @throws IllegalArgumentException If the query is not valid and can't be created.
+ */
+ @Nonnull Query build();
+
+ /**
+ * At a path condition to the query.
+ * If several paths are added to the query, these are handled as an or.
+ * If no path is specified for a query, the search paths of the resource
+ * resolver are used.
+ *
+ * @param path An absolute resource path
+ * @return The query builder to construct the query
+ *
+ * @throws IllegalArgumentException If the argument is not valid.
+ */
@Nonnull QueryBuilder at(@Nonnull String... path);
+ /**
+ * Add a condition to check whether the resource is of a specific resource type.
+ * If more than one resource type is specified, the conditions are handled with
+ * an or operation.
+ *
+ * @param resourceType The resource type to check
+ * @return The query builder to construct the query.
+ *
+ * @throws IllegalArgumentException If the argument is not valid.
+ */
@Nonnull QueryBuilder isA(@Nonnull String resourceType);
+ /**
+ * Add a property condition for the resources.
+ * If more than one property condition is specified, the conditions are
+ * handled with an and operation.
+ *
+ * @param name The name of the property to check.
+ * @return A property builder to specify the operation on the property value.
+ *
+ * @throws IllegalArgumentException If the argument is not valid.
+ */
@Nonnull PropertyBuilder property(@Nonnull String name);
+ /**
+ * Create a new query based on combining two or more queries in an and fashion.
+ *
+ * @param q1 First query
+ * @param q2 Additional queries
+ * @return The new query
+ */
@Nonnull Query and(@Nonnull Query q1, @Nonnull Query... q2);
+ /**
+ * Create a new query based on combining two or more queries in an or fashion.
+ *
+ * @param q1 First query
+ * @param q2 Additional queries
+ * @return The new query
+ *
+ * @throws IllegalArgumentException If the argument is not valid.
+ */
@Nonnull Query or(@Nonnull Query q1, @Nonnull Query... q2);
+ /**
+ * Create a new query by negating a query.
+ * @param q The query to negate.
+ * @return A new query
+ *
+ * @throws IllegalArgumentException If the argument is not valid.
+ */
@Nonnull Query not(@Nonnull Query q);
- @Nonnull Query build();
-
- @Nonnull QueryBuilder sortAscendingBy(String propName);
-
- @Nonnull QueryBuilder sortDescendingBy(String propName);
+ /**
+ * Sort the result in ascending order by this property.
+ * If more than one sort criteria is specified, the result is sorted first by the
+ * first criteria, within that sorting the second criteria is applied and so on.
+ * @param propName The name of the property
+ * @return The query builder to construct the query.
+ *
+ * @throws IllegalArgumentException If the argument is not valid.
+ */
+ @Nonnull QueryBuilder sortAscendingBy(@Nonnull String propName);
+
+ /**
+ * Sort the result in descending order by this property.
+ * If more than one sort criteria is specified, the result is sorted first by the
+ * first criteria, within that sorting the second criteria is applied and so on.
+ * @param propName The name of the property
+ * @return The query builder to construct the query.
+ *
+ * @throws IllegalArgumentException If the argument is not valid.
+ */
+ @Nonnull QueryBuilder sortDescendingBy(@Nonnull String propName);
}
\ No newline at end of file
Added: sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryInstructions.java
URL: http://svn.apache.org/viewvc/sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryInstructions.java?rev=1679504&view=auto
==============================================================================
--- sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryInstructions.java (added)
+++ sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryInstructions.java Fri May 15 06:52:09 2015
@@ -0,0 +1,69 @@
+/*
+ * 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
+ *
+ * http://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.
+ */
+package org.apache.sling.api.resource.query;
+
+import aQute.bnd.annotation.ProviderType;
+
+/**
+ * Query instructions are used to further specify runtime specific
+ * instructions for a query.
+ */
+@ProviderType
+public class QueryInstructions {
+
+ private int limit = -1;
+
+ private int startAt = -1;
+
+ /**
+ * Specify the limit of the query. By default the query is unlimited.
+ * @param limit The new limit. If a negative value is used, there is no limit.
+ * @return The query instructions.
+ */
+ public QueryInstructions limit(final int limit) {
+ this.limit = limit;
+ return this;
+ }
+
+ /**
+ * Get the limit of the query. By default the query is unlimited.
+ * @return The limit. If a negative value is returned, there is no limit.
+ */
+ public int getLimit() {
+ return this.limit;
+ }
+
+ /**
+ * Specify the start index for the query.
+ * @param start The new start index. If the value is less than 1, it starts at 0.
+ * @return The query instructions.
+ */
+ public QueryInstructions startAt(final int start) {
+ this.startAt = start;
+ return this;
+ }
+
+ /**
+ * Get the start index for the query.
+ * @return The start index. If the value is less than 1, the index is 0.
+ */
+ public int getStartAt() {
+ return this.startAt;
+ }
+}
\ No newline at end of file
Propchange: sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryInstructions.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryInstructions.java
------------------------------------------------------------------------------
svn:keywords = author date id revision rev url
Propchange: sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryInstructions.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified: sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryManager.java
URL: http://svn.apache.org/viewvc/sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryManager.java?rev=1679504&r1=1679503&r2=1679504&view=diff
==============================================================================
--- sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryManager.java (original)
+++ sling/whiteboard/cziegeler/api-v3/src/main/java/org/apache/sling/api/resource/query/QueryManager.java Fri May 15 06:52:09 2015
@@ -20,6 +20,7 @@ package org.apache.sling.api.resource.qu
import java.util.Iterator;
+import javax.annotation.CheckForNull;
import javax.annotation.Nonnull;
import org.apache.sling.api.resource.Resource;
@@ -27,27 +28,23 @@ import org.apache.sling.api.resource.Res
import aQute.bnd.annotation.ProviderType;
+/**
+ * The query manager allows to run a query in the context
+ * of a resource resolver.
+ */
@ProviderType
public interface QueryManager extends QueryBuilder {
- /** TODO - we can move this to query builder class. */
- @Nonnull QueryBuilder create();
-
- /** TODO - move to a class. */
- @Nonnull QueryInstruction limit(int n);
-
- /** TODO - move to a class. */
- @Nonnull QueryInstruction range(int start, int end);
-
- @Nonnull Iterator<Resource> find(@Nonnull ResourceResolver resolver,
- @Nonnull Query q);
-
+ /**
+ * Execute the given query in the context of the resource resolver.
+ *
+ * @param resolver The resource resolver
+ * @param q The query
+ * @param qi The optional query instructions
+ * @return An iterator of resources - the result might be empty.
+ */
@Nonnull Iterator<Resource> find(@Nonnull ResourceResolver resolver,
@Nonnull Query q,
- @Nonnull QueryInstruction qi);
-
- /** TODO - move to a class. */
- public interface QueryInstruction {
+ @CheckForNull QueryInstructions qi);
- }
}