= FDO RFC 9 - Add new class !FdoLiteralValueCollection  and new method to !FdoLiteralValue =

This page contains a request for comments document (RFC) for the FDO Open Source project.  
More FDO RFCs can be found on the [wiki:FDORfcs RFCs] page.

== Status ==
 
||RFC Template Version||(1.0)|| 
||Submission Date||Aug 10, 2007||
||Last Modified|| Jack Lee [[Timestamp]]||
||Author|| Jack Lee||
||RFC Status||Adopted||
||Implementation Status||Pending||
||Proposed Milestone||3.3.0.0||
||Assigned PSC guide(s)||Greg Boone||
||'''Voting History'''||August 23, 2007||
||+1||Greg, Orest, Jason, Haris, Mateusz, Frank||
||+0|| ||
||-0|| ||
||-1|| ||
 
== Overview ==

The purpose of this RFC is

 * add the !GetLiteralValueType method to !FdoLiteralvalue class

 * add the !FdoLiteralValueCollection class


== Motivation ==

1) Currently, a !FdoDataValue or !FdoGeometryValue can be derived from !FdoLiteralValue. 

The only way to determine the type of object is to use a dynamic cast:

{{{
if (dynamic_cast<FdoDataValue*>(literalValue) != NULL)
{
    // DataValue
    ...
}
else if (dynamic_cast<FdoGeometryValue*>(literalValue) != NULL)
{
    // GeometryValue
    ...
}
}}}

2) The !FdoLiteralValue class exists but the collection of !FdoLiteralValue objects does not exist.


== Proposed Solution ==

1) Add !GetLiteralValueType method to !FdoLiteralValue class 

This methods returns the literal type(data or geometry).

For the unmanaged code:

{{{
enum FdoLiteralValueType
{
    FdoLiteralValueType_Data,

    FdoLiteralValueType_Geometry,

};

class FdoLiteralValue : public FdoValueExpression
{
public:
      FDO_API virtual FdoLiteralValueType GetLiteralValueType() = 0;
};

}}}

The following 

{{{
if (dynamic_cast<FdoDataValue*>(literalValue) != NULL)
{
    // DataValue
    ...
}
else if (dynamic_cast<FdoGeometryValue*>(literalValue) != NULL)
{
    // GeometryValue
    ...
}
}}}

can be changed to :

{{{
if (literalValue->GetLiteralValueType() == FdoLiteralValueType_Data)
{
   // DataValue
   ...
}
else if (literalValue->GetLiteralValueType() == FdoLiteralValueType_Geometry)
{
   // GeometryValue
   ...
}
}}}

For the managed code:

{{{
public __value enum LiteralValueType
{
      LiteralValueType_Data = FdoLiteralValueType_Data,

      LiteralValueType_Geometry = FdoLiteralValueType_Geometry

};

public __gc class LiteralValue : public NAMESPACE_OSGEO_FDO_EXPRESSION::ValueExpression
{
public:
    __property NAMESPACE_OSGEO_FDO_EXPRESSION::LiteralValueType get_LiteralValueType();

public private:
      inline FdoLiteralValue* GetImpObj();
};
}}}

2) Add the !FdoLiteralValueCollection class


For the unmanaged code:
{{{
class FdoLiteralValueCollection : public FdoCollection<FdoLiteralValue, FdoExpressionException>
{
protected:
    FdoLiteralValueCollection() : FdoCollection<FdoLiteralValue, FdoExpressionException>()
    {
    }

    virtual ~FdoLiteralValueCollection()
    {
    }

    virtual void Dispose()
    {
        delete this;
    }

public:
    /// \brief
    /// Constructs a default instance of an FdoLiteralValueCollection.
    /// 
    /// \return
    /// Returns FdoDataValueCollection
    /// 
    FDO_API static FdoLiteralValueCollection* Create();
};
}}}

For the managed code:

{{{
public __sealed __gc class LiteralValueCollection : public NAMESPACE_OSGEO_RUNTIME::Disposable, public System::Collections::IList
{
/// \cond DOXYGEN-IGNORE
public private:
      inline FdoLiteralValueCollection* GetImpObj();

public:
    /// \brief
    /// The defaut constructor for the object
    /// 
      LiteralValueCollection();

    /// \brief
    /// Constructs a LiteralValueCollection object based on an unmanaged instance of the object
    /// 
    /// \param unmanaged 
    /// Input A Pointer to the unmanaged object.
    /// 
    /// \param autoDelete 
    /// Input Indicates if the constructed object should be automatically deleted 
    /// once it no longer referenced.
    /// 
      LiteralValueCollection(System::IntPtr unmanaged, System::Boolean autoDelete);

    /// \brief
    /// Gets the count of items in collection.
    /// 
    /// \return
    /// Returns the number of items in the collection.
    /// 
      __property System::Int32 get_Count(System::Void);

    /// \brief
    /// Gets an enumerator that can iterate through a collection.
    /// 
    /// \return
    /// Returns an enumerator on the dictionary.
    /// 
      __sealed System::Collections::IEnumerator* GetEnumerator(System::Void);

    /// \brief
    /// Removes the index-th ArgumentDefinition from this collection.
    /// 
    /// \param index 
    /// Input index of the element to remove.
    /// 
      System::Void RemoveAt(System::Int32 index);

    /// \brief
    /// Removes all elements from the collection.
    /// 
      System::Void  Clear();

    /// \brief
    /// Adds a ArgumentDefinition object into the collection.
    /// 
    /// \param value 
    /// Input the ArgumentDefinition object to add.
    /// 
    /// \return
    /// Returns the position into which the new element was inserted.
    /// 
      System::Int32 Add(LiteralValue* value);

    /// \brief
    /// Determines the index of a specific ArgumentDefinition object.
    /// 
    /// \param value 
    /// Input the ArgumentDefinition object to locate in the collection.
    /// 
    /// \return
    /// The index of value if found in the collection; otherwise, -1.
    /// 
      System::Int32 IndexOf(NAMESPACE_OSGEO_FDO_EXPRESSION::LiteralValue* value);

    /// \brief
    /// Inserts a ArgumentDefinition object into the collection at the specified position.
    /// 
    /// \param index 
    /// Input the zero-based index at which value should be inserted.
    /// \param value 
    /// Input the ArgumentDefinition object to insert.
    /// 
      System::Void Insert(System::Int32 index, NAMESPACE_OSGEO_FDO_EXPRESSION::LiteralValue* value);

    /// \brief
    /// Removes the first occurrence of a specific ArgumentDefinition object.
    /// 
    /// \param value 
    /// Input the ArgumentDefinition object to remove from the collection.
    /// 
      System::Void Remove(NAMESPACE_OSGEO_FDO_EXPRESSION::LiteralValue* value);

    /// \brief
    /// Determines whether the collection contains a specific ArgumentDefinition object.
    /// 
    /// \param value 
    /// Input The ArgumentDefinition object to search in the collection.
    /// 
    /// \return
    /// Returns true if the value is found in the collection; otherwise, false.
    /// 
      System::Boolean Contains(NAMESPACE_OSGEO_FDO_EXPRESSION::LiteralValue* value);

    /// \brief
    /// Copies the elements of the collection to an array.
    /// 
    /// \param array 
    /// Output the one-dimensional Array that is the destination of the elements copied from this collection.
    ///
    /// \param startAt 
    /// Input an integer that represents the index in array at which copying begins.
    /// 
      System::Void CopyTo(NAMESPACE_OSGEO_FDO_EXPRESSION::LiteralValue* array[],System::Int32 startAt);

    /// \brief
    /// Gets the item in the collection at the specified index. 
    /// 
    /// \param index 
    /// The index of the item in the collection. The index is 0 based.
    /// 
    /// \return
    /// Returns an instance of a the collected item.
    /// Throws an instance of Exception if the index is out of range or an error occurs.
    /// 
      __property NAMESPACE_OSGEO_FDO_EXPRESSION::LiteralValue* get_RealTypeItem(System::Int32 index);

    /// \brief
    /// Sets the value of the item at the specified index
    /// 
    /// \param index 
    /// Input index of the item to set.
    /// 
    /// \param value 
    /// Input the value of the item
    /// 
      __property System::Void  set_RealTypeItem(System::Int32 index, NAMESPACE_OSGEO_FDO_EXPRESSION::LiteralValue* value);

    /// \brief
    /// Gets an item in the collection.
    /// 
    /// \param index 
    /// Input index of the item to retrieve.
    /// 
    /// \return
    /// Returns the item at the specified index
    /// 
      __property NAMESPACE_OSGEO_FDO_EXPRESSION::LiteralValue* get_Item(System::Int32 index);

    /// \brief
    /// Sets the value of the item at the specified index
    /// 
    /// \param index 
    /// Input index of the item to set.
    /// 
    /// \param value 
    /// Input the value of the item
    /// 
      __property System::Void  set_Item(System::Int32 index, NAMESPACE_OSGEO_FDO_EXPRESSION::LiteralValue* value);

/// \cond DOXYGEN-IGNORE
/// \endcond
};
}}}


== Implications ==

This change will not cause any functional or performance side effects.

== Test Plan ==

Existing unit tests will be expanded to test the proposed enhancements defined above. 

== Funding/Resources ==

Autodesk to provide resources / funding to update the FDO API.