public class comhandle extends BaseDataType
Modifier and Type | Class and Description |
---|---|
private static class |
comhandle.WorkArea
Stores global data relating to the state of the current context.
|
Modifier and Type | Field and Description |
---|---|
static java.lang.Object |
EMPTY
The empty parameter marker for property access and method calls.
|
private ControlFrameComObject |
invalidAccessHandler
Special handler that shows an invalid access error when a attribute or method member is
accessed for an unknown/invalid handle.
|
private static java.util.logging.Logger |
LOG
Logger
|
protected ComObject |
value
The object stored by this special handle.
|
private static ContextLocal<comhandle.WorkArea> |
work
Stores context-local state variables.
|
private static ComObject |
ZERO_RESOURCE
A "zero" pseudo-resource.
|
Constructor and Description |
---|
comhandle()
Default constructor, creates an instance that represents the unknown value.
|
comhandle(comhandle that)
Constructs an instance that has the contained object reference and
unknown that
exactly matches that of the passed-in instance. |
comhandle(java.lang.Object value)
Constructs an instance that wraps the given object reference as a
WrappedResource . |
Modifier and Type | Method and Description |
---|---|
boolean |
_isValid()
Determines if this instance is valid (FWD internal access).
|
void |
assign(BaseDataType value)
Sets the state (data and unknown value) of this instance based on the state of the passed
instance.
|
void |
assign(ComObject newVal)
Dedicated assignment method for loading a
ComObject into this comhandle . |
void |
assign(Undoable newVal)
Modify the contained data of the instance to copy the instance data from the given instance.
|
BaseDataType |
call(java.lang.String method)
Calls a COM-method without parameters on the COM-object stored in this com-handle.
|
BaseDataType |
call(java.lang.String methodName,
java.lang.Object... params)
Calls a COM-method without parameters on the COM-object stored in this com-handle.
|
comhandle |
chain(java.lang.String property)
Chains access to COM property/methods.
|
comhandle |
chainCall(java.lang.String methodName,
java.lang.Object... params)
Calls a COM-method without parameters on the COM-object stored in this com-handle.
|
int |
compareTo(java.lang.Object obj)
Compares this instance with the specified instance and returns a -1 if this instance is less
than the specified, 0 if the two instances are equal and 1 if this instance is greater than
the specified instance.
|
java.lang.String |
defaultFormatString()
Return the default display format string for this type.
|
BaseDataType |
duplicate()
Does the same as standard
clone() method but returns an instance of
BaseDataType and doesn't throw the CloneNotSupportedException . |
static comhandle |
fromResourceId(java.lang.Long resourceId)
Converts the number representation of a handle into the original handle instance.
|
static comhandle |
fromString(java.lang.String txt)
Convert the string representation of a comhandle into the original comhandle instance.
|
BaseDataType |
getProperty(java.lang.String prop)
Obtain a property value from the COM object stored in this handle.
|
ComObject |
getResource()
Obtain the COM object held by this comhandle.
|
int |
hashCode()
Custom implementation of
Object.hashCode() . |
BaseDataType |
instantiateUnknown()
Creates a new instance of the same type that represents the
unknown value. |
boolean |
isUnknown()
Reports if this instance represents the
unknown . |
logical |
isValid()
Determines if this instance is valid.
|
void |
readExternal(java.io.ObjectInput in)
Replacement for the default object reading method.
|
static void |
removeResource(ComObject resource)
Remove the given resource from the context-local map of all resource.
|
static java.lang.Long |
resourceId(ComObject resource)
Get the ID of the given resource, as used by the
toString() and
fromString(java.lang.String) APIs. |
void |
setIndexedProperty(java.lang.String prop,
java.lang.Object newVal,
java.lang.Object... indices)
Sets a COM property for the COM object stored by the handle, with arbitrary indices.
|
void |
setProperty(java.lang.String prop,
java.lang.Object newVal)
Sets a COM property for the COM object stored by the handle.
|
void |
setUnknown()
Sets the state of this instance's
unknown value flag to true . |
static void |
showAccessError(java.lang.String prop,
java.lang.String errCode,
java.lang.String errMsg)
Shows a standard error for accessing an property of method of a com object stored in a
com-handle . |
private static void |
showInvalidAccessError(java.lang.String prop)
Shows a standard error for accessing an invalid
com-handle . |
java.lang.String |
toString()
Creates a string representation of the instance data using the format
ResourceIdHelper.DEFAULT_FORMAT . |
java.lang.String |
toString(java.lang.String fmt)
Creates a string representation of the instance data using the user specified format string
(Progress 4GL compatible) or if no such string is provided, the default format of
ResourceIdHelper.DEFAULT_FORMAT . |
java.lang.String |
toStringExport()
Creates a string representation of the instance data using the 'export' format.
|
java.lang.String |
toStringMessage()
Creates a string representation of the instance data in a form that is compatible with the
MESSAGE language statement. |
ControlFrameComObject |
unwrapComObject()
Unwrap this com-handle to the
ControlFrameComObject instance of the parent
ControlFrame . |
void |
writeExternal(java.io.ObjectOutput out)
Replacement for the default object writing method.
|
calcFormatLength, deepCopy, elementsOfType, equals, formatLength, generateDefault, generateUnknown, getTypeName, incompatibleTypesOnConversion, initializeDefaultExtent, instantiateDefault, instantiateDefaultExtent, isUnknownValue, maximum, minimum, notUnknownValue, sameType
changed, checkUndoable, checkUndoable, checkUndoable, getTransLevel, isGlobal, isUndoable, markUndoable, popBlock, rollback, setGlobal
private static final java.util.logging.Logger LOG
private static final ContextLocal<comhandle.WorkArea> work
public static final java.lang.Object EMPTY
protected ComObject value
private final ControlFrameComObject invalidAccessHandler
private static final ComObject ZERO_RESOURCE
handle.fromString(String)
method when a formally valid ID is provided, but the ID
doesn't denote a valid resource.
A zero resource is not valid but is not unknown.
public comhandle()
public comhandle(comhandle that)
unknown
that
exactly matches that of the passed-in instance.that
- The instance to pattern from.public comhandle(java.lang.Object value)
WrappedResource
.value
- The instance to contain.public static comhandle fromString(java.lang.String txt)
toString()
. Such comhandles are stored in a map for conversion purposes.txt
- A valid text representation of a comhandle ID.public static comhandle fromResourceId(java.lang.Long resourceId)
For handles whose backing resources still exist and which have been cached by
their IDs via resourceId(ComObject)
(which is called at various points in
the handle's life cycle), the method returns a valid handle instance. For handles whose
backing resources no longer exist, or which have never had their backing resources cached,
the method returns a zero handle, i.e. handle with "0" string representation.
resourceId
- Resource identifier.public static java.lang.Long resourceId(ComObject resource)
toString()
and
fromString(java.lang.String)
APIs.
The method allocates additional resources together with the provided wrapped resource,
thus it is necessary that removeResource(ComObject)
is called when
the returned resource id is not needed anymore (i.e. the related resource is deleted),
see removeResource(ComObject)
for more details.
resource
- A resource instance.public static void removeResource(ComObject resource)
This method should be called by all com objects resources when released,
that is all resources which are sub-classes of ComObject
.
resource
- A resource instance to be removed.public void assign(Undoable newVal)
assign
method is called, although this is not a strict requirement.newVal
- The backup instance from which to copy data.public void assign(ComObject newVal)
ComObject
into this comhandle
.
This method is only called by ComServer.create(String, comhandle)
. Stores a newly
created ComObject
into this handle.newVal
- The new value to be stored by this handle.public void assign(BaseDataType value)
assign
in class BaseDataType
value
- The instance from which to copy state.public boolean _isValid()
true
if this instance can be used.public logical isValid()
true
if this instance can be used.public BaseDataType instantiateUnknown()
unknown
value.instantiateUnknown
in class BaseDataType
unknown
value.public BaseDataType duplicate()
clone()
method but returns an instance of
BaseDataType
and doesn't throw the CloneNotSupportedException
.duplicate
in class BaseDataType
public boolean isUnknown()
unknown
.isUnknown
in class BaseDataType
true
if this instance is set to the unknown
value.public int hashCode()
Object.hashCode()
.hashCode
in class BaseDataType
public void setUnknown()
unknown value
flag to true
.
Warning: a separate call is needed to ensure that the data of this instance is set to the correct value.
setUnknown
in class BaseDataType
public int compareTo(java.lang.Object obj)
Comparable
interface.
The algorithm will fail to give meaningful results in the case where one tries to sort against other objects that do not represent compatible values.
obj
- The instance to compare against.unknown
.public java.lang.String toString()
ResourceIdHelper.DEFAULT_FORMAT
. If the instance represents the unknown
value, a '?' will be returned.toString
in class java.lang.Object
public java.lang.String toString(java.lang.String fmt)
ResourceIdHelper.DEFAULT_FORMAT
. If the instance represents the unknown
value, a '?' will be returned.toString
in class BaseDataType
fmt
- The Progress 4GL format string or null
if the default format is to be used.public java.lang.String toStringMessage()
MESSAGE
language statement. If the instance represents the unknown value
,
a '?' will be returned.toStringMessage
in class BaseDataType
public java.lang.String toStringExport()
unknown value
, a '?' will be returned.toStringExport
in class BaseDataType
public java.lang.String defaultFormatString()
Warning: this is larger than the Progress version because the range of handle values can be a 64-bit integer in this implementation.
defaultFormatString
in class BaseDataType
public void readExternal(java.io.ObjectInput in) throws java.io.IOException, java.lang.ClassNotFoundException
in
- The input source from which fields will be restored.java.io.IOException
- In case of I/O errors.java.lang.ClassNotFoundException
- If payload can't be instantiated.public void writeExternal(java.io.ObjectOutput out) throws java.io.IOException
out
- The output destination to which fields will be saved.java.io.IOException
- In case of I/O errors.public ControlFrameComObject unwrapComObject()
ControlFrameComObject
instance of the parent
ControlFrame
. If the comhandle is not obtained from a Control Frame using
COM-HANDLE
attribute handle or is invalid, a special ControlFrameComObject
is returned that handles invalid accesses.public void setProperty(java.lang.String prop, java.lang.Object newVal)
prop
- The legacy property name. Case insensitive. If no property is found then a warning
is displayed and method returns without altering the stored object.newVal
- The new value for the property. It must be of a compatible type with the property.public void setIndexedProperty(java.lang.String prop, java.lang.Object newVal, java.lang.Object... indices)
prop
- The legacy property name. Case insensitive. If no property is found then a warning
is displayed and method returns without altering the stored object.newVal
- The new value for the property. It must be of a compatible type with the property.indices
- A variable number of indices used to access this property's element.public ComObject getResource()
public BaseDataType getProperty(java.lang.String prop)
prop
- The legacy name of the property. Case insensitive. If no property is found then a
warning is displayed and method returns unknown
value.unknown
on exceptions.public comhandle chain(java.lang.String property)
ch:prop1:prop2:prop-or-method
will be
converted to something like: ch.chain("prop1").chain("prop2").get("prop-or-method")
property
- The property to access. It should normally be a com-object property of the object
stored in this comhandle
.comhandle
to the COM object property of currently referred resource. It
normally should be chained with another access for a property of method.public BaseDataType call(java.lang.String methodName, java.lang.Object... params)
methodName
- The method name. Case insensitive. If the COM-object does not declare such method
an error message is displayed and this method returns unknown
value.params
- The list of actual parameters. Their types must be compatible with the parameters
of called method.
TODO: marshal to BDT (?) When code is generated [param] is already BDT.public comhandle chainCall(java.lang.String methodName, java.lang.Object... params)
methodName
- The method name. Case insensitive. If the COM-object does not declare such method
an error message is displayed and this method returns unknown
value.params
- The list of actual parameters. Their types must be compatible with the parameters
of called method.
TODO: marshal to BDT (?) When code is generated [param] is already BDT.comhandle
, so it can be used in a
chained call or property access.public BaseDataType call(java.lang.String method)
method
- The method name. Case insensitive. If the COM-object does not declare such method
an error message is displayed and this method returns unknown
value.public static void showAccessError(java.lang.String prop, java.lang.String errCode, java.lang.String errMsg)
com-handle
.prop
- The legacy name of the property/method being accessed.private static void showInvalidAccessError(java.lang.String prop)
com-handle
.prop
- The legacy name of the property or method being accessed.