KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > osgi > service > event > Event


1 /*
2  * $Header: /cvshome/build/org.osgi.service.event/src/org/osgi/service/event/Event.java,v 1.8 2006/07/12 13:17:04 hargrave Exp $
3  *
4  * Copyright (c) OSGi Alliance (2005, 2006). All Rights Reserved.
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18
19 package org.osgi.service.event;
20
21 import java.util.*;
22
23 import org.osgi.framework.Filter;
24
25 /**
26  * An event.
27  *
28  * <code>Event</code> objects are delivered to <code>EventHandler</code>
29  * services which subsrcibe to the topic of the event.
30  *
31  * @version $Revision: 1.8 $
32  */
33 public class Event {
34     /**
35      * The topic of this event.
36      */
37     String JavaDoc topic;
38     /**
39      * The properties carried by this event. Keys are strings and values are
40      * objects
41      */
42     Hashtable properties;
43
44     /**
45      * Constructs an event.
46      *
47      * @param topic The topic of the event.
48      * @param properties The event's properties (may be <code>null</code>).
49      *
50      * @throws IllegalArgumentException If topic is not a valid topic name.
51      */
52     public Event(String JavaDoc topic, Dictionary properties) {
53         this.topic = topic;
54         validateTopicName();
55         this.properties = new Hashtable();
56         if (properties != null) {
57             for (Enumeration e = properties.keys(); e.hasMoreElements();) {
58                 String JavaDoc key = (String JavaDoc) e.nextElement();
59                 Object JavaDoc value = properties.get(key);
60                 this.properties.put(key, value);
61             }
62         }
63         this.properties.put(EventConstants.EVENT_TOPIC, topic);
64     }
65
66     /**
67      * Retrieves a property.
68      *
69      * @param name the name of the property to retrieve
70      *
71      * @return The value of the property, or <code>null</code> if not found.
72      */
73     public final Object JavaDoc getProperty(String JavaDoc name) {
74         return properties.get(name);
75     }
76
77     /**
78      * Returns a list of this event's property names.
79      *
80      * @return A non-empty array with one element per property.
81      */
82     public final String JavaDoc[] getPropertyNames() {
83         String JavaDoc[] names = new String JavaDoc[properties.size()];
84         Enumeration keys = properties.keys();
85         for (int i = 0; keys.hasMoreElements(); i++) {
86             names[i] = (String JavaDoc) keys.nextElement();
87         }
88         return names;
89     }
90
91     /**
92      * Returns the topic of this event.
93      *
94      * @return The topic of this event.
95      */
96     public final String JavaDoc getTopic() {
97         return topic;
98     }
99
100     /**
101      * Tests this event's properties against the given filter.
102      *
103      * @param filter The filter to test.
104      *
105      * @return true If this event's properties match the filter, false
106      * otherwise.
107      */
108     public final boolean matches(Filter filter) {
109         return filter.matchCase(properties);
110     }
111
112     /**
113      * Compares this <code>Event</code> object to another object.
114      *
115      * <p>
116      * An event is considered to be <b>equal to </b> another
117      * event if the topic is equal and the properties are equal.
118      *
119      * @param object The <code>Event</code> object to be compared.
120      * @return <code>true</code> if <code>object</code> is a
121      * <code>Event</code> and is equal to this object;
122      * <code>false</code> otherwise.
123      */
124     public boolean equals(Object JavaDoc object) {
125         if (object == this) { // quicktest
126 return true;
127         }
128
129         if (!(object instanceof Event)) {
130             return false;
131         }
132
133         Event event = (Event) object;
134         return topic.equals(event.topic) && properties.equals(event.properties);
135     }
136
137     /**
138      * Returns a hash code value for the object.
139      *
140      * @return An integer which is a hash code value for this object.
141      */
142     public int hashCode() {
143         return topic.hashCode() ^ properties.hashCode();
144     }
145
146     /**
147      * Returns the string representation of this event.
148      *
149      * @return The string representation of this event.
150      */
151     public String JavaDoc toString() {
152         return getClass().getName() + " [topic=" + topic + "]"; //$NON-NLS-1$ //$NON-NLS-2$
153 }
154
155     private static final String JavaDoc SEPARATOR = "/"; //$NON-NLS-1$
156
157     /**
158      * Called by the constructor to validate the topic name.
159      *
160      * @throws IllegalArgumentException If the topic name is invalid.
161      */
162     private void validateTopicName() {
163         try {
164             StringTokenizer st = new StringTokenizer(topic, SEPARATOR, true);
165             validateToken(st.nextToken());
166
167             while (st.hasMoreTokens()) {
168                 st.nextToken(); // consume delimiter
169 validateToken(st.nextToken());
170             }
171         }
172         catch (NoSuchElementException e) {
173             throw new IllegalArgumentException JavaDoc("invalid topic"); //$NON-NLS-1$
174 }
175     }
176
177     private static final String JavaDoc tokenAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-"; //$NON-NLS-1$
178
179     /**
180      * Validate a token.
181      *
182      * @throws IllegalArgumentException If the token is invalid.
183      */
184     private void validateToken(String JavaDoc token) {
185         int length = token.length();
186         if (length < 1) { // token must contain at least one character
187 throw new IllegalArgumentException JavaDoc("invalid topic"); //$NON-NLS-1$
188 }
189         for (int i = 0; i < length; i++) { // each character in the token must be from the token alphabet
190 if (tokenAlphabet.indexOf(token.charAt(i)) == -1) { //$NON-NLS-1$
191 throw new IllegalArgumentException JavaDoc("invalid topic"); //$NON-NLS-1$
192 }
193         }
194     }
195 }
196
Popular Tags