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. More...

	xmog_base (xmog_java_array *_ref, jint _index)
	The constructor for Java array elements. More...

	xmog_base (xmog_java_ref _ref, xmog_java_dynamic _dynamic, xmog_flags _flags)
	The constructor for indirect and user-defined types. More...

	xmog_base (xmog_java_class _clazz, xmog_java_dynamic _dynamic, xmog_flags _flags)
	The constructor for indirect and user-defined types. More...

XMOG_EXPLICIT	xmog_base (xmog_base *_delegate, bool _owns_delegate=true)
	The constructor for delegating objects. More...

	xmog_base (jobject _local, xmog_flags _flags)
	The constructor for direct types. More...

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. More...

virtual jobject	get_owning_jobject_ (xmog_localenv *env=NULL)
	Returns this instance's owner. More...

virtual jobject	get_jobject_ (xmog_localenv *env=NULL) const
	Returns this instance's object reference. More...

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. More...

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. More...

virtual void	set_jobject_ (xmog_base _rhs, xmog_localenv env=NULL)
	Sets this instance's object reference to the given object's reference. More...

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. More...

virtual xmog_base *	xmog_to_ (xmog_flags flags, xmog_localenv *env=NULL)
	Converts a reference from one reference type to another. More...

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. More...

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. More...

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. More...

virtual int	xmog_to_java_peer (xmog_localenv *env=NULL)
	Sets the native instance's state into the Java peer instance. More...

virtual void	xmog_lazy_write (xmog_localenv *env=NULL)
	Performs a lazy write operation on the instance. More...

virtual void	xmog_invalidate (xmog_localenv *env=NULL)
	Invalidates any cached values in the instance. More...

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. More...

void	release_delegate ()
	Releases the internally maintained delegate.

Public Attributes
XMOG_JOBJECT_HOLDER	owner_
	The owner or identity of the object. More...

union {
xmog_java_dynamic * dynamic_
	A pointer to an object that can access indirectly specified information.

jint index_
	The index of an array element.

};
	Data or object that provides assistance in accessing indirectly specified elements. More...

xmog_flags	flags_
	The flags governing the type and other housekeeping information.

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

◆ flags

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() [1/6]

xmog_base::xmog_base ( )

The default contructor.

The default constructor creates an empty proxy instance.

◆ xmog_base() [2/6]

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() [3/6]

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() [4/6]

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_base() [5/6]

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() [6/6]

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

◆ copy_jobject_()

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.

Referenced by xmog_field_t< FieldType >::operator=().

◆ duplicate_jobject_()

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.

◆ get_jobject_()

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.

◆ get_owning_jobject_()

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.

◆ get_released_local_jobject_()

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.

◆ release_standalone()

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.

◆ set_jobject_()

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.

Referenced by xmog_field_t< FieldType >::operator=().

◆ transfer_jobject_()

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.

◆ xmog_fill_with_standalone_for_()

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.

◆ xmog_invalidate()

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.

◆ xmog_lazy_write()

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.

◆ xmog_to_()

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

◆ @1

union { ... }

Data or object that provides assistance in accessing indirectly specified elements.

the information that is required to access the peer this could be an array index, or a field descriptor, or anything else that represents both the algorithm and the input information that is required to access the underlying data. index_ is supplied as a separate field as a performance enhancement: we don't want to allocate a dynamic instance just to contain the index.

◆ owner_

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.

Referenced by xmog_field_t< FieldType >::operator FieldType(), and xmog_field_t< FieldType >::operator*().

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

xmog_base.h

Public Types

Public Member Functions

Public Attributes

Detailed Description

Member Enumeration Documentation

◆ flags

Constructor & Destructor Documentation

◆ xmog_base() [1/6]

◆ xmog_base() [2/6]

◆ xmog_base() [3/6]

◆ xmog_base() [4/6]

◆ xmog_base() [5/6]

◆ xmog_base() [6/6]

Member Function Documentation

◆ copy_jobject_()

◆ duplicate_jobject_()

◆ get_jobject_()

◆ get_owning_jobject_()

◆ get_released_local_jobject_()

◆ release_standalone()

◆ set_jobject_()

◆ transfer_jobject_()

◆ xmog_fill_with_standalone_for_()

◆ xmog_invalidate()

◆ xmog_lazy_write()

◆ xmog_to_()

Member Data Documentation

◆ @1

◆ owner_