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    
015    package org.apache.hivemind.impl;
016    
017    import java.util.List;
018    
019    import org.apache.hivemind.events.RegistryShutdownListener;
020    import org.apache.hivemind.internal.ServiceImplementationConstructor;
021    import 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     */
030    public 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    }