1. Project Clover database Tue Dec 20 2016 21:24:09 CET
  2. Package org.xwiki.component.manager

File ComponentManager.java

 

Code metrics

0
0
0
1
206
30
0
-
-
0
-

Classes

Class Line # Actions
ComponentManager 35 0 - 0 0
-1.0 -
 

Contributing tests

No tests hitting this source file were found.

Source view

1    /*
2    * See the NOTICE file distributed with this work for additional
3    * information regarding copyright ownership.
4    *
5    * This is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU Lesser General Public License as
7    * published by the Free Software Foundation; either version 2.1 of
8    * the License, or (at your option) any later version.
9    *
10    * This software is distributed in the hope that it will be useful,
11    * but WITHOUT ANY WARRANTY; without even the implied warranty of
12    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13    * Lesser General Public License for more details.
14    *
15    * You should have received a copy of the GNU Lesser General Public
16    * License along with this software; if not, write to the Free
17    * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
18    * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
19    */
20    package org.xwiki.component.manager;
21   
22    import java.lang.reflect.Type;
23    import java.util.List;
24    import java.util.Map;
25   
26    import org.xwiki.component.annotation.Role;
27    import org.xwiki.component.descriptor.ComponentDescriptor;
28   
29    /**
30    * Provide way to access and modify components repository.
31    *
32    * @version $Id: 00b7940374796e9d5c47b78947ddee27c7eed909 $
33    */
34    @Role
 
35    public interface ComponentManager
36    {
37    /**
38    * @param role the class (aka role) that the component implements
39    * @return true if the component is registered or false otherwise
40    * @since 4.0M1
41    */
42    boolean hasComponent(Type role);
43   
44    /**
45    * @param role the class (aka role) that the component implements
46    * @param hint the hint that differentiates a component implementation from another one (each component is
47    * registered with a hint; the "default" hint being the default)
48    * @return true if the component is registered for the passed hint or false otherwise
49    * @since 4.0M1
50    */
51    boolean hasComponent(Type role, String hint);
52   
53    /**
54    * Find a component instance that implements that passed type. If the component has a singleton lifecycle then this
55    * method always return the same instance.
56    *
57    * @param <T> the component role type
58    * @param roleType the class (aka role) that the component implements
59    * @return the component instance
60    * @throws ComponentLookupException in case the component cannot be found
61    * @since 4.0RC1
62    */
63    <T> T getInstance(Type roleType) throws ComponentLookupException;
64   
65    /**
66    * Find a component instance that implements that passed interface class. If the component has a singleton lifecycle
67    * then this method always return the same instance.
68    *
69    * @param <T> the component role type
70    * @param roleType the class (aka role) that the component implements
71    * @param roleHint the hint that differentiates a component implementation from another one (each component is
72    * registered with a hint; the "default" hint being the default)
73    * @return the component instance
74    * @throws ComponentLookupException in case the component cannot be found
75    * @since 4.0RC1
76    */
77    <T> T getInstance(Type roleType, String roleHint) throws ComponentLookupException;
78   
79    /**
80    * Release the provided singleton instance but don't unregister the component descriptor. This means that next time
81    * the component is looked up a new instance will be created.
82    *
83    * @param componentInstance the component to release passed as a component instance.
84    * @throws ComponentLifecycleException if the component's ending lifecycle raises an error
85    * @since 4.0M1
86    */
87    void release(Object componentInstance) throws ComponentLifecycleException;
88   
89    /**
90    * Find all the components implementing the provided role.
91    *
92    * @param role the type of the components role
93    * @return the components
94    * @param <T> the type of the components role
95    * @throws ComponentLookupException if any error happen during component search
96    * @since 4.0RC1
97    */
98    <T> List<T> getInstanceList(Type role) throws ComponentLookupException;
99   
100    /**
101    * Find all the components implementing the provided role and organize then in a {@link Map} with role hint as key.
102    *
103    * @param role the type of the components role
104    * @return the components
105    * @param <T> the type of the components role
106    * @throws ComponentLookupException if any error happen during component search
107    * @since 4.0M1
108    */
109    <T> Map<String, T> getInstanceMap(Type role) throws ComponentLookupException;
110   
111    /**
112    * Add a component in the component repository dynamically.
113    * <p>
114    * If a component with the same role and role hint already exists it will be replaced by this provided one when
115    * lookup.
116    *
117    * @param <T> the component role type
118    * @param componentDescriptor the descriptor of the component to register.
119    * @throws ComponentRepositoryException error when registering component descriptor.
120    * @since 1.7M1
121    */
122    <T> void registerComponent(ComponentDescriptor<T> componentDescriptor) throws ComponentRepositoryException;
123   
124    /**
125    * Add a component in the component repository dynamically. This method also makes possible to set the instance
126    * returned by the {@link ComponentManager} instead of letting it created it from descriptor.
127    * <p>
128    * If a component with the same role and role hint already exists it will be replaced by this provided one when
129    * lookup.
130    *
131    * @param <T> the component role type
132    * @param componentDescriptor the descriptor of the component to register.
133    * @param componentInstance the initial component instance
134    * @throws ComponentRepositoryException error when registering component descriptor.
135    * @since 2.0M2
136    */
137    <T> void registerComponent(ComponentDescriptor<T> componentDescriptor, T componentInstance)
138    throws ComponentRepositoryException;
139   
140    /**
141    * Remove a component from the component repository dynamically.
142    *
143    * @param role the role identifying the component
144    * @param hint the hint identifying the component
145    * @since 4.0M1
146    */
147    void unregisterComponent(Type role, String hint);
148   
149    /**
150    * Remove a component from the component repository dynamically.
151    *
152    * @param componentDescriptor the component descriptor
153    * @since 4.0M1
154    */
155    void unregisterComponent(ComponentDescriptor<?> componentDescriptor);
156   
157    /**
158    * @param <T> the component role type
159    * @param role the role identifying the component
160    * @param hint the hint identifying the component
161    * @return the descriptor for the component matching the passed parameter or null if this component doesn't exist
162    * @since 4.0M1
163    */
164    <T> ComponentDescriptor<T> getComponentDescriptor(Type role, String hint);
165   
166    /**
167    * @param <T> the role class for which to return all component implementations
168    * @param role the role class for which to return all component implementations
169    * @return all component implementations for the passed role
170    * @since 4.0M1
171    */
172    <T> List<ComponentDescriptor<T>> getComponentDescriptorList(Type role);
173   
174    /**
175    * @return the manager to use to send events when a component descriptor is registered
176    * @since 2.1RC1
177    */
178    ComponentEventManager getComponentEventManager();
179   
180    /**
181    * @param eventManager the manager to use to send events when a component descriptor is registered
182    */
183    void setComponentEventManager(ComponentEventManager eventManager);
184   
185    /**
186    * @return the parent Component Manager of this Component Manager. When doing lookups if the component cannot be
187    * found in the current Component Manager it'll also be looked for in the parent Component Manager
188    */
189    ComponentManager getParent();
190   
191    /**
192    * @param parentComponentManager see {@link #getParent()}
193    */
194    void setParent(ComponentManager parentComponentManager);
195   
196    // Deprecated
197   
198    /**
199    * @param <T> the role class for which to return all component implementations
200    * @param role the role class for which to return all component implementations
201    * @return all component implementations for the passed role
202    * @deprecated since 4.0M1 use {@link #getComponentDescriptorList(Type)} instead
203    */
204    @Deprecated
205    <T> List<ComponentDescriptor<T>> getComponentDescriptorList(Class<T> role);
206    }