The Attribute Specification

This section describes the attributes at a semantic level without getting into representational issues.

Note that the attributes specify detail at the method level whenever possible. That is, while you customarily think of interfaces having IIDs, the attribute specification specifies an IID for each method, so that one Java interface could conceivably proxy to methods on multiple IIDs. For performance reasons, however, the first version of the Microsoft VM will not support this full generality. All methods on an interface will be required to have the same IID. The attribute language itself, however, is consciously designed not to obstruct future flexibility.

This section describes the attributes using an informal representation in which normal Java syntax is augmented by an "attribute syntax," where brackets contain attribute information. This should not be construed as recommending the syntax to use in a commercial development environment.

The type Attribute

This section's model divides Java classes into "pure," "Java-callable-wrappers," and "Java-callable data wrappers."

The allowable attributes are:

          class [type jcw <options>] foo {...}  // denotes a Java-callable wrapper
          class [type jcdw <options>] foo {...}  // denotes a Java-callable data wrapper

A given class has at most one type attribute. When no type attribute is present for a given class, the type of the class is determined as pure.

The type attribute can appear only in a class that derives directly from java.lang.Object. Interfaces do not have type attributes.

Java-Callable Wrappers

Java-callable wrappers (JCWs) are stateless proxies for a single COM object. JCWs can have an optional CLSID subattribute, which the following example shows.

   [type jcw {CLSID=....}]

Each instance of a JCW has an implicit marshaling mode that is determined using the parameter type attribute through which the JCW is created. The marshaling mode is either "NoMarshal" or "AutoMarshal".

If the marshaling mode is AutoMarshal, the JCW's home thread will be the thread that was current at the time the JCW was bound to the COM object. The JCW can be freely passed to other threads. However, calls to the JCW from outside threads will involve overhead due to marshaling back to the home thread. On a Microsoft® Win32® implementation, the home thread for an AutoMarshal JCW must process window messages on a regular basis. Otherwise, this thread will block other applications that attempt system-wide broadcasts.

If a class identifier (CLSID) is given, JCW classes can be used as the argument to the Java new operator. What happens then depends on the ThreadingModel (determined by the Threading Model registry entry for the CLSID).

If the ThreadingModel is "Free", the COM object is instantiated using the Win32 CoCreateInstance function on the current thread. The JCW can be passed around freely between threads and calls to it are never marshaled.

If the ThreadingModel is "Apartment", the object's home thread is either a special apartment thread or the current thread, depending on certain thread attributes that are outside the scope of this document. The JCW can be passed around freely between threads, but calls to it from outside the apartment thread will cause marshaling overhead.

If the ThreadingModel is "Single", the Microsoft VM switches to the hosting process's main Apartment thread to create the object. This thread is presumed to have a message loop.

Java-Callable Data Wrappers

Java-callable data wrappers (JCDWs) are stateless proxies for external data structures.

The ExposedAs Attribute

The ExposedAs attribute prescribes the external interface of COM-callable wrappers (CCWs) created for a given Java object. More specifically, for a given Java method or field, it describes whether it is exposed as a vtable or Dispatch interface; what IID it is exposed on, what vtable offset or dispid it is assigned to, what name it is exposed as (for Dispatch only) and how the parameters are marshaled.

The following example denotes these.

//pure
class Foo {
	[ExposedAs { VtblLoc  | DispatchLoc } <MethodDesc>]
	void Method1(int whatever)
	{
		DoesSomething;
	}
}

where:

   VtblLoc ::= (IID = iid, VtblOffset = offset)
   DispatchLoc ::= (IID = iid, DispId = dispid, DispType = type,  
                    [DispName = name])
   MethodDesc ::= (see later)

Note that a given member can have multiple ExposedAs attributes within the same class (akin to exporting the same function under multiple names from a dynamic-link library (DLL).) In addition, local classes can inherit ExposedAs attributes from superclasses and interface definitions. If a method overrides a method in a superclass, the local method is exposed through all the interfaces listed in the ExposedAs attributes of the overridden method, as well as its own (the overridden method is never exposed by this mechanism; this would violate the notion of overriding).

If two ExposedAs attributes within a class's inheritance tree specify equal vtbllocs or dispatchlocs, it is considered an error.

ExposedAs attributes may appear on interfaces that are named in the "implements" clause of JCW or JCDW classes. However, these attributes have no effect on those classes.

The ProxiesTo Attribute

The ProxiesTo attribute describes, for a given method or field of a Java-callable wrapper (JCW), exactly which Component Object Model (COM) member function it maps to in the underlying COM object.

//JCW
class Foo {
	void Method1(int whatever) 
	{
		[ProxiesTo { VtblLoc  | DispatchLoc} <MethodDesc>]
	}
}

Since JCWs cannot subclass each other, there are no overriding or inheritance rules to define for classes. However, Java interfaces can also specify ProxiesTo attributes (this is convenient for standard interfaces). In addition, interfaces that extend other interfaces can also override the ProxiesTo attributes of their parent interfaces (this is what happens when a COM interface definition inherits off another: it has its own IID).

In the case of multiple ProxiesTo attributes, the ambiguity is resolved by the form of the method call used. That is, in the following example:

interface IOleThing {
	[ProxiesTo (IID=IID_A,...]
	void foo();
}

interface IOleThingEx extends IOleThing {
	[ProxiesTo (IID=IID_B,...]
	void foo();
}

class CoOleThing implements IOleThingEx {
	[ProxiesTo (IID_IID_C,...]
	public void foo();
}

If the call to foo is made using invokeinterface on IOleThing, IID_A is used. If the call to foo is made using invokeinterface on IOleThingEx, IID_B is used. If the call is made using invokevirtual, CoOleThing is used.

The MapsTo Attribute

The MapsTo attribute describes how the fields of a Java-callable data wrapper (JCDW) map to offsets in the underlying data structure. These are valid only on the fields of a JCDW class. JCDW classes cannot subclass each other, so there are no inheritance/overriding rules.

//JCDW
class Data {
	[MapsTo ( [AutoOffset], Offset=offset, TypeDesc = typedesc)]
	int x;
} 

The TypeDesc structure is described in the next section. If the "AutoOffset" is set, the Offset must be zero and the Virtual Machine will compute the actual offset for the hosting platform. This allows the structure definition to move freely between platforms.

Method and Type Descriptions

The TypeDesc structure defines the type of a single method parameter or return value. TypeDesc structures come in two flavors: one for vtable methods and one for dispatch methods. TypeDesc structures do not attempt to describe the type of the corresponding Java. These attributes are always associated with a method attribute that specifies method signatures.

TypeDesc structures have in/out subattributes to aid in efficient marshaling. Also, if TypeDesc describes a Java-callable wrapper (JCW), you must tag it with a subattribute that indicates the expected marshaling model of the external COM object. JCWs have a "Marshaling Mode," which is one of "NoMarshal" or "AutoMarshal." On a NoMarshal JCW, all calls made from Java to COM are made on the calling thread. On an AutoMarshal JCW, the Microsoft VM marshals all calls back to the thread on which the JCW was created.

Vtable Types

VtblTypes can be one of the following:

void	For return values only: indicates method has no return value
signed(1|2|4|8)	Signed 1, 2, 4, and 8-byte characters
unsigned(1|2|4|8)	Unsigned 1, 2, 4, and 8-byte characters
real(4|8)	Float and double
ptr	A 32-bit linear address
struct(size)	A by-value structure or array
interface(IID)	An IUnknown interface derivative
jstring	Strings
jarray	Arrays

Dispatch Types

Dispatch types are denoted by the VARTYPE enumerations (the subset that is allowable in a VARIANT). In addition, the DispatchType encodes the expected IID for VT_UNKNOWN and VT_DISPATCH.

Method Descriptions

A MethodDesc structure appears in various method-level attributes. This structure is the equivalent of the "Java method signature" for a COM/dispatch type. Either it is an array of VtblTypeDesc structures along with a VtblTypeDesc structure for the return type; or it is an array of DispatchTypeDesc structures along with a DispatchTypeDesc structure.