avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nic...@apache.org
Subject svn commit: rev 30982 - avalon/trunk/runtime/framework/api/src/java/org/apache/avalon/framework/availability
Date Fri, 30 Jul 2004 09:46:40 GMT
Author: niclas
Date: Fri Jul 30 02:46:40 2004
New Revision: 30982

Added:
   avalon/trunk/runtime/framework/api/src/java/org/apache/avalon/framework/availability/
   avalon/trunk/runtime/framework/api/src/java/org/apache/avalon/framework/availability/AvailabilityAware.java
  (contents, props changed)
   avalon/trunk/runtime/framework/api/src/java/org/apache/avalon/framework/availability/UnavailableException.java
  (contents, props changed)
Log:
Proposal for a new AvailabilityAware interface in Framework. The change is AFAICT 100% compatible
with existing components, existing containers, and even new AvailabilityAware components running
in old containers.

Added: avalon/trunk/runtime/framework/api/src/java/org/apache/avalon/framework/availability/AvailabilityAware.java
==============================================================================
--- (empty file)
+++ avalon/trunk/runtime/framework/api/src/java/org/apache/avalon/framework/availability/AvailabilityAware.java
Fri Jul 30 02:46:40 2004
@@ -0,0 +1,71 @@
+/*
+ * Copyright 1997-2004 The Apache Software Foundation
+ * 
+ * Licensed 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.avalon.framework.availability;
+
+
+/** An Availability contract between the container and the component.
+ *
+ * <p>A component that implements AvailabilityAware, is capable to be notified
+ * that components that it has previously looked up via the 
+ * ServiceManager.lookup() method are made available and non-available, 
+ * and can gracefully handle unavailability.</p>
+ *
+ * <p>Containers are only required to support this interface, if the
+ * container supports dynamic loading/unloading of components, hot-deploys,
+ * remote components and similar cases where components may disappear for
+ * a shorter or longer period of time.</p>
+ *
+ * @since 4.5
+ *
+ * @author <a href="mailto:dev@avalon.apache.org">Avalon Development Team</a>
+ * @version $Id$
+ */
+public interface AvailabilityAware
+{
+    /** Notification that component is available.
+     * <p>The component that previously has been looked up in the 
+     * ServiceManager, using <i>key</i> is now available. This method can 
+     * either be called after the componentUnavailable() method signalled that 
+     * a component is no longer available, OR if the ServiceManager.lookup() 
+     * returned a null (optional lookup) indicating that the requested 
+     * component didn't exist.</p>
+     * <p>
+     *   This method will NOT be called with a <i>key</i> argument that has
+     *   not been used in a ServiceManager.lookup() previously.
+     * </p>
+     *
+     * @param key The key that was used to lookup the component in the 
+     *            ServiceManager earlier.
+     */
+    void componentAvailable( String key );
+    
+    /** Notification that component is no longer available.
+     * <p>The component that previously has been looked up in the 
+     * ServiceManager, using <i>key</i> is no longer available. The container

+     * does not place any restrictions on how long the component will be 
+     * unavailble, and the AvailabilityAware component, must employ one or more
+     * strategies on how to gracefully handle short and long absences of 
+     * dependent components. </p>
+     * <p>
+     *   This method will NOT be called with a <i>key</i> argument that has
+     *   not been used in a ServiceManager.lookup() previously.
+     * </p>
+     *
+     * @param key The key that was used to lookup the component in the 
+     *            ServiceManager earlier.
+     */
+    void componentUnavailble( String key );
+}

Added: avalon/trunk/runtime/framework/api/src/java/org/apache/avalon/framework/availability/UnavailableException.java
==============================================================================
--- (empty file)
+++ avalon/trunk/runtime/framework/api/src/java/org/apache/avalon/framework/availability/UnavailableException.java
Fri Jul 30 02:46:40 2004
@@ -0,0 +1,52 @@
+/*
+ * Copyright 1997-2004 The Apache Software Foundation
+ * 
+ * Licensed 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.avalon.framework.availability;
+ 
+/** Exception to signal component is not available.
+ * 
+ * UnavailableException is thrown in any method to another component,
+ * but only if the caller implements AvailabilityAware.
+ *
+ * @since 4.5
+ *
+ * @author <a href="mailto:dev@avalon.apache.org">Avalon Development Team</a>
+ * @version $Id$
+ */
+public class UnavailableException extends RuntimeException
+{
+    private String m_Key;
+    
+    /** Constructor.
+     * @param message The non-localized message to be embedded into the
+     *        exception.
+     *
+     * @param key The key that the caller used to lookup the component
+     *            with.
+     */
+    public UnavailableException( String message, String key )
+    {
+        super( message );
+        m_Key = key;
+    }
+   
+    /** Returns the key to the component that is no longer available.
+     *
+     */ 
+    public String getLookupKey()
+    {
+        return m_Key;
+    }
+}
\ No newline at end of file

---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@avalon.apache.org
For additional commands, e-mail: cvs-help@avalon.apache.org


Mime
View raw message