View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.configuration2.builder;
18  
19  import org.apache.commons.configuration2.event.Event;
20  import org.apache.commons.configuration2.event.EventType;
21  
22  /**
23   * <p>
24   * A base event class for events generated by a {@link ConfigurationBuilder}.
25   * </p>
26   * <p>
27   * Configuration builders can trigger a number of different events. All these events are derived from this class. This
28   * event base class does not define any additional properties. However, it defines that the event source must be a
29   * {@code ConfigurationBuilder}.
30   * </p>
31   *
32   * @since 2.0
33   */
34  public class ConfigurationBuilderEvent extends Event {
35  
36      private static final long serialVersionUID = -7488811456039315104L;
37  
38      /** The common super type for all events related to configuration builders. */
39      public static final EventType<ConfigurationBuilderEvent> ANY = new EventType<>(Event.ANY, "BUILDER");
40  
41      /**
42       * The specific event type for builder reset events. Events of this type are generated each time the builder's
43       * {@code resetResult()} method is called.
44       */
45      public static final EventType<ConfigurationBuilderEvent> RESET = new EventType<>(ANY, "RESET");
46  
47      /**
48       * The specific event type for configuration request events. Events of this type are generated each time the builder's
49       * {@code getConfiguration()} method is called (before the managed configuration is actually accessed and the lock is
50       * acquired). This gives listeners the opportunity to perform some checks which may invalidate the configuration, e.g.
51       * trigger a reload check. <strong>Note:</strong> A listener must not call the builder's {@code getConfiguration()}
52       * method - this will cause an infinite loop!
53       *
54       * @see ConfigurationBuilder#getConfiguration()
55       */
56      public static final EventType<ConfigurationBuilderEvent> CONFIGURATION_REQUEST = new EventType<>(ANY, "CONFIGURATION_REQUEST");
57  
58      /**
59       * Creates a new instance of {@code ConfigurationBuilderEvent} and sets basic properties.
60       *
61       * @param source the {@code ConfigurationBuilder} object which triggered this event (must not be <b>null</b>)
62       * @param evType the type of this event (must not be <b>null</b>)
63       * @throws IllegalArgumentException if a required parameter is null
64       */
65      public ConfigurationBuilderEvent(final ConfigurationBuilder<?> source, final EventType<? extends ConfigurationBuilderEvent> evType) {
66          super(source, evType);
67      }
68  
69      /**
70       * Gets the source of this event as a {@code ConfigurationBuilder}.
71       *
72       * @return the {@code ConfigurationBuilder} which generated this event
73       */
74      @Override
75      public ConfigurationBuilder<?> getSource() {
76          return (ConfigurationBuilder<?>) super.getSource();
77      }
78  }