Source code: org/objectstyle/cayenne/event/EventSubject.java
1 /* ====================================================================
2 *
3 * The ObjectStyle Group Software License, Version 1.0
4 *
5 * Copyright (c) 2002-2003 The ObjectStyle Group
6 * and individual authors of the software. All rights reserved.
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
10 * are met:
11 *
12 * 1. Redistributions of source code must retain the above copyright
13 * notice, this list of conditions and the following disclaimer.
14 *
15 * 2. Redistributions in binary form must reproduce the above copyright
16 * notice, this list of conditions and the following disclaimer in
17 * the documentation and/or other materials provided with the
18 * distribution.
19 *
20 * 3. The end-user documentation included with the redistribution, if
21 * any, must include the following acknowlegement:
22 * "This product includes software developed by the
23 * ObjectStyle Group (http://objectstyle.org/)."
24 * Alternately, this acknowlegement may appear in the software itself,
25 * if and wherever such third-party acknowlegements normally appear.
26 *
27 * 4. The names "ObjectStyle Group" and "Cayenne"
28 * must not be used to endorse or promote products derived
29 * from this software without prior written permission. For written
30 * permission, please contact andrus@objectstyle.org.
31 *
32 * 5. Products derived from this software may not be called "ObjectStyle"
33 * nor may "ObjectStyle" appear in their names without prior written
34 * permission of the ObjectStyle Group.
35 *
36 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39 * DISCLAIMED. IN NO EVENT SHALL THE OBJECTSTYLE GROUP OR
40 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47 * SUCH DAMAGE.
48 * ====================================================================
49 *
50 * This software consists of voluntary contributions made by many
51 * individuals on behalf of the ObjectStyle Group. For more
52 * information on the ObjectStyle Group, please see
53 * <http://objectstyle.org/>.
54 *
55 */
56
57 package org.objectstyle.cayenne.event;
58
59 import java.util.Map;
60
61 import org.apache.commons.collections.ReferenceMap;
62
63 /**
64 * This class encapsulates the String that is used to identify the <em>subject</em>
65 * that a listener is interested in. Using plain Strings causes several severe
66 * problems:
67 * <ul>
68 * <li>it's easy to misspell a subject, leading to undesired behaviour at
69 * runtime that is hard to debug.</li>
70 * <li>in systems with many different subjects there is no safeguard for
71 * defining the same subject twice for different purposes. This is especially
72 * true in a distributed setting.
73 * </ul>
74 *
75 * @author Dirk Olmes
76 * @author Holger Hoffstaette
77 */
78
79 public class EventSubject extends Object {
80
81 // a Map that will allow the values to be GC'ed
82 private static Map _registeredSubjects = new ReferenceMap(ReferenceMap.HARD, ReferenceMap.WEAK);
83
84 // Subject identifier in the form "com.foo.bar/SubjectName"
85 private String _fullyQualifiedSubjectName;
86
87 /**
88 * Returns an event subject identified by the given owner and subject name.
89 *
90 * @param subjectOwner the Class used for uniquely identifying this subject
91 * @param subjectName a String used as name, e.g. "MyEventTopic"
92 * @throws IllegalArgumentException if subjectOwner/subjectName are
93 * <code>null</code> or subjectName is empty.
94 */
95 public static EventSubject getSubject(Class subjectOwner, String subjectName) {
96 if (subjectOwner == null) {
97 throw new IllegalArgumentException("Owner class must not be null.");
98 }
99
100 if ((subjectName == null) || (subjectName.length() == 0)) {
101 throw new IllegalArgumentException("Subject name must not be null or empty.");
102 }
103
104 String fullSubjectName = subjectOwner.getName() + "/" + subjectName;
105 EventSubject newSubject = (EventSubject)_registeredSubjects.get(fullSubjectName);
106 if (newSubject == null) {
107 newSubject = new EventSubject(fullSubjectName);
108 _registeredSubjects.put(newSubject.getSubjectName(), newSubject);
109 }
110
111 return newSubject;
112 }
113
114 /**
115 * Private constructor to force use of #getSubject(Class, String)
116 */
117 private EventSubject() {
118 }
119
120 /**
121 * Protected constructor for new subjects.
122 *
123 * @param subject the name of the new subject to be created
124 */
125 protected EventSubject(String fullSubjectName) {
126 super();
127 _fullyQualifiedSubjectName = fullSubjectName;
128 }
129
130 public boolean equals(Object obj) {
131 if (obj instanceof EventSubject) {
132 return _fullyQualifiedSubjectName.equals(((EventSubject)obj).getSubjectName());
133 }
134
135 return false;
136 }
137
138 public int hashCode() {
139 return (super.hashCode() ^ _fullyQualifiedSubjectName.hashCode());
140 }
141
142 public String getSubjectName() {
143 return _fullyQualifiedSubjectName;
144 }
145
146 /**
147 * @return a String in the form
148 * <code><ClassName 0x123456> SomeName</code>
149 *
150 * @see Object#toString()
151 */
152 public String toString() {
153 StringBuffer buf = new StringBuffer(64);
154
155 buf.append("<");
156 buf.append(this.getClass().getName());
157 buf.append(" 0x");
158 buf.append(Integer.toHexString(System.identityHashCode(this)));
159 buf.append("> ");
160 buf.append(_fullyQualifiedSubjectName);
161
162 return buf.toString();
163 }
164
165 }