Return-Path: X-Original-To: apmail-jackrabbit-commits-archive@www.apache.org Delivered-To: apmail-jackrabbit-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 1080710195 for ; Thu, 13 Mar 2014 15:53:18 +0000 (UTC) Received: (qmail 99543 invoked by uid 500); 13 Mar 2014 15:51:19 -0000 Delivered-To: apmail-jackrabbit-commits-archive@jackrabbit.apache.org Received: (qmail 97956 invoked by uid 500); 13 Mar 2014 15:51:17 -0000 Mailing-List: contact commits-help@jackrabbit.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@jackrabbit.apache.org Delivered-To: mailing list commits@jackrabbit.apache.org Received: (qmail 97840 invoked by uid 99); 13 Mar 2014 15:51:15 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 13 Mar 2014 15:51:15 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 13 Mar 2014 15:51:13 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id F05A6238883D; Thu, 13 Mar 2014 15:50:52 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1577213 - in /jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/observation: JackrabbitEventFilter.java JackrabbitObservationManager.java Date: Thu, 13 Mar 2014 15:50:52 -0000 To: commits@jackrabbit.apache.org From: mduerig@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20140313155052.F05A6238883D@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: mduerig Date: Thu Mar 13 15:50:52 2014 New Revision: 1577213 URL: http://svn.apache.org/r1577213 Log: JCR-3745: Add JackrabbitObservationManager with additional methods for registering event listeners Initial version of new API Added: jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/observation/JackrabbitEventFilter.java jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/observation/JackrabbitObservationManager.java Added: jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/observation/JackrabbitEventFilter.java URL: http://svn.apache.org/viewvc/jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/observation/JackrabbitEventFilter.java?rev=1577213&view=auto ============================================================================== --- jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/observation/JackrabbitEventFilter.java (added) +++ jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/observation/JackrabbitEventFilter.java Thu Mar 13 15:50:52 2014 @@ -0,0 +1,257 @@ +/* + * 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.jackrabbit.api.observation; + +import static java.util.Arrays.copyOf; + +/** + * A storage object for event filter configuration. + *

+ * The parameters of the filter can then be set by chaining the set methods, + * since each method returns the same EventFilter with the indicated parameter set. + *

+ * Once the filter is configured, it and an {@link javax.jcr.observation.EventListener} object are + * passed to + * {@link org.apache.jackrabbit.api.observation.JackrabbitObservationManager#addEventListener(javax.jcr.observation.EventListener, JackrabbitEventFilter)}. + *

+ * The filter restricts which events are sent to the EventListener according to the + * following parameters. Note that the term associated parent node of an event means the + * parent node of the item at (or formerly at) the path returned by + * {@link javax.jcr.observation.Event#getPath}. + *

    + *
  • + * eventTypes: + * A bitwise OR of the event types to be listened to. See + * {@link javax.jcr.observation.Event} for details. + *
    • + *
  • + * absPath, absPaths isDeep: + * Only events whose associated parent node is at one of the paths in + * absPath or absPaths (or within its subgraph, + * if isDeep is true) will be received. It is + * permissible to register a listener for a path where no node currently exists. + *
    • + *
  • + * uuid: + * Only events whose associated parent node has one of + * the identifiers in this list will be received. If his parameter is + * null then no identifier-related restriction is placed on + * events received. Note that specifying an empty array instead of + * null would result in no nodes being listened to. The term + * "UUID" is used for compatibility with JCR 1.0. + *
    • + *
  • + * nodeTypeName: + * Only events whose associated parent node has + * one of the node types (or a subtype of one of the node types) in this + * list will be received. If his parameter is null then no node + * type-related restriction is placed on events received. Note that + * specifying an empty array instead of null would result in no + * nodes types being listened to. + *
    • + *
  • + * noLocal: if true, then events + * generated by the session through which the listener was registered are + * ignored. Otherwise, they are not ignored. + *
    • + *
  • + * noExternal: if true, then events + * from external cluster nodes are ignored. Otherwise, they are not ignored. + *
    • + *
+ * The restrictions are "ANDed" together. In other words, for a particular node to be "listened to" it + * must meet all the restrictions. + * + */ +public class JackrabbitEventFilter { // TODO extends EventFilter once JCR 2.1 is out + private int eventTypes; + private String absPath; + private boolean isDeep; + private String[] identifiers; + private String[] nodeTypeNames; + private boolean noLocal; + private String[] absPaths = new String[]{}; + private boolean noExternal; + + /** + * Sets the eventTypes parameter of the filter. + * If left unset, this parameter defaults to 0. + * + * @param eventTypes an int. + * @return This EventFilter object with the eventTypes parameter set. + */ + public JackrabbitEventFilter setEventTypes(int eventTypes) { + this.eventTypes = eventTypes; + return this; + } + + /** + * Returns the eventTypes parameter of the filter. + * + * @return an int. + */ + public int getEventTypes() { + return eventTypes; + } + + /** + * Sets the absPath parameter of the filter. + * If left unset, this parameter defaults to null. + * + * @param absPath an absolute path String. + * @return This EventFilter object with the absPath parameter set. + */ + public JackrabbitEventFilter setAbsPath(String absPath) { + this.absPath = absPath; + return this; + } + + /** + * Returns the absPath parameter of the filter. + * + * @return a String. + */ + public String getAbsPath() { + return absPath; + } + + /** + * Sets the isDeep parameter of the filter. + * If left unset, this parameter defaults to false. + * + * @param isDeep a boolean. + * @return This EventFilter object with the isDeep parameter set. + */ + public JackrabbitEventFilter setIsDeep(boolean isDeep) { + this.isDeep = isDeep; + return this; + } + + /** + * Returns the isDeep parameter of the filter. + * + * @return a boolean. + */ + public boolean getIsDeep() { + return isDeep; + } + + /** + * Sets the identifiers parameter of the filter. + * If left unset, this parameter defaults to null. + * + * @param identifiers a String array. + * @return This EventFilter object with the identifiers parameter set. + */ + public JackrabbitEventFilter setIdentifiers(String[] identifiers) { + this.identifiers = copyOf(identifiers, identifiers.length); + return null; + } + + /** + * Returns the uuids parameter of the filter. + * + * @return a String array. + */ + public String[] getIdentifiers() { + return identifiers == null ? null : copyOf(identifiers, identifiers.length); + } + + /** + * Sets the nodeTypeNames parameter of the filter. + * If left unset, this parameter defaults to null. + * + * @param nodeTypeNames a String array. + * @return This EventFilter object with the nodeTypes parameter set. + */ + public JackrabbitEventFilter setNodeTypes(String[] nodeTypeNames) { + this.nodeTypeNames = copyOf(nodeTypeNames, nodeTypeNames.length); + return this; + } + + /** + * Returns the nodeTypeName parameter of the filter. + * + * @return a String array. + */ + public String[] getNodeTypes() { + return nodeTypeNames == null ? null : copyOf(nodeTypeNames, nodeTypeNames.length); + } + + /** + * Sets the noLocal parameter of the filter. + * If left unset, this parameter defaults to false. + * + * @param noLocal a boolean. + * @return This EventFilter object with the noLocal parameter set. + */ + public JackrabbitEventFilter setNoLocal(boolean noLocal) { + this.noLocal = noLocal; + return this; + } + + /** + * Returns the noLocal parameter of the filter. + * + * @return a boolean. + */ + public boolean getNoLocal() { + return noLocal; + } + + /** + * Sets the absPaths parameter of the filter. + * If left unset, this parameter defaults to an empty array. + * + * @param absPaths an absolute path String array. + * @return This EventFilter object with the absPaths parameter set. + */ + public JackrabbitEventFilter setAdditionalPaths(String... absPaths) { + this.absPaths = copyOf(absPaths, absPaths.length); + return this; + } + + /** + * Returns the absPaths parameter of the filter. + * + * @return a String array. + */ + public String[] getAdditionalPaths() { + return copyOf(absPaths, absPaths.length); + } + + /** + * Sets the noExternal parameter of the filter. + * If left unset, this parameter defaults to false. + * + * @param noExternal a boolean. + * @return This EventFilter object with the noExternal parameter set. + */ + public JackrabbitEventFilter setNoExternal(boolean noExternal) { + this.noExternal = noExternal; + return this; + } + + /** + * Returns the noExternal parameter of the filter. + * + * @return a boolean. + */ + public boolean getNoExternal() { + return noExternal; + } +} \ No newline at end of file Added: jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/observation/JackrabbitObservationManager.java URL: http://svn.apache.org/viewvc/jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/observation/JackrabbitObservationManager.java?rev=1577213&view=auto ============================================================================== --- jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/observation/JackrabbitObservationManager.java (added) +++ jackrabbit/trunk/jackrabbit-api/src/main/java/org/apache/jackrabbit/api/observation/JackrabbitObservationManager.java Thu Mar 13 15:50:52 2014 @@ -0,0 +1,54 @@ +/* + * 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.jackrabbit.api.observation; + +import javax.jcr.RepositoryException; +import javax.jcr.observation.EventListener; + +/** + * Jackrabbit specific extensions to {@link javax.jcr.observation.ObservationManager}. + */ +public interface JackrabbitObservationManager { + + /** + * Adds an event listener that listens for the events specified + * by the passed {@link JackrabbitEventFilter}. + *

+ * In addition to the EventFilter, the set of events reported + * will be further filtered by the access rights of the + * current Session. + *

+ * See {@link JackrabbitEventFilter} for a description of the filtering parameters available. + *

+ * The filter of an already-registered EventListener can be + * changed at runtime by re-registering the same EventListener + * object (i.e. the same actual Java object) with a new filter. + * The implementation must ensure that no events are lost during the changeover. + *

+ * In addition to the filters placed on a listener above, the scope of + * observation support, in terms of which parts of a workspace are observable, may also + * be subject to implementation-specific restrictions. For example, in some + * repositories observation of changes in the jcr:system + * subgraph may not be supported. + * + * @param listener an {@link EventListener} object. + * @param filter an {@link JackrabbitEventFilter} object. + * @throws RepositoryException If an error occurs. + */ + void addEventListener(EventListener listener, JackrabbitEventFilter filter) + throws RepositoryException; +}