sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1826192 - in /sis/branches/JDK8: core/sis-utility/src/main/java/org/apache/sis/util/logging/ storage/sis-storage/src/main/java/org/apache/sis/storage/ storage/sis-storage/src/main/java/org/apache/sis/storage/event/
Date Thu, 08 Mar 2018 09:28:59 GMT
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



Mime
View raw message