001    package org.bukkit.plugin;
002    
003    import java.util.Collection;
004    import java.util.List;
005    
006    /**
007     * Manages services and service providers. Services are an interface
008     * specifying a list of methods that a provider must implement. Providers are
009     * implementations of these services. A provider can be queried from the
010     * services manager in order to use a service (if one is available). If
011     * multiple plugins register a service, then the service with the highest
012     * priority takes precedence.
013     */
014    public interface ServicesManager {
015    
016        /**
017         * Register a provider of a service.
018         *
019         * @param <T> Provider
020         * @param service service class
021         * @param provider provider to register
022         * @param plugin plugin with the provider
023         * @param priority priority of the provider
024         */
025        public <T> void register(Class<T> service, T provider, Plugin plugin, ServicePriority priority);
026    
027        /**
028         * Unregister all the providers registered by a particular plugin.
029         *
030         * @param plugin The plugin
031         */
032        public void unregisterAll(Plugin plugin);
033    
034        /**
035         * Unregister a particular provider for a particular service.
036         *
037         * @param service The service interface
038         * @param provider The service provider implementation
039         */
040        public void unregister(Class<?> service, Object provider);
041    
042        /**
043         * Unregister a particular provider.
044         *
045         * @param provider The service provider implementation
046         */
047        public void unregister(Object provider);
048    
049        /**
050         * Queries for a provider. This may return if no provider has been
051         * registered for a service. The highest priority provider is returned.
052         *
053         * @param <T> The service interface
054         * @param service The service interface
055         * @return provider or null
056         */
057        public <T> T load(Class<T> service);
058    
059        /**
060         * Queries for a provider registration. This may return if no provider
061         * has been registered for a service.
062         *
063         * @param <T> The service interface
064         * @param service The service interface
065         * @return provider registration or null
066         */
067        public <T> RegisteredServiceProvider<T> getRegistration(Class<T> service);
068    
069        /**
070         * Get registrations of providers for a plugin.
071         *
072         * @param plugin The plugin
073         * @return provider registration or null
074         */
075        public List<RegisteredServiceProvider<?>> getRegistrations(Plugin plugin);
076    
077        /**
078         * Get registrations of providers for a service. The returned list is
079         * unmodifiable.
080         *
081         * @param <T> The service interface
082         * @param service The service interface
083         * @return list of registrations
084         */
085        public <T> Collection<RegisteredServiceProvider<T>> getRegistrations(Class<T> service);
086    
087        /**
088         * Get a list of known services. A service is known if it has registered
089         * providers for it.
090         *
091         * @return list of known services
092         */
093        public Collection<Class<?>> getKnownServices();
094    
095        /**
096         * Returns whether a provider has been registered for a service. Do not
097         * check this first only to call <code>load(service)</code> later, as that
098         * would be a non-thread safe situation.
099         *
100         * @param <T> service
101         * @param service service to check
102         * @return whether there has been a registered provider
103         */
104        public <T> boolean isProvidedFor(Class<T> service);
105    
106    }