001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019
020package org.apache.felix.ipojo.dependency.interceptors;
021
022import org.apache.felix.ipojo.util.DependencyModel;
023import org.osgi.framework.ServiceReference;
024
025import java.util.List;
026
027/**
028 * A service to influence the sorting of services on a service dependency.
029 *
030 * Only one ranking interceptor can be plugged on a dependency, but an interceptor can handle several dependencies.
031 *
032 * This interceptors is called to compute the selected set of services from the matching set,
033 * i.e. the set of services that matching the filter (actually accepted by the tracking interceptors).
034 *
035 * @since 1.10.1
036 */
037public interface ServiceRankingInterceptor extends DependencyInterceptor {
038
039    /**
040     * Gets the sorted set of selected reference.
041     * @param dependency the dependency
042     * @param matching the set of service to sort
043     * @return the sorted set of selected reference. This set is a sub-set potentially empty of the given list of
044     * references.
045     */
046    public List<ServiceReference> getServiceReferences(DependencyModel dependency, List<ServiceReference> matching);
047
048    /**
049     * A new service arrives in the matching set. This method is called to retrieve the new sorted set of selected
050     * services.
051     * @param dependency the dependency
052     * @param matching the set of matching service
053     * @param reference the arriving reference
054     * @return the new sorted set of service
055     */
056    public List<ServiceReference> onServiceArrival(DependencyModel dependency, List<ServiceReference> matching,
057                                                   ServiceReference<?> reference);
058
059    /**
060     * A service leaves the matching set. This method is called to retrieve the new sorted set of selected
061     * services.
062     * @param dependency the dependency
063     * @param matching the set of matching service
064     * @param reference the leaving reference
065     * @return the new sorted set of service
066     */
067    public List<ServiceReference> onServiceDeparture(DependencyModel dependency, List<ServiceReference> matching,
068                                                     ServiceReference<?> reference);
069
070    /**
071     * A service from the matching set was modified. This method is called to retrieve the new sorted set of selected
072     * services.
073     * @param dependency the dependency
074     * @param matching the set of matching service
075     * @param reference the modified service
076     * @return the new sorted set of service
077     */
078    public List<ServiceReference> onServiceModified(DependencyModel dependency, List<ServiceReference> matching,
079                                              ServiceReference<?> reference);
080
081}