/*
* Copyright 2000-2016 Vaadin Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.vaadin.v7.data;
import com.vaadin.data.Binder;
import com.vaadin.data.HasValue;
import com.vaadin.data.ValueProvider;
import com.vaadin.server.Setter;
import java.io.Serializable;
/**
* <p>
* The <code>Property</code> is a simple data object that contains one typed
* value. This interface contains methods to inspect and modify the stored value
* and its type, and the object's read-only state.
* </p>
*
* <p>
* The <code>Property</code> also defines the events
* <code>ReadOnlyStatusChangeEvent</code> and <code>ValueChangeEvent</code>, and
* the associated <code>listener</code> and <code>notifier</code> interfaces.
* </p>
*
* <p>
* The <code>Property.Viewer</code> interface should be used to attach the
* Property to an external data source. This way the value in the data source
* can be inspected using the <code>Property</code> interface.
* </p>
*
* <p>
* The <code>Property.editor</code> interface should be implemented if the value
* needs to be changed through the implementing class.
* </p>
*
* @param <T>
* type of values of the property
*
* @author Vaadin Ltd
* @deprecated As of 8.0, replaced by {@link HasValue}, {@link ValueProvider}, {@link Setter}, see {@link Binder}
* @since 3.0
*/
@Deprecated
public interface Property<T> extends Serializable {
/**
* Gets the value stored in the Property. The returned object is compatible
* with the class returned by getType().
*
* @return the value stored in the Property
*/
public T getValue();
/**
* Sets the value of the Property.
* <p>
* Implementing this functionality is optional. If the functionality is
* missing, one should declare the Property to be in read-only mode and
* throw <code>Property.ReadOnlyException</code> in this function.
* </p>
*
* Note : Since Vaadin 7.0, setting the value of a non-String property as a
* String is no longer supported.
*
* @param newValue
* New value of the Property. This should be assignable to the
* type returned by getType
*
* @throws Property.ReadOnlyException
* if the object is in read-only mode
*/
public void setValue(T newValue) throws Property.ReadOnlyException;
/**
* Returns the type of the Property. The methods <code>getValue</code> and
* <code>setValue</code> must be compatible with this type: one must be able
* to safely cast the value returned from <code>getValue</code> to the given
* type and pass any variable assignable to this type as an argument to
* <code>setValue</code>.
*
* @return type of the Property
*/
public Class<? extends T> getType();
/**
* Tests if the Property is in read-only mode. In read-only mode calls to
* the method <code>setValue</code> will throw
* <code>ReadOnlyException</code> and will not modify the value of the
* Property.
*
* @return <code>true</code> if the Property is in read-only mode,
* <code>false</code> if it's not
*/
public boolean isReadOnly();
/**
* Sets the Property's read-only mode to the specified status.
*
* This functionality is optional, but all properties must implement the
* <code>isReadOnly</code> mode query correctly.
*
* @param newStatus
* new read-only status of the Property
*/
public void setReadOnly(boolean newStatus);
/**
* A Property that is capable of handle a transaction that can end in commit
* or rollback.
*
* Note that this does not refer to e.g. database transactions but rather
* two-phase commit that allows resetting old field values (in e.g. a
* FieldGroup) if the commit of one of the properties fails after other
* properties have already been committed.
*
* @param <T>
* The type of the property
* @author Vaadin Ltd
* @since 7.0
*/
@Deprecated
public interface Transactional<T> extends Property<T> {
/**
* Starts a transaction.
*
* <p>
* If the value is set during a transaction the value must not replace
* the original value until {@link #commit()} is called. Still,
* {@link #getValue()} must return the current value set in the
* transaction. Calling {@link #rollback()} while in a transaction must
* rollback the value to what it was before the transaction started.
* </p>
* <p>
* {@link ValueChangeEvent}s must not be emitted for internal value
* changes during a transaction. If the value changes as a result of
* {@link #commit()}, a {@link ValueChangeEvent} should be emitted.
* </p>
*/
public void startTransaction();
/**
* Commits and ends the transaction that is in progress.
* <p>
* If the value is changed as a result of this operation, a
* {@link ValueChangeEvent} is emitted if such are supported.
* <p>
* This method has no effect if there is no transaction is in progress.
* <p>
* This method must never throw an exception.
*/
public void commit();
/**
* Aborts and rolls back the transaction that is in progress.
* <p>
* The value is reset to the value before the transaction started. No
* {@link ValueChangeEvent} is emitted as a result of this.
* <p>
* This method has no effect if there is no transaction is in progress.
* <p>
* This method must never throw an exception.
*/
public void rollback();
}
/**
* <code>Exception</code> object that signals that a requested Property
* modification failed because it's in read-only mode.
*
* @author Vaadin Ltd.
* @since 3.0
*/
@SuppressWarnings("serial")
@Deprecated
public class ReadOnlyException extends RuntimeException {
/**
* Constructs a new <code>ReadOnlyException</code> without a detail
* message.
*/
public ReadOnlyException() {
}
/**
* Constructs a new <code>ReadOnlyException</code> with the specified
* detail message.
*
* @param msg
* the detail message
*/
public ReadOnlyException(String msg) {
super(msg);
}
}
/**
* Interface implemented by the viewer classes capable of using a Property
* as a data source.
*
* @author Vaadin Ltd.
* @since 3.0
*/
@Deprecated
public interface Viewer extends Serializable {
/**
* Sets the Property that serves as the data source of the viewer.
*
* @param newDataSource
* the new data source Property
*/
public void setPropertyDataSource(Property newDataSource);
/**
* Gets the Property serving as the data source of the viewer.
*
* @return the Property serving as the viewers data source
*/
public Property getPropertyDataSource();
}
/**
* Interface implemented by the editor classes capable of editing the
* Property.
* <p>
* Implementing this interface means that the Property serving as the data
* source of the editor can be modified through the editor. It does not
* restrict the editor from editing the Property internally, though if the
* Property is in a read-only mode, attempts to modify it will result in the
* <code>ReadOnlyException</code> being thrown.
* </p>
*
* @author Vaadin Ltd.
* @since 3.0
*/
@Deprecated
public interface Editor extends Property.Viewer, Serializable {
}
/* Value change event */
/**
* An <code>Event</code> object specifying the Property whose value has been
* changed.
*
* @author Vaadin Ltd.
* @since 3.0
*/
@Deprecated
public interface ValueChangeEvent extends Serializable {
/**
* Retrieves the Property that has been modified.
*
* @return source Property of the event
*/
public Property getProperty();
}
/**
* The <code>listener</code> interface for receiving
* <code>ValueChangeEvent</code> objects.
*
* @author Vaadin Ltd.
* @since 3.0
*/
@Deprecated
public interface ValueChangeListener extends Serializable {
/**
* Notifies this listener that the Property's value has changed.
*
* @param event
* value change event object
*/
public void valueChange(Property.ValueChangeEvent event);
}
/**
* The interface for adding and removing <code>ValueChangeEvent</code>
* listeners. If a Property wishes to allow other objects to receive
* <code>ValueChangeEvent</code> generated by it, it must implement this
* interface.
* <p>
* Note : The general Java convention is not to explicitly declare that a
* class generates events, but to directly define the
* <code>addListener</code> and <code>removeListener</code> methods. That
* way the caller of these methods has no real way of finding out if the
* class really will send the events, or if it just defines the methods to
* be able to implement an interface.
* </p>
*
* @author Vaadin Ltd.
* @since 3.0
*/
@Deprecated
public interface ValueChangeNotifier extends Serializable {
/**
* Registers a new value change listener for this Property.
*
* @param listener
* the new Listener to be registered
*/
public void addValueChangeListener(
Property.ValueChangeListener listener);
/**
* @deprecated As of 7.0, replaced by
* {@link #addValueChangeListener(ValueChangeListener)}
**/
@Deprecated
public void addListener(Property.ValueChangeListener listener);
/**
* Removes a previously registered value change listener.
*
* @param listener
* listener to be removed
*/
public void removeValueChangeListener(
Property.ValueChangeListener listener);
/**
* @deprecated As of 7.0, replaced by
* {@link #removeValueChangeListener(ValueChangeListener)}
**/
@Deprecated
public void removeListener(Property.ValueChangeListener listener);
}
/* ReadOnly Status change event */
/**
* An <code>Event</code> object specifying the Property whose read-only
* status has been changed.
*
* @author Vaadin Ltd.
* @since 3.0
*/
@Deprecated
public interface ReadOnlyStatusChangeEvent extends Serializable {
/**
* Property whose read-only state has changed.
*
* @return source Property of the event.
*/
public Property getProperty();
}
/**
* The listener interface for receiving
* <code>ReadOnlyStatusChangeEvent</code> objects.
*
* @author Vaadin Ltd.
* @since 3.0
*/
@Deprecated
public interface ReadOnlyStatusChangeListener extends Serializable {
/**
* Notifies this listener that a Property's read-only status has
* changed.
*
* @param event
* Read-only status change event object
*/
public void readOnlyStatusChange(
Property.ReadOnlyStatusChangeEvent event);
}
/**
* The interface for adding and removing
* <code>ReadOnlyStatusChangeEvent</code> listeners. If a Property wishes to
* allow other objects to receive <code>ReadOnlyStatusChangeEvent</code>
* generated by it, it must implement this interface.
* <p>
* Note : The general Java convention is not to explicitly declare that a
* class generates events, but to directly define the
* <code>addListener</code> and <code>removeListener</code> methods. That
* way the caller of these methods has no real way of finding out if the
* class really will send the events, or if it just defines the methods to
* be able to implement an interface.
* </p>
*
* @author Vaadin Ltd.
* @since 3.0
*/
@Deprecated
public interface ReadOnlyStatusChangeNotifier extends Serializable {
/**
* Registers a new read-only status change listener for this Property.
*
* @param listener
* the new Listener to be registered
*/
public void addReadOnlyStatusChangeListener(
Property.ReadOnlyStatusChangeListener listener);
/**
* @deprecated As of 7.0, replaced by
* {@link #addReadOnlyStatusChangeListener(ReadOnlyStatusChangeListener)}
**/
@Deprecated
public void addListener(Property.ReadOnlyStatusChangeListener listener);
/**
* Removes a previously registered read-only status change listener.
*
* @param listener
* listener to be removed
*/
public void removeReadOnlyStatusChangeListener(
Property.ReadOnlyStatusChangeListener listener);
/**
* @deprecated As of 7.0, replaced by
* {@link #removeReadOnlyStatusChangeListener(ReadOnlyStatusChangeListener)}
**/
@Deprecated
public void removeListener(
Property.ReadOnlyStatusChangeListener listener);
}
}