001 /*
002 * Copyright (c) OSGi Alliance (2004, 2009). 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 package org.osgi.service.cm;
017
018 import java.util.Dictionary;
019
020 import org.osgi.framework.ServiceReference;
021
022 /**
023 * A Configuration Event.
024 *
025 * <p>
026 * <code>ConfigurationEvent</code> objects are delivered to all registered
027 * <code>ConfigurationListener</code> service objects. ConfigurationEvents
028 * must be asynchronously delivered in chronological order with respect to each
029 * listener.
030 *
031 * <p>
032 * A type code is used to identify the type of event. The following event types
033 * are defined:
034 * <ul>
035 * <li>{@link #CM_UPDATED}
036 * <li>{@link #CM_DELETED}
037 * </ul>
038 * Additional event types may be defined in the future.
039 *
040 * <p>
041 * Security Considerations. <code>ConfigurationEvent</code> objects do not
042 * provide <code>Configuration</code> objects, so no sensitive configuration
043 * information is available from the event. If the listener wants to locate the
044 * <code>Configuration</code> object for the specified pid, it must use
045 * <code>ConfigurationAdmin</code>.
046 *
047 * @see ConfigurationListener
048 *
049 * @version $Revision: 6180 $
050 * @since 1.2
051 */
052 public class ConfigurationEvent {
053 /**
054 * A <code>Configuration</code> has been updated.
055 *
056 * <p>
057 * This <code>ConfigurationEvent</code> type that indicates that a
058 * <code>Configuration</code> object has been updated with new properties.
059 *
060 * An event is fired when a call to {@link Configuration#update(Dictionary)}
061 * successfully changes a configuration.
062 *
063 * <p>
064 * The value of <code>CM_UPDATED</code> is 1.
065 */
066 public static final int CM_UPDATED = 1;
067 /**
068 * A <code>Configuration</code> has been deleted.
069 *
070 * <p>
071 * This <code>ConfigurationEvent</code> type that indicates that a
072 * <code>Configuration</code> object has been deleted.
073 *
074 * An event is fired when a call to {@link Configuration#delete()}
075 * successfully deletes a configuration.
076 *
077 * <p>
078 * The value of <code>CM_DELETED</code> is 2.
079 */
080 public static final int CM_DELETED = 2;
081 /**
082 * Type of this event.
083 *
084 * @see #getType
085 */
086 private final int type;
087 /**
088 * The factory pid associated with this event.
089 */
090 private final String factoryPid;
091 /**
092 * The pid associated with this event.
093 */
094 private final String pid;
095 /**
096 * The ConfigurationAdmin service which created this event.
097 */
098 private final ServiceReference reference;
099
100 /**
101 * Constructs a <code>ConfigurationEvent</code> object from the given
102 * <code>ServiceReference</code> object, event type, and pids.
103 *
104 * @param reference The <code>ServiceReference</code> object of the
105 * Configuration Admin service that created this event.
106 * @param type The event type. See {@link #getType}.
107 * @param factoryPid The factory pid of the associated configuration if the
108 * target of the configuration is a ManagedServiceFactory. Otherwise
109 * <code>null</code> if the target of the configuration is a
110 * ManagedService.
111 * @param pid The pid of the associated configuration.
112 */
113 public ConfigurationEvent(ServiceReference reference, int type,
114 String factoryPid, String pid) {
115 this.reference = reference;
116 this.type = type;
117 this.factoryPid = factoryPid;
118 this.pid = pid;
119 if ((reference == null) || (pid == null)) {
120 throw new NullPointerException("reference and pid must not be null");
121 }
122 }
123
124 /**
125 * Returns the factory pid of the associated configuration.
126 *
127 * @return Returns the factory pid of the associated configuration if the
128 * target of the configuration is a ManagedServiceFactory. Otherwise
129 * <code>null</code> if the target of the configuration is a
130 * ManagedService.
131 */
132 public String getFactoryPid() {
133 return factoryPid;
134 }
135
136 /**
137 * Returns the pid of the associated configuration.
138 *
139 * @return Returns the pid of the associated configuration.
140 */
141 public String getPid() {
142 return pid;
143 }
144
145 /**
146 * Return the type of this event.
147 * <p>
148 * The type values are:
149 * <ul>
150 * <li>{@link #CM_UPDATED}
151 * <li>{@link #CM_DELETED}
152 * </ul>
153 *
154 * @return The type of this event.
155 */
156 public int getType() {
157 return type;
158 }
159
160 /**
161 * Return the <code>ServiceReference</code> object of the Configuration
162 * Admin service that created this event.
163 *
164 * @return The <code>ServiceReference</code> object for the Configuration
165 * Admin service that created this event.
166 */
167 public ServiceReference getReference() {
168 return reference;
169 }
170 }