View Javadoc

1   /*
2    * $Id: Registry.java 20278 2010-11-19 18:56:45Z dfeist $
3    * --------------------------------------------------------------------------------------
4    * Copyright (c) MuleSoft, Inc.  All rights reserved.  http://www.mulesoft.com
5    *
6    * The software in this package is published under the terms of the CPAL v1.0
7    * license, a copy of which has been included with this distribution in the
8    * LICENSE.txt file.
9    */
10  
11  package org.mule.api.registry;
12  
13  import org.mule.api.lifecycle.Disposable;
14  import org.mule.api.lifecycle.Initialisable;
15  import org.mule.api.lifecycle.LifecycleException;
16  
17  import java.util.Collection;
18  import java.util.Map;
19  
20  public interface Registry extends Initialisable, Disposable
21  {
22      // /////////////////////////////////////////////////////////////////////////
23      // Lookup methods - these should NOT create a new object, only return existing ones
24      // /////////////////////////////////////////////////////////////////////////
25  
26      /**
27       * Alias method performing the lookup, here to simplify syntax when called from dynamic languages.
28       */
29      <T> T get(String key);
30  
31      /** 
32       * Look up a single object by name. 
33       * @return object or null if not found
34       */
35      <T> T lookupObject(String key);
36  
37      /**
38       * Look up all objects of a given type.
39       *
40       * @return collection of objects or empty collection if none found
41       */
42      <T> Collection<T> lookupObjects(Class<T> type);
43  
44      /**
45       * Look up all objects of a given type that lifecycle should be applied to. This
46       * method differs from {@link #lookupObjects(Class)} in that it allows
47       * implementations to provide an alternative implementation of lookup for
48       * lifecycle. For example only returning pre-existing objects and not creating
49       * new ones on the fly.
50       * 
51       * @return collection of objects or empty collection if none found
52       */
53      <T> Collection<T> lookupObjectsForLifecycle(Class<T> type);
54      
55      /**
56       * Look up a single object by type.
57       *
58       * @return object or null if not found
59       * @throws RegistrationException if more than one object is found.
60       */
61      <T> T lookupObject(Class<T> clazz) throws RegistrationException;
62  
63      /**
64       * @return key/object pairs
65       */
66      <T> Map<String, T> lookupByType(Class<T> type);
67  
68      // /////////////////////////////////////////////////////////////////////////
69      // Registration methods
70      // /////////////////////////////////////////////////////////////////////////
71  
72      /**
73       * Registers an object in the registry with a key.
74       * @param key the key to store the value against.  This is a non-null value
75       * @param value the object to store in the registry. This is a non-null value
76       * @throws RegistrationException if an object with the same key already exists
77       */
78      void registerObject(String key, Object value) throws RegistrationException;
79  
80      /**
81       * Registers an object in the registry with a key.
82       * @param key the key to store the value against.  This is a non-null value
83       * @param value the object to store in the registry. This is a non-null value
84       * @param metadata an implementation specific argument that can be passed into the method
85       * @throws RegistrationException if an object with the same key already exists
86       */
87      void registerObject(String key, Object value, Object metadata) throws RegistrationException;
88  
89      /**
90       * Registers a Map of objects into the registry
91       * @param objects a map of key value pairs, each will individually be registered in the registry
92       * @throws RegistrationException if an object with the same key already exists
93       */
94      void registerObjects(Map<String, Object> objects) throws RegistrationException;
95  
96      /**
97       * Will remove an object by name from the registry. By default the registry must apply all remaining lifecycle phases
98       * to the object when it is removed.
99       *
100      * @param key the name or key of the object to remove from the registry
101      * @throws RegistrationException if there is a problem unregistering the object. Typically this will be because 
102      * the object's lifecycle threw an exception
103      */
104     void unregisterObject(String key) throws RegistrationException;
105 
106     /**
107      * Will remove an object by name from the registry. By default the registry must apply all remaining lifecycle phases
108      * to the object when it is removed.
109      *
110      * @param key the name or key of the object to remove from the registry
111      * @param metadata an implementation specific argument that can be passed into the method
112      * @throws RegistrationException if there is a problem unregistering the object. Typically this will be because
113      * the object's lifecycle threw an exception
114      */
115     void unregisterObject(String key, Object metadata) throws RegistrationException;
116 
117     // /////////////////////////////////////////////////////////////////////////
118     // Registry Metadata
119     // /////////////////////////////////////////////////////////////////////////
120 
121     String getRegistryId();
122 
123     //TODO should this really be here
124     void fireLifecycle(String phase) throws LifecycleException;
125 
126     boolean isReadOnly();
127 
128     boolean isRemote();
129 }