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
