Checking To See If A Struct Is Of Type Ordered / Linked In Lucee CFML 5.3.6.61
One of the really excited features of ColdFusion is that it can create linked / ordered Structs. These are Structs (objects, hashes, maps) in which the key-iteration order matches the order in which the keys were originally defined. As I discussed last year, ordered Structs are perfect for MongoDB interactions, where the order of the key-iteration determines the underlying database interaction behaviors. The other day, I was building a Gateway wrapper to a MongoDB database; and, due to the importance of the Struct implementation, I wanted to see if I could, perhaps, require the MongoDB query documents to be Ordered / Linked Structs. ColdFusion doesn't provide decision functions around Struct type; so, I wanted to see how I might determine if a Struct is of type Ordered / Linked in Lucee CFML 5.3.6.61.
CAUTION: I am using undocumented, implementation details here - but, I am encapsulating them within Function boundaries.
To figure out a plan of attack, I started looking around in the Lucee CFML source code for the StructImpl class. I was hoping that each "type" of Struct was actually a different class; and then, maybe, I could just use the isInstanceOf() ColdFusion function. But, it looks like the StructImpl class just wraps a map of a given Type. That said, it does have a .getType() method, which exposes the Type of said underlying map. So, I ended up using the .getType() method to determine what type of Struct I had:
<cfscript>
normal = {};
linked = [:];
weak = structNew( "weak" );
// As a test case, let's try a value that isn't a Struct at all.
none = "hello";
echo( "<strong> Normal : </strong>" );
echo( "#isNormalStruct( normal )# , #isLinkedStruct( normal )# , #isWeakStruct( normal )#" );
echo( "<br />" );
echo( "<strong> Linked : </strong>" );
echo( "#isNormalStruct( linked )# , #isLinkedStruct( linked )# , #isWeakStruct( linked )#" );
echo( "<br />" );
echo( "<strong> Weak : </strong>" );
echo( "#isNormalStruct( weak )# , #isLinkedStruct( weak )# , #isWeakStruct( weak )#" );
echo( "<br />" );
echo( "<strong> None : </strong>" );
echo( "#isNormalStruct( none )# , #isLinkedStruct( none )# , #isWeakStruct( none )#" );
echo( "<br />" );
// ------------------------------------------------------------------------------- //
// ------------------------------------------------------------------------------- //
/**
* I determine if the given value is a "normal" Struct.
*
* @value I am the value being inspected.
*/
public boolean function isNormalStruct( required any value ) {
return(
isStructOfType( value, "TYPE_UNDEFINED" ) ||
isStructOfType( value, "TYPE_REGULAR" )
);
}
/**
* I determine if the given value is a "linked" or "ordered" Struct.
*
* @value I am the value being inspected.
*/
public boolean function isLinkedStruct( required any value ) {
return( isStructOfType( value, "TYPE_LINKED" ) );
}
/**
* I determine if the given value is a "weak" Struct.
*
* @value I am the value being inspected.
*/
public boolean function isWeakStruct( required any value ) {
return( isStructOfType( value, "TYPE_WEAKED" ) );
}
/**
* I determine if the given value is a Struct of the given Type.
*
* @value I am the value being inspected.
* @valueType I am the name of the INTERNAL TYPE being tested.
*/
public boolean function isStructOfType(
required any value,
required string valueType
) {
// Since we're about to dip into the INTERNAL IMPLEMENTATION details of the
// Lucee CFML Struct object, let's try to short-circuit the check to avoid any
// invalid object references.
if (
! isStruct( value ) ||
! isInstanceOf( value, "lucee.runtime.type.StructImpl" )
) {
return( false );
}
// At this point, we know that we're dealing with a "StructImpl" instance. As
// such, we should be able to access its Type, which is an enumerated value.
var StructTypes = createObject( "java", "lucee.runtime.type.Struct" );
switch ( valueType ) {
case "TYPE_UNDEFINED": // -1
case "TYPE_WEAKED": // 0
case "TYPE_LINKED": // 1
case "TYPE_SYNC": // 2
case "TYPE_REGULAR": // 3
case "TYPE_SOFT": // 4
return( value.getType() == StructTypes[ valueType ] );
break;
default:
return( false );
break;
}
}
</cfscript>
As you can see, I am defining three high-level functions:
isNormalStruct( value )isLinkedStruct( value )isWeakStruct( value )
But, each of these just turns around and defers to a low-level method, isStructOfType(), which, in turn, dips into the underlying Java implementation details. The low-level part is the part that might break when Lucee CFML changes its implementation. But, given that it is wrapped up in a Function, it gives us a place to change it later on.
That said, when we run this ColdFusion code, we get the following output:
As you can see, by using our custom User Defined Functions (UDFs), we are able to take a ColdFusion Struct and determine which type it is. I could - theoretically - now take these decision functions and build a MongoDB gateway component that requires linked / ordered Structs to be used to define query document specifications in Lucee CFML 5.3.6.61.
Want to use code from this post? Check out the license.
Reader Comments
I was determining whether an Adobe ColdFusion struct was ordered by examining the canonical Name.
canonicalName = getMetaData(myStruct).getCanonicalName();
For structs, It would return one of the following:
If using a LinkedHashMap, it would return:
@James,
Oh nice, that's good to know for ACF. And actually, when I started this post, I was assuming that Lucee CFML was going to work the same way. But, it turned out that the low-level Struct was actually a property of the "Struct Implementation", so I had to dip down into the
.getType()method. But, nice to see this can be achieved in both runtimes.