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 */
019package org.apache.felix.ipojo;
020
021import java.util.Dictionary;
022
023import org.osgi.framework.BundleContext;
024import org.osgi.framework.InvalidSyntaxException;
025import org.osgi.framework.ServiceListener;
026import org.osgi.framework.ServiceReference;
027import org.osgi.framework.ServiceRegistration;
028
029/**
030 * A service context is the facade of a service registry. 
031 * It gives the access to a service broker. All service
032 * interactions should use a service context to garanty
033 * the service isolation.
034 * This class is a subset of {@link BundleContext} methods.
035 * (methods implying interactions with the service registry).
036 * So, refer to this class for further information.
037 * @see BundleContext
038 * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
039 */
040public interface ServiceContext extends BundleContext {
041
042    /**
043     * Adds a service listener.
044     * The listener is added to this service context.
045     * So only services from this context will be tracked.
046     * @param listener the service listener to add.
047     * @param filter the LDAP filter
048     * @throws InvalidSyntaxException if the LDAP filter is malformed
049     * @see org.osgi.framework.BundleContext#addServiceListener(org.osgi.framework.ServiceListener, java.lang.String)
050     */
051    void addServiceListener(ServiceListener listener, String filter) throws InvalidSyntaxException;
052
053    /**
054     * Adds a service listener.
055     * The listener is added to this service context.
056     * So only services from this context will be tracked.
057     * @param listener the service listener to add.
058     * @see org.osgi.framework.BundleContext#addServiceListener(org.osgi.framework.ServiceListener)
059     */
060    void addServiceListener(ServiceListener listener);
061
062    /**
063     * Gets the service references matching with the given query.
064     * The query is executed inside this service context.
065     * @param clazz the required interface
066     * @param filter a LDAP filter
067     * @return the array of available service references or <code>null</code>
068     * if no providers are available.
069     * @throws InvalidSyntaxException if the LDAP filter is malformed
070     * @see org.osgi.framework.BundleContext#getAllServiceReferences(java.lang.String, java.lang.String)
071     */
072    ServiceReference[] getAllServiceReferences(String clazz, String filter) throws InvalidSyntaxException;
073
074    /**
075     * Gets a service object.
076     * The given service reference must comes from this
077     * service context.
078     * @param reference the required service reference 
079     * @return the service object or null if the service reference is no more valid or if the service object is not accessible
080     * @see org.osgi.framework.BundleContext#getService(org.osgi.framework.ServiceReference)
081     */
082    <S> S getService(ServiceReference<S> reference);
083
084    /**
085     * Gets a service reference for the given interface.
086     * The query is executed inside this service context.
087     * @param clazz the required interface name
088     * @return a service reference on a available provider or 
089     * <code>null</code> if no providers are available
090     * @see org.osgi.framework.BundleContext#getServiceReference(java.lang.String)
091     */
092    ServiceReference getServiceReference(String clazz);
093
094    /**
095     * Gets service reference list for the given query.
096     * The query is executed inside this service context.
097     * @param clazz : the name of the required service interface
098     * @param filter : LDAP filter to apply on service provider
099     * @return : the array of consistent service reference or <code>null</code>
100     * if no available providers
101     * @throws InvalidSyntaxException if the LDAP filter is malformed
102     * @see org.osgi.framework.BundleContext#getServiceReferences(java.lang.String, java.lang.String)
103     */
104    ServiceReference[] getServiceReferences(String clazz, String filter) throws InvalidSyntaxException;
105
106    /**
107     * Registers a service inside this service context.
108     * This service is then isolated inside this context.
109     * @param clazzes the interfaces provided by the service.
110     * @param service the service object.
111     * @param properties service properties to publish
112     * @return the service registration for this service publication.
113     * This service registration is attached to the current service context,
114     * and does not have any meaning in other contexts.
115     * @see org.apache.felix.ipojo.ServiceContext#registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)
116     */
117    ServiceRegistration registerService(String[] clazzes, Object service, Dictionary<String, ?> properties);
118
119    /**
120     * Registers a service inside this service context.
121     * This service is then isolated inside this context.
122     * @param clazz the interface provided by the service.
123     * @param service the service object.
124     * @param properties service properties to publish.
125     * @return the service registration for this service publication. 
126     * This service registration is attached to the current service context,
127     * and does not have any meaning in other contexts.
128     * @see org.osgi.framework.BundleContext#registerService(java.lang.String, java.lang.Object, java.util.Dictionary)
129     */
130    ServiceRegistration registerService(String clazz, Object service, Dictionary<String, ?> properties);
131
132    /**
133     * Removes a service listener.
134     * The listener must be registered inside this service context.
135     * @param listener the listener to remove
136     * @see org.osgi.framework.BundleContext#removeServiceListener(org.osgi.framework.ServiceListener)
137     */
138    void removeServiceListener(ServiceListener listener);
139
140    /**
141     * Ungets the service reference.
142     * The service reference must comes from this service context.
143     * @param reference the reference to unget
144     * @return <code>true</code> if you are the last user of the reference.
145     * @see org.osgi.framework.BundleContext#ungetService(org.osgi.framework.ServiceReference)
146     */
147    boolean ungetService(ServiceReference<?> reference);
148
149}