001 /*
002 * Copyright (c) OSGi Alliance (2005, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package org.osgi.service.event;
018
019 import org.osgi.framework.Bundle;
020 import org.osgi.framework.Constants;
021 import org.osgi.framework.Filter;
022 import org.osgi.framework.ServiceReference;
023 import org.osgi.framework.Version;
024
025 /**
026 * Defines standard names for <code>EventHandler</code> properties.
027 *
028 * @version $Revision: 6080 $
029 */
030 public interface EventConstants {
031
032 /**
033 * Service registration property (named <code>event.topics</code>)
034 * specifying the <code>Event</code> topics of interest to a Event Handler
035 * service.
036 * <p>
037 * Event handlers SHOULD be registered with this property. The value of the
038 * property is a string or an array of strings that describe the topics in
039 * which the handler is interested. An asterisk ('*') may be used as a
040 * trailing wildcard. Event Handlers which do not have a value for this
041 * property must not receive events. More precisely, the value of each
042 * string must conform to the following grammar:
043 *
044 * <pre>
045 * topic-description := '*' | topic ( '/*' )?
046 * topic := token ( '/' token )*
047 * </pre>
048 *
049 * @see Event
050 */
051 public static final String EVENT_TOPIC = "event.topics";
052
053 /**
054 * Service Registration property (named <code>event.filter</code>)
055 * specifying a filter to further select <code>Event</code> s of interest to
056 * a Event Handler service.
057 * <p>
058 * Event handlers MAY be registered with this property. The value of this
059 * property is a string containing an LDAP-style filter specification. Any
060 * of the event's properties may be used in the filter expression. Each
061 * event handler is notified for any event which belongs to the topics in
062 * which the handler has expressed an interest. If the event handler is also
063 * registered with this service property, then the properties of the event
064 * must also match the filter for the event to be delivered to the event
065 * handler.
066 * <p>
067 * If the filter syntax is invalid, then the Event Handler must be ignored
068 * and a warning should be logged.
069 *
070 * @see Event
071 * @see Filter
072 */
073 public static final String EVENT_FILTER = "event.filter";
074
075 /**
076 * The Distinguished Names of the signers of the bundle relevant to the
077 * event. The type of the value for this event property is
078 * <code>String</code> if there is a single signer or <code>String[]</code>
079 * if there are multiple signers.
080 */
081 public static final String BUNDLE_SIGNER = "bundle.signer";
082
083 /**
084 * The Bundle Symbolic Name of the bundle relevant to the event. The type of
085 * the value for this event property is <code>String</code>.
086 */
087 public static final String BUNDLE_SYMBOLICNAME = "bundle.symbolicName";
088
089 /**
090 * The Bundle id of the bundle relevant to the event. The type of the value
091 * for this event property is <code>Long</code>.
092 *
093 * @since 1.1
094 */
095 public static final String BUNDLE_ID = "bundle.id";
096
097 /**
098 * The Bundle object of the bundle relevant to the event. The type of the
099 * value for this event property is {@link Bundle}.
100 *
101 * @since 1.1
102 */
103 public static final String BUNDLE = "bundle";
104
105 /**
106 * The version of the bundle relevant to the event. The type of the value
107 * for this event property is {@link Version}.
108 *
109 * @since 1.2
110 */
111 public static final String BUNDLE_VERSION = "bundle.version";
112
113 /**
114 * The forwarded event object. Used when rebroadcasting an event that was
115 * sent via some other event mechanism. The type of the value for this event
116 * property is <code>Object</code>.
117 */
118 public static final String EVENT = "event";
119
120 /**
121 * An exception or error. The type of the value for this event property is
122 * <code>Throwable</code>.
123 */
124 public static final String EXCEPTION = "exception";
125
126 /**
127 * The name of the exception type. Must be equal to the name of the class of
128 * the exception in the event property {@link #EXCEPTION}. The type of the
129 * value for this event property is <code>String</code>.
130 *
131 * @since 1.1
132 */
133 public static final String EXCEPTION_CLASS = "exception.class";
134
135 /**
136 * The exception message. Must be equal to the result of calling
137 * <code>getMessage()</code> on the exception in the event property
138 * {@link #EXCEPTION}. The type of the value for this event property is
139 * <code>String</code>.
140 */
141 public static final String EXCEPTION_MESSAGE = "exception.message";
142
143 /**
144 * A human-readable message that is usually not localized. The type of the
145 * value for this event property is <code>String</code>.
146 */
147 public static final String MESSAGE = "message";
148
149 /**
150 * A service reference. The type of the value for this event property is
151 * {@link ServiceReference}.
152 */
153 public static final String SERVICE = "service";
154
155 /**
156 * A service's id. The type of the value for this event property is
157 * <code>Long</code>.
158 */
159 public static final String SERVICE_ID = Constants.SERVICE_ID;
160
161 /**
162 * A service's objectClass. The type of the value for this event property is
163 * <code>String[]</code>.
164 */
165 public static final String SERVICE_OBJECTCLASS = "service.objectClass";
166
167 /**
168 * A service's persistent identity. The type of the value for this event
169 * property is <code>String</code>.
170 */
171 public static final String SERVICE_PID = Constants.SERVICE_PID;
172
173 /**
174 * The time when the event occurred, as reported by
175 * <code>System.currentTimeMillis()</code>. The type of the value for this
176 * event property is <code>Long</code>.
177 */
178 public static final String TIMESTAMP = "timestamp";
179
180 /**
181 * This constant was released with an incorrectly spelled name. It has been
182 * replaced by {@link #EXCEPTION_CLASS}
183 *
184 * @deprecated As of 1.1, replaced by EXCEPTION_CLASS
185 */
186 public static final String EXECPTION_CLASS = "exception.class";
187 }