Author: desruisseaux Date: Thu Mar 8 09:28:59 2018 New Revision: 1826192 URL: http://svn.apache.org/viewvc?rev=1826192&view=rev Log: Move the listener and event class to an 'event' sub-package and develop Javadoc.
Added: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/ChangeEvent.java (contents, props changed) - copied, changed from r1826191, sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/ChangeEvent.java sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/ChangeListener.java (contents, props changed) - copied, changed from r1826191, sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/ChangeListener.java sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/package-info.java (with props) Removed: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/ChangeEvent.java sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/ChangeListener.java Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/logging/WarningListener.java sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/logging/WarningListener.java URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/logging/WarningListener.java?rev=1826192&r1=1826191&r2=1826192&view=diff ============================================================================== --- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/logging/WarningListener.java [UTF-8] (original) +++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/logging/WarningListener.java [UTF-8] Thu Mar 8 09:28:59 2018 @@ -42,6 +42,7 @@ import java.util.logging.LogRecord; * * @see WarningListeners * @see org.apache.sis.storage.DataStore#addWarningListener(WarningListener) + * @see org.apache.sis.storage.event.ChangeListener * * @since 0.3 * @module Modified: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java?rev=1826192&r1=1826191&r2=1826192&view=diff ============================================================================== --- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java [UTF-8] (original) +++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/Resource.java [UTF-8] Thu Mar 8 09:28:59 2018 @@ -105,43 +105,44 @@ public interface Resource { Metadata getMetadata() throws DataStoreException; /** - * Attaches a ChangeListener on the resource. - * The resource will call the {@link ChangeListener#changeOccured(org.apache.sis.storage.ChangeEvent) } - * method when a new event matching the predicate is produced. - * - * <p> - * The sample listener may be added multiple times with different predicates. - * Adding multiple times the same listener with the same predicate has no effect, - * The listener will only be called once per event. - * </p> - * - * <p> - * The resource is not required to keep a reference to the listener. - * For example the resource might discard a listener if the given predicate - * will never happen on this resource. - * </p> - * - * @param <T> type of {@linkplain ChangeEvent} - * @param listener listener to notify - * @param predicate class of {@linkplain ChangeEvent} to listen to, or null for all. + * Registers a listener that is notified each time a change occurs in the resource content or structure. + * The resource will call the {@link ChangeListener#changeOccured(ChangeEvent)} + * method when a new event matching the {@code eventType} is produced. + * + * <p>Registering a listener for a given {@code eventType} also register the listener for all sub-types. + * The same listener can be added multiple times for different even type. + * Adding many times the same listener with the same even type has no effect: + * the listener will only be called once per event.</p> + * + * @todo When adding a listener to an aggregate, should the listener be added to all components? + * In other words, should listeners in a tree node also listen to events from all children? + * + * <p>The resource is not required to keep a reference to the listener. + * For example the resource may discard a listener if no event of the given type happen on this resource.</p> + * + * @param <T> compile-time value of the {@code eventType} argument. + * @param listener listener to notify about changes. + * @param eventType type of {@linkplain ChangeEvent} to listen (can not be {@code null}). */ - //TODO : remove comment when implementated on all resources. - //<T extends ChangeEvent> void addListener(ChangeListener<? super T> listener, Class<T> predicate); + //TODO: remove comment when implemented on all resources. + //<T extends ChangeEvent> void addListener(ChangeListener<? super T> listener, Class<T> eventType); /** - * Removes an attached ChangeListener from the resource. + * Unregisters a listener previously added to this resource for the given type of events. + * The {@code eventType} must be the exact same class than the one given to the {@code addListener(…)} method. * - * <p> - * Calling multiple times this method with the same listener or a listener - * which is unknown to this resource will have no effect and won't raise an - * exception. - * </p> - * - * @param <T> type of {@linkplain ChangeEvent} - * @param listener listener to remove - * @param predicate class of {@linkplain ChangeEvent} to listen to, or null for all. + * <div class="note"><b>Example:</b> + * if the same listener has been added for {@code ChangeEvent} and {@code StructuralChangeEvent}, that listener + * will be notified only once for all {@code ChangeEvent}s. If that listener is removed for {@code ChangeEvent}, + * then the listener will still receive {@code StructuralChangeEvent}s.</div> + * + * <p>Calling multiple times this method with the same listener and event type or a listener + * which is unknown to this resource will have no effect and will not raise an exception.</p> + * + * @param <T> compile-time value of the {@code eventType} argument. + * @param listener listener to stop notifying about changes. + * @param eventType type of {@linkplain ChangeEvent} which were listened (can not be {@code null}). */ - //TODO : remove comment when implementated on all resources. - //<T extends ChangeEvent> void removeListener(ChangeListener<? super T> listener, Class<T> predicate); - + //TODO: remove comment when implemented on all resources. + //<T extends ChangeEvent> void removeListener(ChangeListener<? super T> listener, Class<T> eventType); } Copied: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/ChangeEvent.java (from r1826191, sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/ChangeEvent.java) URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/ChangeEvent.java?p2=sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/ChangeEvent.java&p1=sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/ChangeEvent.java&r1=1826191&r2=1826192&rev=1826192&view=diff ============================================================================== --- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/ChangeEvent.java [iso-8859-1] (original) +++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/ChangeEvent.java [UTF-8] Thu Mar 8 09:28:59 2018 @@ -14,26 +14,47 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package org.apache.sis.storage; +package org.apache.sis.storage.event; import java.util.EventObject; +import org.apache.sis.storage.Resource; + /** - * Parent class of all Resource events. + * Parent class of all events related to a change in the metadata, content or structure of a resource. + * Those events are created by {@link Resource} implementations and sent to all registered listeners. + * + * @author Johann Sorel (Geomatys) + * @version 1.0 + * + * @see ChangeListener * - * @author Johann Sorel (Geomatys) * @since 1.0 * @module */ public abstract class ChangeEvent extends EventObject { + /** + * For cross-version compatibility. + */ + private static final long serialVersionUID = -1725093072445990248L; /** - * Construct event. + * Constructs an event that occurred in the given resource. * - * @param source The object on which the Event initially occurred. + * @param source the resource on which the event initially occurred. + * @throws IllegalArgumentException if the given source is null. */ - public ChangeEvent(Object source) { + public ChangeEvent(Resource source) { super(source); } + /** + * Returns the resource on which the event initially occurred. + * + * @return the resource on which the Event initially occurred. + */ + @Override + public Resource getSource() { + return (Resource) source; + } } Propchange: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/ChangeEvent.java ------------------------------------------------------------------------------ svn:eol-style = native Propchange: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/ChangeEvent.java ------------------------------------------------------------------------------ svn:mime-type = text/plain;charset=UTF-8 Copied: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/ChangeListener.java (from r1826191, sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/ChangeListener.java) URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/ChangeListener.java?p2=sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/ChangeListener.java&p1=sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/ChangeListener.java&r1=1826191&r2=1826192&rev=1826192&view=diff ============================================================================== --- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/ChangeListener.java [iso-8859-1] (original) +++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/ChangeListener.java [UTF-8] Thu Mar 8 09:28:59 2018 @@ -14,23 +14,41 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -package org.apache.sis.storage; +package org.apache.sis.storage.event; + +import org.apache.sis.storage.Resource; + /** - * Intercept event from a Resource. + * Defines an object which listens for changes in resources. + * The changes in resources are described by {@link ChangeEvent} instances. + * {@link Resource} implementations are responsible for instantiating the most specific {@code ChangeEvent} subclass + * for the type of event, for example: + * + * <ul> + * <li>When the data store content changed (e.g. new feature instance added or removed).</li> + * <li>When the data store structure changed (e.g. a column is added in tabular data).</li> + * <li>Any other change at implementation choice.</li> + * </ul> + * + * Then, all {@code ChangeListener}s that declared an interest in {@code ChangeEvent}s of that kind are notified. + * + * @author Johann Sorel (Geomatys) + * @version 1.0 + * + * @param <T> the type of events of interest to this listener. + * + * @see ChangeEvent + * @see org.apache.sis.util.logging.WarningListener * - * @author Johann Sorel (Geomatys) - * @param <T> * @since 1.0 * @module */ public interface ChangeListener<T extends ChangeEvent> { - /** - * Method called when an ChangeEvent is produce by a Resource. + * Invoked <em>after</em> a change occurred in a resource. * - * @param event resource event, never null + * @param event resource event, never null. */ void changeOccured(T event); - } Propchange: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/ChangeListener.java ------------------------------------------------------------------------------ svn:eol-style = native Propchange: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/ChangeListener.java ------------------------------------------------------------------------------ svn:mime-type = text/plain;charset=UTF-8 Added: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/package-info.java URL: http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/package-info.java?rev=1826192&view=auto ============================================================================== --- sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/package-info.java (added) +++ sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/package-info.java [UTF-8] Thu Mar 8 09:28:59 2018 @@ -0,0 +1,33 @@ +/* + * 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. + */ + + +/** + * Provides interfaces and classes for dealing with different types of events fired by resources. + * The different types of events are differentiated by the {@link ChangeEvent} subclasses. + * There is different subclasses for structural changes or changes in resource content. + * It is possible to register a listener for only some specific types of events. + * + * <p>Note that warnings that may occur during exploitation of a resource are handled by an interface + * defined in another package, {@link org.apache.sis.util.logging.WarningListener}.</p> + * + * @author Johann Sorel (Geomatys) + * @since 1.0 + * @version 1.0 + * @module + */ +package org.apache.sis.storage.event; Propchange: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/package-info.java ------------------------------------------------------------------------------ svn:eol-style = native Propchange: sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/event/package-info.java ------------------------------------------------------------------------------ svn:mime-type = text/plain;charset=UTF-8