xmog_base Struct Reference

The baseclass for all proxy types in the framework. More...

#include <xmog_base.h>

Inheritance diagram for xmog_base:

[legend]Collaboration diagram for xmog_base:


Public Types
enum	flags { STAND_ALONE = 1, ARRAY_ELEMENT = 2, DYNAMIC = 4, DELEGATE = 8, LOCAL = 16, WEAK_GLOBAL = 32, GLOBAL = 64, REMOTE = 128, CACHING = 256, CACHE_INVALID = 512, CACHE_DIRTY = 1024, CACHE_LAZY_WRITE = 2048, OWNS_DELEGATE = 4096, STRING_DIRTY = 8192, STRING_PTR = 16384, STRING_WPTR = 32768, INDIRECT = 65536, NONVIRT = 131072, SUPPRESS_LOGGING = 262144, CATEGORY = 15, TYPE = 240, CACHE = 3840 }
	The possible flag values. More...
Public Member Functions
	xmog_base ()
	The default contructor.
	xmog_base (xmog_java_array *_ref, jint _index)
	The constructor for Java array elements.
	xmog_base (xmog_java_ref _ref, xmog_java_dynamic _dynamic, xmog_flags _flags)
	The constructor for indirect and user-defined types.
	xmog_base (xmog_java_class _clazz, xmog_java_dynamic _dynamic, xmog_flags _flags)
	The constructor for indirect and user-defined types.
XMOG_EXPLICIT	xmog_base (xmog_base *_delegate, bool _owns_delegate=true)
	The constructor for delegating objects.
	xmog_base (jobject _local, xmog_flags _flags)
	The constructor for direct types.
virtual	~xmog_base ()
	The virtual destructor.
virtual void	copy_jobject_ (xmog_base _rhs, xmog_localenv env=NULL)
	Sets this instance's object reference to a duplicate of the given object's reference.
virtual jobject	get_owning_jobject_ (xmog_localenv *env=NULL)
	Returns this instance's owner.
virtual jobject	get_jobject_ (xmog_localenv *env=NULL) const
	Returns this instance's object reference.
virtual jobject	get_released_local_jobject_ (xmog_localenv *env=NULL) const
	Returns this instance's object reference as a local reference and removes it from this instance's ownership.
virtual bool	is_null_ (xmog_localenv *env=NULL) const
	Tests the instance for `null`.
virtual bool	is_same_ (const xmog_base &_rhs, xmog_localenv *env=NULL) const
	Tests whether this instance references the same instance as the other instance.
virtual jobject	duplicate_jobject_ (xmog_localenv *env=NULL) const
	Returns a duplicate of this instance's object reference.
virtual void	set_jobject_ (xmog_base _rhs, xmog_localenv env=NULL)
	Sets this instance's object reference to the given object's reference.
virtual void	transfer_jobject_ (xmog_base _rhs, xmog_localenv env=NULL)
	Sets this instance's object reference to the given object's reference and removes ownership from the other object.
virtual xmog_base *	xmog_to_ (xmog_flags flags, xmog_localenv *env=NULL)
	Converts a reference from one reference type to another.
virtual xmog_base *	xmog_fill_with_standalone_for_ (xmog_base _rhs, xmog_localenv env=NULL)
	Populates the object with a stand-alone reference based on another object.
virtual xmog_java_class *	xmog_get_java_peer (xmog_localenv *env=NULL)
	Returns `NULL` if the type does not have a Java peer type, a pointer to the type's xmog_java_class otherwise.
virtual int	xmog_create_java_peer (xmog_java_class clazz, xmog_localenv env=NULL, xmog_flags flags=xmog_base::GLOBAL)
	Creates a Java peer instance for this type.
virtual int	xmog_to_java_peer (xmog_localenv *env=NULL)
	Sets the native instance's state into the Java peer instance.
virtual void	xmog_lazy_write (xmog_localenv *env=NULL)
	Performs a lazy write operation on the instance.
virtual void	xmog_invalidate (xmog_localenv *env=NULL)
	Invalidates any cached values in the instance.
void	release_standalone (xmog_localenv *env=NULL)
	Releases the internally maintained object if the instance is a stand-alone (direct) instance and not an indirect instance.
void	release_delegate ()
	Releases the internally maintained delegate.
Public Attributes
XMOG_JOBJECT_HOLDER	owner_
	The owner or identity of the object.
xmog_flags	flags_
	The flags governing the type and other housekeeping information.
xmog_java_dynamic *	dynamic_
	A pointer to an object that can access indirectly specified information.
jint	index_
	The index of an array element.

Detailed Description

The baseclass for all proxy types in the framework.

This class acts as baseclass for all proxy types in the framework. As such, it is fairly technology-unspecific and requires technology-specific extensions in its subtypes. It is important that no more than one instance of this type is aggregated into derived types, so either this type or a derived type that is a basetype for all other derived types needs to be inherited virtually.

Member Enumeration Documentation

enum xmog_base::flags

The possible flag values.
These flags govern various parts of the proxy's behavior. They are organized into a couple of categories:

category of proxy. This can be a STAND_ALONE, ARRAY_ELEMENT, DYNAMIC, or DELEGATE

reference type of proxy. This can be a LOCAL, WEAK_GLOBAL, GLOBAL, or REMOTE

cache control of proxy. This can be a CACHING, CACHE_INVALID, or CACHE_DIRTY

Constructor & Destructor Documentation

xmog_base::xmog_base ( )

The default contructor.
The default constructor creates an empty proxy instance.

xmog_base::xmog_base ( xmog_java_array * _ref,

jint _index

)

The constructor for Java array elements.
An array element is really a special case of a dynamic proxy instance and could theoretically be handled using an xmog_java_dynamic specialization for array elements. The downside of this approach would be that each proxy array element needs to maintain an index and an xmog_java_dynamic instance that has been dynamically allocated, causing wasted memory. By having a special case for array elements, we can store the index in the same space that the xmog_java_dynamic pointer would otherwise occupy.
Parameters:

_ref pointer to array proxy.

_index index into the array.

xmog_base::xmog_base ( xmog_java_ref * _ref,

xmog_java_dynamic * _dynamic,

xmog_flags _flags

)

The constructor for indirect and user-defined types.
Indirect types operate on a reference using some unique algorithm. Java fields and Java methods are specializations of the xmog_java_dynamic type. A Java proxy field instance of type xmog_java_field for example may use JNI or a remoting protocol to get/set the value of a Java field. A Java proxy method instance of type xmog_java_method might use JNI or a remoting protocol to call the proper method.

Parameters:

_ref pointer to a proxy element.

_dynamic pointer to the instance that is going to be used to dynamically access the proxy element's value.

_flags bit flags that may be used during the processing of the access, for example to remember the type of JNI reference that is set into the proxy instance.

xmog_base::xmog_base ( xmog_java_class * _clazz,

xmog_java_dynamic * _dynamic,

xmog_flags _flags

)

The constructor for indirect and user-defined types.
Indirect types operate on a reference using some unique algorithm. Java fields and Java methods are specializations of the xmog_java_dynamic type. A Java proxy field instance of type xmog_java_field for example may use JNI or a remoting protocol to get/set the value of a Java field. A Java proxy method instance of type xmog_java_method might use JNI or a remoting protocol to call the proper method.

Parameters:

_clazz pointer to a proxy element.

_dynamic pointer to the instance that is going to be used to dynamically access the proxy element's value.

_flags bit flags that may be used during the processing of the access, for example to remember the type of JNI reference that is set into the proxy instance.

XMOG_EXPLICIT xmog_base::xmog_base ( xmog_base * _delegate,

bool _owns_delegate = true

)

The constructor for delegating objects.
A delegating instance is a special case of an indirect type that does not need an algorithm, just a reference. This type of proxy can be very useful when we have a heap allocated instance that we wish to use within the context of our framework. In the generated proxy types, all method arguments are references and all return values are object instances on the stack, so a dynamically, heap-allocated instance can generally not be used as a method result. This particularly prohibits the use of factory methods that create a most derived instance from inside the framework. The delegate "flavor" of proxy instance allows this usage.

Parameters:

_delegate an instance that is of compatible type to the outer instance and can therefore be delegated to for every request being made of this instance.

_owns_delegate true if the proxy instance owns the delgate, false otherwise. The proxy's destructor will call delete() on the delegate if the value is true. The default value is true.

xmog_base::xmog_base ( jobject _local,

xmog_flags _flags

)

The constructor for direct types.
This object directly references a Java peer object. This constructor is useful when we want to set an externally created object reference into a proxy instance.

Parameters:

_local the Java object reference.

_flags the bit flags describing the reference.

Member Function Documentation

virtual void xmog_base::copy_jobject_ ( xmog_base * _rhs,

xmog_localenv * env = NULL

) [virtual]

Sets this instance's object reference to a duplicate of the given object's reference.
This method is only useful for reference-type proxies but not for primitive value proxies.

Parameters:

_rhs the other proxy instance from which we're getting the value.

env an optional local call environment. NULL is a legal value.

virtual jobject xmog_base::duplicate_jobject_ ( xmog_localenv * env = NULL ) const [virtual]

Returns a duplicate of this instance's object reference.
This method is only useful for reference-type proxies but not for primitive value proxies.

Parameters:

env an optional local call environment. NULL is a legal value.

virtual jobject xmog_base::get_jobject_ ( xmog_localenv * env = NULL ) const [virtual]

Returns this instance's object reference.
This method is only useful for reference-type proxies but not for primitive value proxies.

Parameters:

env an optional local call environment. NULL is a legal value.

Reimplemented in xmog_java_ref.

virtual jobject xmog_base::get_owning_jobject_ ( xmog_localenv * env = NULL ) [virtual]

Returns this instance's owner.
This method is only useful for indirect proxies that derive their value from an owning object and a way to ask the owning object for a value.

Parameters:

env an optional local call environment. NULL is a legal value.

virtual jobject xmog_base::get_released_local_jobject_ ( xmog_localenv * env = NULL ) const [virtual]

Returns this instance's object reference as a local reference and removes it from this instance's ownership.
This method is used by native method implementations.

Parameters:

env an optional local call environment. NULL is a legal value.

void xmog_base::release_standalone ( xmog_localenv * env = NULL )

Releases the internally maintained object if the instance is a stand-alone (direct) instance and not an indirect instance.

Parameters:

env an optional local call environment. NULL is a legal value.

virtual void xmog_base::set_jobject_ ( xmog_base * _rhs,

xmog_localenv * env = NULL

) [virtual]

Sets this instance's object reference to the given object's reference.
This method is only useful for reference-type proxies but not for primitive value proxies.

Parameters:

_rhs the other proxy instance from which we're getting the value.

env an optional local call environment. NULL is a legal value.

virtual void xmog_base::transfer_jobject_ ( xmog_base * _rhs,

xmog_localenv * env = NULL

) [virtual]

Sets this instance's object reference to the given object's reference and removes ownership from the other object.
This method is only useful for reference-type proxies but not for primitive value proxies.

Parameters:

_rhs the other proxy instance from which we're transfering the value.

env an optional local call environment. NULL is a legal value.

virtual xmog_base* xmog_base::xmog_fill_with_standalone_for_ ( xmog_base * _rhs,

xmog_localenv * env = NULL

) [virtual]

Populates the object with a stand-alone reference based on another object.
The purpose of this method is to provide an easy way to get an object reference that has the proper ownership flags, indpendent of its origin. If it was based on a stand-alone object, it simply receives the stand-alone object's reference without ownership. If it is based on an indirect object, it receives the dereferenced object's reference with ownership.

Parameters:

_rhs the other proxy object.

env an optional local call environment. NULL is a legal value.

virtual void xmog_base::xmog_invalidate ( xmog_localenv * env = NULL ) [virtual]

Invalidates any cached values in the instance.

Parameters:

env an optional local call environment. NULL is a legal value.

Reimplemented in xmog_java_array.

virtual void xmog_base::xmog_lazy_write ( xmog_localenv * env = NULL ) [virtual]

Performs a lazy write operation on the instance.
If an instance uses lazy write caching, for example because access to the instance via C++ is frequent and very time-sensitive, whereas access to the instance from the peer language is infrequent and not time-sensitive, this method can be called to synchronize the changes that might have been made on the C++ side to the peer side.
Each proxy type needs to provide a concrete implementation of this method that checks each field for required write-through operations and performs them if necessary.

Parameters:

env an optional local call environment. NULL is a legal value.

virtual xmog_base* xmog_base::xmog_to_ ( xmog_flags flags,

xmog_localenv * env = NULL

) [virtual]

Converts a reference from one reference type to another.

Parameters:

flags the flags containing the reference type to which we want to convert the instance.

env an optional local call environment. NULL is a legal value.

Member Data Documentation

XMOG_JOBJECT_HOLDER xmog_base::owner_

The owner or identity of the object.
An object can be a stand-alone object (local_ or remote_ reference) or it can be owned by another object. In the latter case, an xmog_dynamic instance will contain the algorithm to access the underlying object.
This code will work as long as a pointer can be maintained in this type. This might require a little bit of tuning on 64bit systems.

The documentation for this struct was generated from the following file:

xmog_base.h

Generated on Wed May 31 14:01:21 2006 for Shared Codemesh Runtime Library API Reference by

1.4.1

xmog_base Struct Reference

Public Types

Public Member Functions

Public Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation