001/*
002 * ============================================================================
003 * Copyright © 2002-2023 by Thomas Thrien.
004 * All Rights Reserved.
005 * ============================================================================
006 *
007 * Licensed to the public under the agreements of the GNU Lesser General Public
008 * License, version 3.0 (the "License"). You may obtain a copy of the License at
009 *
010 *      http://www.gnu.org/licenses/lgpl.html
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
014 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015 * License for the specific language governing permissions and limitations
016 * under the License.
017 */
018
019package org.tquadrat.foundation.config;
020
021import static org.apiguardian.api.API.Status.STABLE;
022
023import java.io.Serial;
024import java.util.EventObject;
025
026import org.apiguardian.api.API;
027import org.tquadrat.foundation.annotation.ClassVersion;
028import org.tquadrat.foundation.lang.Objects;
029
030/**
031 *  The event object that is thrown each time a property of a configuration
032 *  bean is changed.
033 *
034 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
035 *  @version $Id: ConfigurationChangeEvent.java 1078 2023-10-19 14:39:47Z tquadrat $
036 *  @since 0.0.1
037 *
038 *  @UMLGraph.link
039 */
040@ClassVersion( sourceVersion = "$Id: ConfigurationChangeEvent.java 1078 2023-10-19 14:39:47Z tquadrat $" )
041@API( status = STABLE, since = "0.0.1" )
042public final class ConfigurationChangeEvent extends EventObject
043{
044        /*------------*\
045    ====** Attributes **=======================================================
046        \*------------*/
047    /**
048     *  The new value of the property.
049     *
050     *  @serial
051     */
052    private final Object m_NewValue;
053
054    /**
055     *  The old value of the property.
056     *
057     *  @serial
058     */
059    private final Object m_OldValue;
060
061    /**
062     *  The name of the property.
063     *
064     *  @serial
065     */
066    private final String m_PropertyName;
067
068        /*------------------------*\
069    ====** Static Initialisations **===========================================
070        \*------------------------*/
071    /**
072     *  The serial version UID for objects of this class: {@value}.
073     *
074     *  @hidden
075     */
076    @Serial
077    private static final long serialVersionUID = 1L;
078
079        /*--------------*\
080    ====** Constructors **=====================================================
081        \*--------------*/
082    /**
083     *  Creates a new {@code ConfigurationChangeEvent} instance.
084     *
085     *  @param  sourceBean  The reference to the configuration bean that fired
086     *      the change event.
087     *  @param  propertyName    The name of the property that was modified.
088     *  @param  oldValue    The property's value before the change; obviously,
089     *      this can be {@code null}, depending on the property.
090     *  @param  newValue    The new value of the property; if allowed by the
091     *      property, this can be {@code null} also.
092     */
093    public ConfigurationChangeEvent( final ConfigBeanSpec sourceBean, final String propertyName, final Object oldValue, final Object newValue )
094    {
095        super( sourceBean );    //  Parent does the null check
096        m_PropertyName = propertyName;
097        m_OldValue = oldValue;
098        m_NewValue = newValue;
099    }   //  ConfigurationChangeEvent()
100
101        /*---------*\
102    ====** Methods **==========================================================
103        \*---------*/
104    /**
105     *  Gets the new value for the property, expressed as an instance of
106     *  {@link Object}.
107     *
108     *  @return The new value for the property, expressed as an instance of
109     *      {@code Object}. May be {@code null}.
110     */
111    public final Object getNewValue() { return m_NewValue; }
112
113    /**
114     *  Gets the old value for the property, expressed as an instance of
115     *  {@link Object}.
116     *
117     *  @return The old value for the property, expressed as an instance of
118     *      {@code Object}. May be {@code null}.
119     */
120    public final Object getOldValue() { return m_OldValue; }
121
122    /**
123     *  Gets the name of the configuration property that was changed.
124     *
125     *  @return The name of the property that was changed.
126     */
127    public final String getPropertyName() { return m_PropertyName; }
128
129    /**
130     *  {@inheritDoc}
131     */
132    @Override
133    public final ConfigBeanSpec getSource() { return (ConfigBeanSpec) super.getSource(); }
134
135    /**
136     *  {@inheritDoc}
137     */
138    @Override
139    public final String toString()
140    {
141        final var retValue =
142            "%1$s [propertyName=%3$s; oldValue=%4$s; newValue=%5$s; source=%2$s]".formatted(
143                getClass().getName(),
144                getSource().getClass().getName(),
145                getPropertyName(),
146                Objects.toString( getOldValue() ),
147                Objects.toString( getNewValue() ) );
148
149        //---* Done *----------------------------------------------------------
150        return retValue;
151    }   //  toString()
152}
153//  class ConfigurationChangeEvent
154
155/*
156 *  End of File
157 */