/*
GNU GENERAL LICENSE
Copyright (C) 2006 The Lobo Project. Copyright (C) 2014 - 2017 Lobo Evolution
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public
License as published by the Free Software Foundation; either
verion 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General License for more details.
You should have received a copy of the GNU General Public
along with this program. If not, see <http://www.gnu.org/licenses/>.
Contact info: lobochief@users.sourceforge.net; ivan.difrancesco@yahoo.it
*/
package org.lobobrowser.http;
import java.beans.PropertyChangeEvent;
import java.beans.PropertyChangeListener;
import java.beans.PropertyChangeSupport;
import java.beans.PropertyVetoException;
import java.beans.VetoableChangeListener;
import java.beans.VetoableChangeSupport;
/**
* <p>
* A convenience class from which to extend all non-visual JavaBeans. It manages
* the PropertyChange notification system, making it relatively trivial to add
* support for property change events in getters/setters.
* </p>
*
* <p>
* A non-visual java bean is a Java class that conforms to the JavaBean patterns
* to allow visual manipulation of the bean's properties and event handlers at
* design-time.
* </p>
*
* Here is a simple example bean that contains one property, foo, and the proper
* pattern for implementing property change notification:
*
* <pre>
* <code>
* public class ABean extends JavaBean {
* private String foo;
*
* public void setFoo(String newFoo) {
* String old = getFoo();
* this.foo = newFoo;
* firePropertyChange("foo", old, getFoo());
* }
*
* public String getFoo() {
* return foo;
* }
* }
* </code>
* </pre>
*
* <p>
* You will notice that "getFoo()" is used in the setFoo method rather than
* accessing "foo" directly for the gets. This is done intentionally so that if
* a subclass overrides getFoo() to return, for instance, a constant value the
* property change notification system will continue to work properly.
* </p>
*
* <p>
* The firePropertyChange method takes into account the old value and the new
* value. Only if the two differ will it fire a property change event. So you
* can be assured from the above code fragment that a property change event will
* only occur if old is indeed different from getFoo()
* </p>
*
* <code>JavaBean</code> also supports VetoablePropertyChange events. These
* events are similar to <code>PropertyChange</code> events, except a special
* exception can be used to veto changing the property. For example, perhaps the
* property is changing from "fred" to "red", but a listener deems that "red" is
* unexceptable. In this case, the listener can fire a veto exception and the
* property must remain "fred". For example:
*
* <pre>
* <code>
* public class ABean extends JavaBean {
* private String foo;
*
* public void setFoo(String newFoo) throws PropertyVetoException {
* String old = getFoo();
* this.foo = newFoo;
* fireVetoableChange("foo", old, getFoo());
* }
*
* public String getFoo() {
* return foo;
* }
* }
*
* public class Tester {
* public static void main(String... args) {
* try {
* ABean a = new ABean();
* a.setFoo("fred");
* a.addVetoableChangeListener(new VetoableChangeListener() {
* public void vetoableChange(PropertyChangeEvent evt) throws PropertyVetoException {
* if ("red".equals(evt.getNewValue()) {
* throw new PropertyVetoException("Cannot be red!", evt);
* }
* }
* }
* a.setFoo("red");
* } catch (Exception e) {
* logger.error(e.getMessage()); // this will be executed
* }
* }
* }
* </code>
* </pre>
*
* status REVIEWED
*
* @author rbair
*/
public abstract class AbstractBean {
/**
* Helper class that manages all the property change notification machinery.
* PropertyChangeSupport cannot be extended directly because it requires a
* bean in the constructor, and the "this" argument is not valid until after
* super construction. Hence, delegation instead of extension
*/
private transient PropertyChangeSupport pcs;
/**
* Helper class that manages all the veto property change notification
* machinery.
*/
private transient VetoableChangeSupport vcs;
/**
* Creates a new instance of JavaBean.
*/
protected AbstractBean() {
pcs = new PropertyChangeSupport(this);
vcs = new VetoableChangeSupport(this);
}
/**
* Creates a new instance of JavaBean, using the supplied
* PropertyChangeSupport and VetoableChangeSupport delegates. Neither of
* these may be null.
*
* @param pcs
* the pcs
* @param vcs
* the vcs
*/
protected AbstractBean(final PropertyChangeSupport pcs,
final VetoableChangeSupport vcs) {
if (pcs == null) {
throw new NullPointerException(
"PropertyChangeSupport must not be null");
}
if (vcs == null) {
throw new NullPointerException(
"VetoableChangeSupport must not be null");
}
this.pcs = pcs;
this.vcs = vcs;
}
/**
* Add a PropertyChangeListener to the listener list. The listener is
* registered for all properties. The same listener object may be added more
* than once, and will be called as many times as it is added. If
* <code>listener</code> is null, no exception is thrown and no action is
* taken.
*
* @param listener
* The PropertyChangeListener to be added
*/
public void addPropertyChangeListener(
final PropertyChangeListener listener) {
pcs.addPropertyChangeListener(listener);
}
/**
* Remove a PropertyChangeListener from the listener list. This removes a
* PropertyChangeListener that was registered for all properties. If
* <code>listener</code> was added more than once to the same event source,
* it will be notified one less time after being removed. If
* <code>listener</code> is null, or was never added, no exception is thrown
* and no action is taken.
*
* @param listener
* The PropertyChangeListener to be removed
*/
public void removePropertyChangeListener(
final PropertyChangeListener listener) {
pcs.removePropertyChangeListener(listener);
}
/** Gets the property change listeners.
*
* @return the property change listeners
*/
public PropertyChangeListener[] getPropertyChangeListeners() {
return pcs.getPropertyChangeListeners();
}
/**
* Add a PropertyChangeListener for a specific property. The listener will
* be invoked only when a call on firePropertyChange names that specific
* property. The same listener object may be added more than once. For each
* property, the listener will be invoked the number of times it was added
* for that property. If <code>propertyName</code> or <code>listener</code>
* is null, no exception is thrown and no action is taken.
*
* @param propertyName
* The name of the property to listen on.
* @param listener
* The PropertyChangeListener to be added
*/
public void addPropertyChangeListener(final String propertyName,
final PropertyChangeListener listener) {
pcs.addPropertyChangeListener(propertyName, listener);
}
/**
* Remove a PropertyChangeListener for a specific property. If
* <code>listener</code> was added more than once to the same event source
* for the specified property, it will be notified one less time after being
* removed. If <code>propertyName</code> is null, no exception is thrown and
* no action is taken. If <code>listener</code> is null, or was never added
* for the specified property, no exception is thrown and no action is
* taken.
*
* @param propertyName
* The name of the property that was listened on.
* @param listener
* The PropertyChangeListener to be removed
*/
public void removePropertyChangeListener(final String propertyName,
final PropertyChangeListener listener) {
pcs.removePropertyChangeListener(propertyName, listener);
}
/**
* Returns an array of all the listeners which have been associated with the
* named property.
*
* @param propertyName
* The name of the property being listened to
* @return all of the <code>PropertyChangeListeners</code> associated with
* the named property. If no such listeners have been added, or if
* <code>propertyName</code> is null, an empty array is returned.
*/
public PropertyChangeListener[] getPropertyChangeListeners(
final String propertyName) {
return pcs.getPropertyChangeListeners(propertyName);
}
/**
* Report a bound property update to any registered listeners. No event is
* fired if old and new are equal and non-null.
*
* <p>
* This is merely a convenience wrapper around the more general
* firePropertyChange method that takes {@code PropertyChangeEvent} value.
*
* @param propertyName
* The programmatic name of the property that was changed.
* @param oldValue
* The old value of the property.
* @param newValue
* The new value of the property.
*/
protected void firePropertyChange(final String propertyName,
final Object oldValue, final Object newValue) {
pcs.firePropertyChange(propertyName, oldValue, newValue);
}
/**
* Fire an existing PropertyChangeEvent to any registered listeners. No
* event is fired if the given event's old and new values are equal and
* non-null.
*
* @param evt
* The PropertyChangeEvent object.
*/
protected void firePropertyChange(final PropertyChangeEvent evt) {
pcs.firePropertyChange(evt);
}
/**
* Report a bound indexed property update to any registered listeners.
* <p>
* No event is fired if old and new values are equal and non-null.
*
* <p>
* This is merely a convenience wrapper around the more general
* firePropertyChange method that takes {@code PropertyChangeEvent} value.
*
* @param propertyName
* The programmatic name of the property that was changed.
* @param index
* index of the property element that was changed.
* @param oldValue
* The old value of the property.
* @param newValue
* The new value of the property.
*/
protected void fireIndexedPropertyChange(final String propertyName,
final int index, final Object oldValue, final Object newValue) {
pcs.fireIndexedPropertyChange(propertyName, index, oldValue, newValue);
}
/**
* Check if there are any listeners for a specific property, including those
* registered on all properties. If <code>propertyName</code> is null, only
* check for listeners registered on all properties.
*
* @param propertyName
* the property name.
* @return true if there are one or more listeners for the given property
*/
protected boolean hasPropertyChangeListeners(final String propertyName) {
return pcs.hasListeners(propertyName);
}
/**
* Check if there are any listeners for a specific property, including those
* registered on all properties. If <code>propertyName</code> is null, only
* check for listeners registered on all properties.
*
* @param propertyName
* the property name.
* @return true if there are one or more listeners for the given property
*/
protected boolean hasVetoableChangeListeners(final String propertyName) {
return vcs.hasListeners(propertyName);
}
/**
* Add a VetoableListener to the listener list. The listener is registered
* for all properties. The same listener object may be added more than once,
* and will be called as many times as it is added. If <code>listener</code>
* is null, no exception is thrown and no action is taken.
*
* @param listener
* The VetoableChangeListener to be added
*/
public void addVetoableChangeListener(
final VetoableChangeListener listener) {
vcs.addVetoableChangeListener(listener);
}
/**
* Remove a VetoableChangeListener from the listener list. This removes a
* VetoableChangeListener that was registered for all properties. If
* <code>listener</code> was added more than once to the same event source,
* it will be notified one less time after being removed. If
* <code>listener</code> is null, or was never added, no exception is thrown
* and no action is taken.
*
* @param listener
* The VetoableChangeListener to be removed
*/
public void removeVetoableChangeListener(
final VetoableChangeListener listener) {
vcs.removeVetoableChangeListener(listener);
}
/** Gets the vetoable change listeners.
*
* @return the vetoable change listeners
*/
public VetoableChangeListener[] getVetoableChangeListeners() {
return vcs.getVetoableChangeListeners();
}
/**
* Add a VetoableChangeListener for a specific property. The listener will
* be invoked only when a call on fireVetoableChange names that specific
* property. The same listener object may be added more than once. For each
* property, the listener will be invoked the number of times it was added
* for that property. If <code>propertyName</code> or <code>listener</code>
* is null, no exception is thrown and no action is taken.
*
* @param propertyName
* The name of the property to listen on.
* @param listener
* The VetoableChangeListener to be added
*/
public void addVetoableChangeListener(final String propertyName,
final VetoableChangeListener listener) {
vcs.addVetoableChangeListener(propertyName, listener);
}
/**
* Remove a VetoableChangeListener for a specific property. If
* <code>listener</code> was added more than once to the same event source
* for the specified property, it will be notified one less time after being
* removed. If <code>propertyName</code> is null, no exception is thrown and
* no action is taken. If <code>listener</code> is null, or was never added
* for the specified property, no exception is thrown and no action is
* taken.
*
* @param propertyName
* The name of the property that was listened on.
* @param listener
* The VetoableChangeListener to be removed
*/
public void removeVetoableChangeListener(final String propertyName,
final VetoableChangeListener listener) {
vcs.removeVetoableChangeListener(propertyName, listener);
}
/**
* Returns an array of all the listeners which have been associated with the
* named property.
*
* @param propertyName
* The name of the property being listened to
* @return all the <code>VetoableChangeListeners</code> associated with the
* named property. If no such listeners have been added, or if
* <code>propertyName</code> is null, an empty array is returned.
*/
public VetoableChangeListener[] getVetoableChangeListeners(
final String propertyName) {
return vcs.getVetoableChangeListeners(propertyName);
}
/**
* Report a vetoable property update to any registered listeners. If anyone
* vetos the change, then fire a new event reverting everyone to the old
* value and then rethrow the PropertyVetoException.
* <p>
* No event is fired if old and new are equal and non-null.
*
* @param propertyName
* The programmatic name of the property that is about to
* change..
* @param oldValue
* The old value of the property.
* @param newValue
* The new value of the property.
* @exception PropertyVetoException
* if the recipient wishes the property change to be rolled
* back.
*/
protected void fireVetoableChange(final String propertyName,
final Object oldValue, final Object newValue)
throws PropertyVetoException {
vcs.fireVetoableChange(propertyName, oldValue, newValue);
}
/**
* Fire a vetoable property update to any registered listeners. If anyone
* vetos the change, then fire a new event reverting everyone to the old
* value and then rethrow the PropertyVetoException.
* <p>
* No event is fired if old and new are equal and non-null.
*
* @param evt
* The PropertyChangeEvent to be fired.
* @exception PropertyVetoException
* if the recipient wishes the property change to be rolled
* back.
*/
protected void fireVetoableChange(final PropertyChangeEvent evt)
throws PropertyVetoException {
vcs.fireVetoableChange(evt);
}
/**
* Clone.
*
* @return the object
* @exception CloneNotSupportedException
* the clone not supported exception
*/
@Override
public Object clone() throws CloneNotSupportedException {
AbstractBean result = (AbstractBean) super.clone();
result.pcs = new PropertyChangeSupport(result);
result.vcs = new VetoableChangeSupport(result);
return result;
}
}