001/*
002 * Value.java January 2007
003 *
004 * Copyright (C) 2007, Niall Gallagher <niallg@users.sf.net>
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
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,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
015 * implied. See the License for the specific language governing 
016 * permissions and limitations under the License.
017 */
018
019package org.simpleframework.xml.strategy;
020
021/**
022 * The <code>Value</code> object describes a type that is represented 
023 * by an XML element. This enables a <code>Strategy</code> to define
024 * not only the type an element represents, but also defines if that
025 * type needs to be created. This allows arrays as well as standard
026 * object types to be described. When instantiated the instance should
027 * be set on the value object for use by the strategy to detect cycles.
028 * 
029 * @author Niall Gallagher
030 * 
031 * @see org.simpleframework.xml.strategy.Strategy
032 */
033public interface Value {
034
035   /**
036    * This method is used to acquire an instance of the type that
037    * is defined by this object. If the value has not been set
038    * then this method will return null if this is not a reference.
039    * 
040    * @return an instance of the type this object represents
041    */
042   Object getValue();
043   
044   /**
045    * This method is used set the value within this object. Once
046    * this is set then the <code>getValue</code> method will return
047    * the object that has been provided for consistency. 
048    * 
049    * @param value this is the value to insert as the type
050    */
051   void setValue(Object value);
052   
053   /**
054    * This is the type of the object instance this represents. The
055    * type returned by this is used to instantiate an object which
056    * will be set on this value and the internal graph maintained.
057    * 
058    * @return the type of the object that must be instantiated
059    */
060   Class getType();
061   
062   /**
063    * This returns the length of the array that is to be allocated.
064    * If this value does not represent an array then this should
065    * return zero to indicate that it is not an array object.
066    * 
067    * @return this returns the number of elements for the array
068    */
069   int getLength();
070   
071   /**
072    * This will return true if the object represents a reference.
073    * A reference will provide a valid instance when this objects 
074    * getter is invoked. A valid instance can be a null.
075    * 
076    * @return this returns true if this represents a reference
077    */
078   boolean isReference();
079}