View Javadoc

1   /* This file is part of COPAL (COntext Provisioning for All).
2    *
3    * COPAL is a part of SM4All (Smart hoMes for All) project.
4    *
5    * COPAL is free software: you can redistribute it and/or modify
6    * it under the terms of the GNU Lesser General Public License as published by
7    * the Free Software Foundation, either version 3 of the License, or
8    * (at your option) any later version.
9    *
10   * COPAL 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
13   * GNU Lesser General Public License for more details.
14   *
15   * You should have received a copy of the GNU Lesser General Public License
16   * along with COPAL. If not, see <http://www.gnu.org/licenses/>.
17   */
18  package at.ac.tuwien.infosys.sm4all.copal.service.copal;
19  
20  import at.ac.tuwien.infosys.sm4all.copal.api.event.ContextEventType;
21  import at.ac.tuwien.infosys.sm4all.copal.api.event.xml.XMLContextEventType;
22  
23  /**
24   * Interface which COPAL provides to register, unregister, and query
25   * {@link ContextEventType}s.
26   * 
27   * @author sanjin
28   */
29  public interface ContextEventTypeRegistry {
30  
31      /**
32       * Register {@link XMLContextEventType}.
33       * 
34       * @param eventType the {@link XMLContextEventType}.
35       * @return <code>true</code> if registration was successful;
36       *         <code>false</code> otherwise.
37       */
38      boolean register(XMLContextEventType eventType);
39  
40      /**
41       * Unregister {@link XMLContextEventType} with specified name.
42       * 
43       * @param name the name of the {@link XMLContextEventType}.
44       * @return <code>true</code> if unregistration was successful;
45       *         <code>false</code> otherwise.
46       */
47      boolean unregister(String name);
48  
49      /**
50       * Checks if a {@link XMLContextEventType} with specified name is currently
51       * registered.
52       * 
53       * @param name the name of the {@link XMLContextEventType}.
54       * @return <code>true</code> if the {@link XMLContextEventType} with
55       *         specified name is registered; <code>false</code> otherwise.
56       */
57      boolean isRegistered(String name);
58  
59      /**
60       * Returns all currently registered {@link XMLContextEventType}s.
61       * 
62       * @return all currently registered {@link XMLContextEventType}s.
63       */
64      XMLContextEventType[] getEventTypes();
65  
66      /**
67       * Returns {@link XMLContextEventType} with specified name.
68       * 
69       * @param name the name of the {@link XMLContextEventType}.
70       * @return the {@link XMLContextEventType} or <code>null</code> if there is
71       *         no {@link XMLContextEventType} with specified name.
72       */
73      XMLContextEventType getEventType(String name);
74  
75      /**
76       * The {@link String} used for event name when attaching
77       * {@link ContextEventTypeObserver} to signal that this
78       * {@link ContextEventTypeObserver} should receive notifications about all
79       * {@link XMLContextEventType}.
80       */
81      final String ALL_EVENT_TYPES = "*";
82  
83      /**
84       * Attach given {@link ContextEventTypeObserver} so it will in future
85       * receive notifications for availability of {@link XMLContextEventType}
86       * with name equal to specified name. If such {@link XMLContextEventType} is
87       * already registered, the
88       * {@link ContextEventTypeObserver#onRegister(XMLContextEventType)} method
89       * will also be invoked.
90       * 
91       * @param name the name of the {@link XMLContextEventType}
92       * @param observer the {@link ContextEventTypeObserver}
93       */
94      void attach(String name, ContextEventTypeObserver observer);
95  
96      /**
97       * Detach given {@link ContextEventTypeObserver} so it doesn't receive any
98       * future notifications for availability of {@link XMLContextEventType} with
99       * name equal to specified name. If such {@link XMLContextEventType} is
100      * already registered, the
101      * {@link ContextEventTypeObserver#onUnregister(XMLContextEventType)} method
102      * will be also be invoked.
103      * 
104      * @param name the name of the {@link ContextEventType}
105      * @param observer the {@link ContextEventTypeObserver}
106      */
107     void detach(String name, ContextEventTypeObserver observer);
108 }