com.squeakysand.commons.valueobjects.MutableValueObject Maven / Gradle / Ivy
Show all versions of squeakysand-commons Show documentation
/*
* Copyright 2010-2012 Craig S. Dickson (http://craigsdickson.com)
*
* 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.squeakysand.commons.valueobjects;
import java.util.Date;
/**
* Represents the Value Object pattern for those entity types that can change over time. For example, information
* related to a user's profile may change over time - the user may change their password or update their preferences. A
* VO designed to represent a user needs to provide information about those changes and also the ability to participate
* in optimistic locking and updating at the database level.
*/
public interface MutableValueObject extends ValueObject {
/**
* Accessor for the createdTimeStamp property. The createdTimeStamp property represents the time at which the entity
* represented by this VO was first persisted (created).
*
* A setter method is not provided for the timeStamp property in this interface as it should be immutable after
* construction. However implementations of this interface may choose to provide a setter method for Serialization
* purposes.
*
* @return the current value of the timeStamp property, may be null if the entity represented by this
* value object has not been persisted.
*/
Date getCreatedTimeStamp();
/**
* Accessor for the modifiedTimeStamp property. The modifiedTimeStamp property represents the time at which this VO
* was last persisted (updated). This value will be the same as the one returned by the
* {@link #getCreatedTimeStamp()} method if this object has never been updated.
*
* A setter method is not provided for the modifiedTimeStamp property in this interface as it should be immutable
* after construction. However implementations of this interface may choose to provide a setter method for
* Serialization purposes.
*
* @return the current value of the modifiedTimeStamp property, may be null if the entity represented
* by this value object has not been persisted.
*/
Date getModifiedTimeStamp();
/**
* Indicates if the value object has had changes applied to it that may need to be persisted to the database.
* At a minimum, this method must return true if there have definitely been changes made
* to the value object that need to be persisted. It can also return true if there may have been
* changes made that need to be persisted (see below).
*
* It is up to the implementor as to how sophisticated this method is. It could simply return true
* if any of the property mutator methods of the value object have been called at all. Or it could actually keep
* track of whether the content of the value object has actually been modified by those calls to the property
* mutator methods. For example, a property has a null value originally, then a call to its mutator
* method sets the value of the property to null again - this may or may not make the value object
* dirty depending on the implementation of this method.
*
* The role of this method is to indicate, with reasonable confidence, that there have been changes made to the
* value object that need to be persisted. The more reliably this method indicates this, the more efficient the
* persistence system will be. However, this will require a trade-off against the speed and size of the value object
* as it is likely that for this method to definitively indicate whether changes that need to be persisted have been
* made, it will need additional member variables and logic to be carried by the value object.
*
* @return true if changes have been made to the value object that may need to be persisted and
* false otherwise.
*/
boolean isDirty();
}