001// Copyright 2004, 2005 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007//     http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.hivemind.impl;
016
017import java.util.List;
018
019import org.apache.hivemind.events.RegistryShutdownListener;
020import org.apache.hivemind.internal.ServiceImplementationConstructor;
021import org.apache.hivemind.internal.ServicePoint;
022
023/**
024 * "Private" interface used by a {@link org.apache.hivemind.internal.ServiceModel}s to access non-
025 * information about a {@link org.apache.hivemind.internal.ServicePoint}, such as its instance
026 * builder and interceptors.
027 * 
028 * @author Howard Lewis Ship
029 */
030public interface ConstructableServicePoint extends ServicePoint
031{
032    /**
033     * Returns the constructor that can create the core service implementation. Returns the service
034     * constructor, if defined, or the default service constructor. The default service constructor
035     * comes from the <service-point> itself; other modules can override this default using an
036     * <implementation> element.
037     */
038    ServiceImplementationConstructor getServiceConstructor();
039
040    /**
041     * Returns a list of {@link org.apache.hivemind.internal.ServiceInterceptorContribution}s,
042     * ordered according to their dependencies. May return null or an empty list.
043     * <p>
044     * Note that the order is tricky! To keep any error messages while ordering the interceptors
045     * understandable, they are ordered according into runtime execution order. Example: If we want
046     * a logging interceptor to operate before a security-check interceptor, we'll write the
047     * following in the descriptor:
048     * 
049     * <pre>
050     *               &lt;interceptor service-id=&quot;hivemind.LoggingInterceptor&quot; before=&quot;*&quot;/&gt;
051     *               &lt;interceptor service-id=&quot;somepackage.SecurityInterceptor&quot;/&gt;
052     * </pre>
053     * 
054     * The <code>before</code> value for the first interceptor contribution will be assigned to
055     * the contribution's
056     * {@link org.apache.hivemind.internal.ServiceInterceptorContribution#getFollowingInterceptorIds() followingInterceptorIds}
057     * property, because all other interceptors (including the security interceptor) should have
058     * their behavior follow the logging interceptor.
059     * <p>
060     * To get this behavior, the logging interceptor will delegate to the security interceptor, and
061     * the security interceptor will delegate to the core service implementation.
062     * <p>
063     * The trick is that interceptors are applied in reverse order: we start with core service
064     * implementation, wrap it with the security interceptor, then wrap that with the logging
065     * interceptor ... but that's an issue that applies when building the interceptor stack around
066     * the core service implementation.
067     */
068    List getOrderedInterceptorContributions();
069
070    /**
071     * Invoked by the ServiceModel when constuction information (the builder and interceptors) is no
072     * longer needed.
073     */
074    void clearConstructorInformation();
075
076    /**
077     * Adds a shutdown listener; HiveMind uses two coordinators; the first is the
078     * hivemind.ShutdownCoordinator service, which is the coordinator used for service
079     * implementations. The second coordinator is used by the HiveMind infrastructure directly; this
080     * method adds a listener to that coordinator. Why two? It's about order of operations during
081     * registry shutdown; the hivemind.ShutdownCoordinator service's listeners are all invoked
082     * first, the the internal coordinator, to shutdown proxies and the like. This allows services
083     * to communicate during shutdown.
084     * 
085     * @param listener
086     *            the listener to be added to the infrastructure's shutdown coordinator
087     * @since 1.1.1
088     */
089
090    void addRegistryShutdownListener(RegistryShutdownListener listener);
091}