com.vinculumtech.carrierwave.image
Class ImageGraph

java.lang.Object
  com.vinculumtech.carrierwave.image.ImageGraph

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

SourcedImageGraph

public class ImageGraph

extends java.lang.Object

implements java.io.Serializable

The ImageGraph class maintains all Image instances associated in a graph.

When two Image instances are associated by calling the setter on the parent with the child as the arguement, one of three things will happen:

• An ImageGraph instance is created to hold both instances. Subsequent addtions to the graph will be added to that ImageGraph.
• If two distinct Image instances belonging to two distinct ImageGraph instances are associated, they will be merged into one ImageGraph instance. That is, the parent Image ImageGraph instance will hold all the images, the child Image ImageGraph will be empty.
• If an ImageGraph instance is marked durable, all Image instances will be added to it, even if it is the child Image has a unique ImageGraphInstance.

The ImageGraph class is simply a namespace with limited referential integrity enforcement.

Version:

$Id: //depot/carrierwave/src/shared/com/vinculumtech/carrierwave/image/ImageGraph.java#9 $

See Also:

ImageHelper, Serialized Form

Constructor Summary

	ImageGraph()
protected	ImageGraph(Image originImage)
protected	ImageGraph(ImageGraph imageGraph) This constructor will assume all the images held by the given ImageGraph instance. Note the given ImageGraph instance will be in an undefined state and should be discarded.

Method Summary

boolean	acceptImage(Image image) Moves the given Image instance from its current ImageGraph to this ImageGraph instance, removeImage is called on the original ImageGraph instance. Reference counts and origin status is preserved. Note that if this ImageGraph instance already contains an Image instance with an equivalent identity (Icon), the old Image instance will not be replaced.
protected void	addImagesFrom(ImageGraph imageGraph)
protected void	addImagesTo(ImageGraph imageGraph)
void	addOriginImage(Image originImage) Makes the given Image instance an origin (possibly one of many). If the given Image instance is owned by another ImageGraph instance, an IllegalArgumentException will be thrown.
protected void	associateImage(Image image) Adds the given Image instance to the current ImageGraph if it is not already a member. It is assumed the given image is intended as a child to an Image existing in this ImageGraph.
protected void	associateImageGraphs(ImageGraph imageGraph) Handles the association between this ImageGraph instance and the given child ImageGraph instance (associated with an Image added via associateImage) It is intended that this method be overidden for special cases.
protected ImageGraph	becomeImageGraph() Intended to be used by subclasses implementing the writeReplace method for serialization support.
void	clear() Clears all images and origins from this ImageGraph instance.
void	clearOriginImages() Sets the number of origin Image instances to zero, and markes thier origin status accordingly.
boolean	containsImage(Icon icon) Tests the local image Map for an Image instance with equivalent identity.
protected void	decrementImage(Image image)
protected void	disassociateImage(Icon icon)
protected void	disassociateImage(Image image) Disassociates the given Image image from the graph. It is assumed the given Image instance has lost a parent child relationship with an Image in this ImageGraph instance. Note that disassociation does not remove the Image instance, but simply decrements its reference count.
java.util.Collection	getIcons() Returns only Icon instances that have an associated Image instance in the graph.
Image	getImage(Icon icon) Returns an Image instance equivalent to the given Icon instance. By default, this method calls getImageLocal.
Image	getImageLocal(Icon icon) Retrieves the Image instance with the given Icon identity from the 'local' image Map. Override getImage to delegate Image retrieval from an additional source.
java.util.Map	getImageMap()
java.util.Collection	getImages()
protected java.util.Map	getImagesPrivate()
Image	getOriginImage()
java.util.List	getOriginImages() Returns a List of all origin Image instances. The result of a 'select' guarantees one origin.
protected java.util.List	getOriginsPrivate()
boolean	hasManyOriginImages() An ImageGraph may have zero or more origin Images.
protected void	incrementImage(Image image)
boolean	isDurable() A durable ImageGraph instance is one that will not release its owned Image instances during a parent child association. By default the parent ImageGraph will assume the instances owned by the child ImageGraph instance.
boolean	isStrict() A strict ImageGraph instance is one that represents the whole graph as represented on the server.
void	makeDurable() Forces this ImageGraph instance to be durable.
void	makeOriginImage(Image originImage) Forces the given Image instance to be the only origin in the graph. It is expected that the given Image instance is already a member of this ImageGraph instance.
void	makeOriginImages(java.util.List originImages) Forces all the Image instances in the given List to be the only origin image instances in the graph. It is expected that all the given Image instances in the List are already in the current ImageGraph instance.
void	makeStrict() Forces this ImageGraph instance to be strict.
Image	putImage(Image image) Places the the given Image instance directly into this ImageGraph instance and returns any Image instance with an equivalent identity (Icon) as the given Image instance. Reference counts are not not incremented.
protected void	reassociateImage(Icon oldIcon, Icon newIcon) Reassociates an Image instance from the oldIcon to the newIcon. This method is used when Icon instances are made soft or have lost thier identity (intentionally).
void	removeImage(Image image) Removes the given Image instance from this ImageGraph instance.
protected void	removeOrigin(Image image)
void	setDurable(boolean durable)
void	setIsStrict(boolean isStrict)
protected java.util.Map	setThisOnAll(java.util.Map images)
int	size()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ImageGraph

public ImageGraph()

ImageGraph

protected ImageGraph(Image originImage)

ImageGraph

protected ImageGraph(ImageGraph imageGraph)

This constructor will assume all the images held by the given ImageGraph instance.
Note the given ImageGraph instance will be in an undefined state and should be discarded.

Parameters:

imageGraph -

Method Detail

getImagesPrivate

protected final java.util.Map getImagesPrivate()

getOriginsPrivate

protected final java.util.List getOriginsPrivate()

isStrict

public boolean isStrict()

A strict ImageGraph instance is one that represents the whole graph as represented on the server. This notifies the graph plan generator to create nodes for null references. Otherwise, a node will not be created and the null on that edge will subsequently be ignored during a 'modify'.
Warning, by setting this value to true, a subsequent modify could truncate (null) any values that are not included in this ImageGraph instance, but are on the server. Thus 'selects' from the server will NOT mark the returned ImageGraph instance as strict.

Returns:

makeStrict

public void makeStrict()

Forces this ImageGraph instance to be strict.

setIsStrict

public void setIsStrict(boolean isStrict)

isDurable

public boolean isDurable()

A durable ImageGraph instance is one that will not release its owned Image instances during a parent child association.
By default the parent ImageGraph will assume the instances owned by the child ImageGraph instance. A durable ImageGraph instance will always assume the Image instances from the competing ImageGraph, unless it is also durable, such cases will result in a RuntimeException.

Returns:

true if this ImageGraph instance is durable.

makeDurable

public void makeDurable()

Forces this ImageGraph instance to be durable.

setDurable

public void setDurable(boolean durable)

getImages

public java.util.Collection getImages()

Returns:

a Collection of all the Image instances in the graph owned by this ImageGraph instance

getIcons

public java.util.Collection getIcons()

Returns only Icon instances that have an associated Image instance in the graph.

Returns:

a Collection of all the Image instances in the graph owned by this ImageGraph instance

getImageMap

public java.util.Map getImageMap()

Returns:

a copy of the internal Map of Image instances

clear

public void clear()

Clears all images and origins from this ImageGraph instance.

size

public int size()

Returns:

the number of Image instances owned by this ImageGraph instance

getImageLocal

public final Image getImageLocal(Icon icon)

Retrieves the Image instance with the given Icon identity from the 'local' image Map.
Override getImage to delegate Image retrieval from an additional source.

Parameters:

icon -

Returns:

null if not found or if the Icon instance is null, otherwise an equivalent Image instance

getImage

public Image getImage(Icon icon)

Returns an Image instance equivalent to the given Icon instance.
By default, this method calls getImageLocal. Override this method to delegate Image retrieval from and additional source.

Parameters:

icon -

Returns:

containsImage

public boolean containsImage(Icon icon)

Tests the local image Map for an Image instance with equivalent identity.

Parameters:

icon -

Returns:

true if this ImageGraph instance owns an Image instance with equivalent identity

getOriginImage

public Image getOriginImage()

Returns:

the first origin Image instance, if any

hasManyOriginImages

public boolean hasManyOriginImages()

An ImageGraph may have zero or more origin Images.

Returns:

true if this ImageGraph has more than one origin Image instance

getOriginImages

public java.util.List getOriginImages()

Returns a List of all origin Image instances.
The result of a 'select' guarantees one origin. Local graph manipulations may reduce the count to zero, via reference count checks.

Returns:

all origin Image instances

clearOriginImages

public void clearOriginImages()

Sets the number of origin Image instances to zero, and markes thier origin status accordingly. Does not remove Image instances from the ImageGraph.

makeOriginImage

public void makeOriginImage(Image originImage)

Forces the given Image instance to be the only origin in the graph.
It is expected that the given Image instance is already a member of this ImageGraph instance.

Parameters:

originImage -

makeOriginImages

public void makeOriginImages(java.util.List originImages)

Forces all the Image instances in the given List to be the only origin image instances in the graph.
It is expected that all the given Image instances in the List are already in the current ImageGraph instance.

Parameters:

originImages -

addOriginImage

public void addOriginImage(Image originImage)

Makes the given Image instance an origin (possibly one of many).
If the given Image instance is owned by another ImageGraph instance, an IllegalArgumentException will be thrown.

Parameters:

originImage -

removeOrigin

protected void removeOrigin(Image image)

acceptImage

public boolean acceptImage(Image image)

Moves the given Image instance from its current ImageGraph to this ImageGraph instance, removeImage is called on the original ImageGraph instance.
Reference counts and origin status is preserved.
Note that if this ImageGraph instance already contains an Image instance with an equivalent identity (Icon), the old Image instance will not be replaced.

Parameters:

image -

Returns:

true if the given Image instance was accepted, false otherwise

putImage

public Image putImage(Image image)

Places the the given Image instance directly into this ImageGraph instance and returns any Image instance with an equivalent identity (Icon) as the given Image instance.
Reference counts are not not incremented. Child Image instances of the given Image instance will not be assumed this ImageGraph instance.
This method is intended for internal tool use.

Parameters:

image -

Returns:

the old Image instance, if exists

removeImage

public void removeImage(Image image)

Removes the given Image instance from this ImageGraph instance. Reference counts are not decremented, but origin status is preserved (but is removed from the collection of origin maintained by this ImageGraph instance.
This method is intended for internal tool use.

Parameters:

image -

associateImage

protected void associateImage(Image image)

Adds the given Image instance to the current ImageGraph if it is not already a member.
It is assumed the given image is intended as a child to an Image existing in this ImageGraph. Thus, the image will have its reference count increased. And it will no longer be considered an origin, if it was one previously.
Note that the child ImageGraph instance (if any) the given Image instance currently belongs to, will have all of its images instances assumed this ImageGraph.
It is intended for this method to be called by subclasses of Image.

Parameters:

image -

associateImageGraphs

protected void associateImageGraphs(ImageGraph imageGraph)

Handles the association between this ImageGraph instance and the given child ImageGraph instance (associated with an Image added via associateImage)
It is intended that this method be overidden for special cases.

Parameters:

imageGraph -

addImagesFrom

protected void addImagesFrom(ImageGraph imageGraph)

addImagesTo

protected void addImagesTo(ImageGraph imageGraph)

reassociateImage

protected void reassociateImage(Icon oldIcon,
                                Icon newIcon)

Reassociates an Image instance from the oldIcon to the newIcon.
This method is used when Icon instances are made soft or have lost thier identity (intentionally).

Parameters:

oldIcon -

newIcon -

disassociateImage

protected void disassociateImage(Image image)

Disassociates the given Image image from the graph.
It is assumed the given Image instance has lost a parent child relationship with an Image in this ImageGraph instance.
Note that disassociation does not remove the Image instance, but simply decrements its reference count. If the reference count becomes zero, the Image instance becomes an origin.
It is intended for this method to be called by subclasses of Image.

Parameters:

image -

disassociateImage

protected void disassociateImage(Icon icon)

incrementImage

protected void incrementImage(Image image)

decrementImage

protected void decrementImage(Image image)

setThisOnAll

protected java.util.Map setThisOnAll(java.util.Map images)

becomeImageGraph

protected ImageGraph becomeImageGraph()

Intended to be used by subclasses implementing the writeReplace method for serialization support. This is useful in the case the ImageGraph subclass is not located in the server classpath.

Returns: