<!-- ========================================================================
LCDInterfaceDef DTD:
Author:
John Tigue <jtigue@datachannel.com>
Last edited:
1998.34.21
This version:
http://www.datachannel.com/XML/DTD/LCDInterfaceDef-19980421.dtd
Latest version:
http://www.datachannel.com/XML/DTD/LCDInterfaceDef.dtd
Copyright (c) 1998 DataChannel Inc. http://www.datachannel.com
These declarations can be referred to as an external entity using either
a public ID:
<!DOCTYPE interfaceDef
PUBLIC
"-//DataChannel//DTD LCDInterfaceDef v0.6//EN"
"http://www.datachannel.com/XML/DTD/LCDInterfaceDef.dtd"
>
or using a system id such as:
<!DOCTYPE interfaceDef
SYSTEM
"http://www.datachannel.com/XML/DTD/LCDInterfaceDef.dtd"
>
-->
<!-- ========================================================================
History:
Release 1998.3.23 (John Tigue)
clearly unfinished but ready for some design feedback
Release NEXT (JFT)
1998.3.25 (JFT)
moved "unique" and "constant" in from ObjectMethodMessages
1998.3.29 (JFT)
moved other typeDoc constructs out and so made InterfaceRef
and ModuleRef which used to be parameter entity refs.
1998.3.31 (JFT)
Forked InterfaceDef.dtd to InterfaceDef.dtd and
OrnimentedInterfaceDef.dtd
1998.4.1 (JFT)
added in XLink and XPointer constructs with associated comments.
1998.4.3 (JFT)
started leaning heavily on NOTATIONs and ENTITY attributes for
'import' functionality
1998.4.5 (JFT
added use of primative data types as ENTITY referable attribute
values
-->
<!-- ========================================================================
Introductory Note:
LCDInterfaceDef (also known as LowestCommonDenominatorInterfaceDef)
contains definitions for using XML documents to describe software
component interfaces in a Web-native fashion. The term "Web-native
fashion" implies such technologies as HTTP (for transport and security),
XML, and URIs (URIs are just URLs and URNs grouped together). These
definitions are intended to be compatable with COM+, CORBA, and Java;
hence the "lowest common denominator". Work is in progress on another
DTD, FullLegacyInterfaceDef, which is designed for legacy code and
provides full support for all DCOM and CORBA features (RSN).
The information encoded in documents of this type is a textual
representation of a subset of the information in DCOM and CORBA IDL
files. XML enables the same document to be used by both humans and
computer tools. Humans (and 'assistance' tools) write the InterfaceDefs
and operating systems and developement tools can use the same documents
for such things as building interface repositories, as controlling
proxy-less marshalling, and for generating proxy and stub code in
various target programming languages.
(Note: there is some conflict in terminology. The two "marshallers"
are the main source code products derived from interface definition
documents. They have different names in different systems. In CORBA the
client/caller mashaller is called the "stub" and the server/callee it is
called the "skeleton". In COM+ they are "proxy" and "stub" respectively.
For clarity, WebBroker uses the term "proxy" for the client side and
"skeleton" for the server side. The term "stub" causes confusion and
so is not used.)
In the WebBroker system, InterfaceDef documents define software
component object interfaces. For actual communication messages between
software component objects, the ObjectMethodMessages DTD defines the
structure of documents which are serialized object method calls and
responses as they pass over the Web.
LCDInterfaceDef has been designed to work in Java, COM+ and CORBA.
As such it does not express all the features of CORBA and COM+. CORBA
2.2 defines mechanisms for mapping full CORBA to Java. That has its
place but LCDInterfaceDef has a design goal of simplicity. Also the
mapping between the COM and CORBA is not perfect. It is strongly
encouraged that new code only use these definition and that
FullLegacyInterfaceDef only be used in situations of legacy code.
LCDInterfaceDef has been designed to be upward compatable with
FullLegacyInterfaceDef.
The only concept which does not map transparently to Java is structs.
These had to be included in order to prevent an explosion of C/S round
trips. The map easily to Java classes with no methods and all member
fields public. Not very object oriented but then message passing isn't
very much so either. This is acceptable b/ on the wire only data is
being transfered. Code is not transfer as in Java RMI. These are purely
passive and declarative information collections.
maybe structs are XML chunks.
The concept of "Exception"s has been assumed for reporting faults even
for the COM environment. Microsoft is heading in that direction so there
is no need to propagate HRESULTs (ahmen). The Microsoft Java Virtual
Machine already expresses HRESULT error codes as instances of the class
com.ms.com.COMException. The COMExpeption is what is transimitted over
the Web.
One of the design goals of this effort is to enable a simple client and
a simple protocol. For client-side simplicity, one improvement is to
allow method parameters to only be marshalled in. The same information
return value as 'out' marshalling can be achieved by defining a
struct which contains all the desired info and using that as the
return type. The only information
marshalled out would be the return value (or an exception). This way the
client-side proxy does not have to map data structures which are
marshalled in and out. Interfaces design with this constrain are also
??? more friendly to Java and EcmaScript (VB, COM+??????????). These
definitions
follow this design goal. The definitions in FullLegacyInterfaceDef
include and extend the definitions here, such that if existing code is
being migrated to the Web there is support for such concepts as enums,
unions, sequences, attributes, and parameters which are
marshalled 'out' or 'in and out'. FullLegacyInterfaceDef is for use
only with legacy code.
Documents of type LCDInterfaceDef are often interlinked with related
document of the same type and/or the following types:
ModuleDef:
ExcetionDef:
TypeDef as seperate from StructDef ? what does corba say?
Just DTD syntax or new construct?
The mapping between CORBA's meta object facility and WebBroker is:
CORBA WebBroker
============ =======================
ModuleDef ModuleDef document
ExceptionDef ExceptionDef document
OperationDef methodDef element
(what do typelib APIs call them?)
what does MS Repository call them?
ParameterDef parameterDef element
AttributeDef N/A
ConstantDef constantDef element
TypeDef N/A but subseted by ComplexDef
InterfaceDef LCDInterfaceDef document
others?
Note that there is no independent document type 'constantDef' as might
be expected if following the CORBA interface repository APIs. Java
does not support such a concept. These definitions do allow for
'constantDef's but not as a document root element type. This still maps
to the CORBA concepts.
Nor do ParameterDef's occur as independent document roots. The occur as
elements which are descendents of a interfaceDef.
Applying the "lowest common denominator" design requirement means that
there are no such things as AttributeDefs because Java does not support
them.
note the restrictions on the CORBA interface repository and how this maps
to the CORBA 2.2 stuff.
note that for entities, names need to be constrained to be legal names
(with the associated rules for name start chars and name chars) in XML, Java,
CORBA, and COM+. I.e. legal names in WebBroker are legal names in all four
mentioned systems.
(Phylosophical soliloquy: a design goal of these related document types
is to correspond to existing interface definitions and the APIs for
accessing those definitions(COM TypeLibs accessed through APIs such as
ITypeLib, ITypeInfo, and ITypeComp and also CORBA Interface Repositories
and their APIs). The novelty and value here is the Web-native
syntactical foundation (the XML specs) and the Web conscious design.
Because the Web can have
long, slow links between machines, it is desirable to minimize the
number of client to server roundtrips. Whereas in LAN-based situations
it is acceptable (even encouraged) to have very high granularity APIs
*** (e.g. sundry nitty APIs), on the Web it is desirable to pack as much
related info as possible in a single roundtrip (ergo structs ala CORBA
2.2). This must be balanced against a
modular design. The balance point is also constrained by XML mechanics.
For example, when linking two documents, notation declarations can be
used to say "the thing on the other end of this link is of notation X".
Different NOTATIONs can be declared for each document type. When
declaring the NOTATION, a PUBLIC or SYSTEM id needs to be assigned. It
would be desirable to use the NOTATION's ID indicate what type of
structure is on the other side of the link by declaring that the link
goes to an ENTITY of a particular NOTATION. This technique has been used
to link the various related structures. If one DTD had been used for all
the
various components, then the notation declarations would not be able to
distinguish which type of construct was at the end of the links.
If you wish to compare InterfaceDef documents to MS TypeLibs: a TypeLib
is a binary document which is simply a group link (and embedding of) to
sundry related type definition documents, similar
to how an HTML page may have links to its graphics and other related sub
parts. A client machine will download a desired "TypeLib" root document,
keep the
connection open, read the "TypeLib" to discover what other documents
need to be downloaded, and after doing so it will then create the in
memory
representation of the "TypeLib". (Technically that was multiple round
trips but the HTTP persistant connection makes that uncostly). It is
expected that MS will even expose these documents through its
existing TypeLib APIs.
Another value is that by packing up the type
info into a collection of XML documents, just the relevant parts can
be downloaded for efficient federating as opposed to bringing down
large type repositories. In this way the interface repository (aka NT
Registry)
is (controllably) exposed to the Web and TypeLibs are simply
conveniences indicating how to quickly download most everything another
machine will be expected to need. This Web conscious design phylosophy
brings
out the value of XML as the syntax of the Web's APIs. End of
soliloquy/essay.)
In general, many element names defined in these documents are of the
form "XxxxDef" and "XxxxRef" where XxxxDef is the definition of some
structure and XxxxRef is a reference to a XxxxDef element with the
same name prefix: e.g. ExceptionDef and ExceptionRef.
Documents complying to these definition are pure XML 1.0 documents. Data
typing is not part of XML 1.0. Currently data typing is done in the XML
application not the XML processor. When XML has data types (with
XML-Data being the most comprehenive work to date in that area) more of
the data typing responsibilities can be left to the XML processor.
Whatever the XML WG produces, this work will be revised to reflect their
decision. In general, these definitions have been design to use the XML
1.0 processor as much as possible and to minimize the amount of
"application" level logic. Also ENTITY attributes have been relied on
for document linking. When XLink is worked out it will be adopted. Using
ENTITY attributes for linking is also very similar to HyTime. Note also
that by declaring other typeInfo docs as entities, if a doc needs to be
referred to more than once in a document then the idempotence (it that
even the right word?) of the entity being referred to is clearer. This
also reduces the possibility of human typos. All experienced programmers
understand the value of declaring variables before using them. This is
the analogous argument in XML. XLink is like not having to declare
variables in Visual Basic (remember 'Option Explicit'). That's very
handy but dangerous when you get
into the operating system.
Some people new to XML and only familiar with HTML find the use of
ENTITY attributes and NOTATION declarations coumbersome. The value of
these is tighter type checking (using NOTATION and NDATA on the ENTITY)
and itindicates to the processor that the attribute is an entity that
should be locatable rather than "the application knows its an URI".
Without defining appropriate attributes as ENTITY, more smarts have to
be put in the XML application layer which in unneccessary and opens the
door to less interoperability.
Note that in the WebBroker system the 'things' of interest are
type documents which are all referenced through external entities.
External entities can be define using either PUBLIC or SYSTEM IDs.
Either way the document instances are the same and only the internal DTD
'headers' change. This way the interface repository can simply be stupid
URLs which have been inteligently arranged (just like Java, no need for
more complex machinery). Alternatively, PUBLIC IDs can be used which map
to existing interface repositories for migration purposes.
Notes about things not explicit in the declarations:
Consider the following snippet from the head of a Java class:
package datachannel.io.xml;
import java.net.*;
import java.io.DataInput
public class XMLReader {
These statements are used to define names and associate them with
entities (in this case java .class files). Declaring the class
'XMLReader' to be in the package 'datachannel.io.xml' defines its
name context. It also implicitly does some 'importing'. Any classes
in the package 'namespace' of 'datachannel.io.xml' are automatically
recognised as valid names. In the WebBroker system, the XML processor is
used to recognize names. In Java, each name must be unique. In XML,
each entities name must be unique. This correspondence is used in
WebBroker (why reinvent the wheel). To get the effect of 'fellow
module residents' name are recognised' simply declare the moduleDef
as an external entity and then do a parameter entity reference such
that the entity references in the moduleDef will define all the
'fellow residence'. The XML processor will catch name collisions for
the WebBroker. The same argument holds for the wildcard import (second
line of the above snippet). The effect of 'importing' a single object is
simply declaring it as an external entity.
The point is that only one entity name is allowed within a document. By
doing things this way the already worked out and standardized (read:
let's not waste time reinventing the wheel) power of XML 1.0 can be
leveraged. Placing the intelligence in the application layer
unneccessarily reduces the chance of interoperability
For moduleDef's there is the issue of wildcarding. In, say, Java
there are two forms of "import". For example:
import java.io.DataInput;
inport java.io.*;
In CORBA thats---
In COM+ thats---
The first brings in a single "interfaceDef" and the second brings
in an entire "logicalGroupName"'s set of "interfaceDef"s. They are very
similar syntactically but very different.
The first, simpler but less desirable is that a moduleDef is nothing
more than an entity which contains only a set of parameter
entity defs and refs. I.e. it explicitly and manually includes
all the interfaceDefs in the module's namespace (but not sub-
namespaces).
There are two solutions which have been encountered so far. The problem
is one of staleness i.e. a new interface may be added to a module but if
the moduleDef is not updated then the new interface will not be
"included".
The second is better but requires some smarts on the part of the
Web server which is serving up these interfaceDef entities
(or the entity manager which is doing the same). Consider the
current situation: many Web servers can
generate (on the fly) an HTML document which lists the contents
of a directory. This is the model for the second solution.
This makes sence in the context of humans and
Web browsers. But they could just as well have listed the
contents of all the files in the directory. The point is that
these documents are generated on the fly as so do not become
stale. So the two examples above could translate into:
<import interfaceDef="SOMEROOT/java/io/DataInput" />
<import moduleDef="SOMEROOT/java/io/" />
Note that the attribute values are ENTITY implying that in the
internal DTD subset of the document the entity is defined. E.g.:
<!ENTITY SOMEROOT/java/io/ SYSTEM "http:...../java/io/">
In a situation such as DCOM where the included defs are actually
in a legacy format such as typeLibs, you might want to use
a notation declaration for transitional purposes, say:
<!NOTATION TYPELIB PUBLIC "Microsoft TypeLib v2" >
This has not been done here. TypeLibs should be algorithmically
migratable to the WebBroker system. Note the the OrnimentedInterfaceDef
DTD MAY allows for there to be links to Microsoft COM TypeLibs. That is
a legacy issue and is not addresed in these definitions.
A TypeLib is simply an archive of typeDocs. Can MIDL indlued refs to
TypeLIbs,? VB seems to , Typelib can to refer to other Typelib so make
is a refd to otehr InterfeacDef entity.
Note that the XML namespace facility is not relevant to this issue. XML
namespaces and software code module namespaces are completely unrelated
and one can not be used to express the other.
Acknoledgements:
McCool and Prescod are the pioneers who pointed the way. Their
work is available at:
http://www.cgl.uwaterloo.ca/Projects/meta/.
This work removes the documentation structures from their
work simply to make the entire DTD more easily comprehendible on
first reading. The documentation structures should be re-introduced
when these issues are addressed in a W3C Working Group. In general
this work is a stripped down version of what they did for reasons
related to both simplicity and human readability.
Thanks to W. Eliot Kimber and Eve Maler for their DTD design help.
Also, Gavin Nicol had already started working on IDL in XML while
working on the DOM. His work was a helpful reality check.
References:
MS-IDL:
CORBA-IDL:
CORBA Meta Object Facility:
McCool&Prescod:
GavinNichol:
-->
<!-- ========================================================================
Here these declarations are simple saying that they are also a notation.
-->
<!NOTATION interfaceDef PUBLIC "-//DataChannel//DTD InterfaceDef v0.9//EN" >
<!-- ========================================================================
Here the data typing structures are pulled in. Basically two parameter
entities are used. They are defined as:
<!ENTITY % loquaciousPrimativeDataTypes
"boolean | booleanArray | char | charArray | double |
doubleArray | int | intArray | long | longArray | float |
floatArray | short | shortArray | byte | byteArray |
string | stringArray" >
<!ENTITY % loquaciousPrimativesPlusObjectRefs
"%loquaciousPrimativeDataTypes;|objectRef|objectRefArray " >
The terse analog of these declarations pulls in the
TerseObjectMethodMessages declarations not, as here, the loquacious
ones.
-->
<!ENTITY % objectMethodMessagesAndDataTyping
PUBLIC
"-//DataChannel//DTD ObjectMethodMessages V1.0//EN"
"http://xml.datachannel.com/system/dtd/ObjectMethodMessages.dtd"
>
%objectMethodMessagesAndDataTyping;
<!-- ========================================================================
"interfaceDef" is the intended root for documents of this type. An
interface is essentially just a collection of methods plus some
constants thrown in. This constrained definition is imposed by Java's
interface facility. The "FullLegacyInterfaceDef" DTD extends these
declarations to include many legacy constructs of COM and CORBA.
-->
<!ELEMENT interfaceDef
( namingContextRef?, interface, distributionInfo? )
>
<!-- ========================================================================
'namingContextRef' is the name scope of an interfaceDef. In Java, it is
called a "package". In CORBA they are modules. COM+ seems like it is
going to call it a "package" or "module" or "namespace" (the latter
would be most unfortunate).
This is simply a link to the moduleDef document which contains this
document and all the other documents which are in the module. I.e. this
is exactly the same thing as a moduleRef. This link can be used to
discover the other entities in this namingContext which are 'included'
during compilation i.e. their names are (uniquely) defined and
associated with entities.
Note that the entity which is the value of the 'moduleRef' attribute
is the same entity which was defined and referenced to get the 'fellow
module residents' name are automatically recognised' effect. See the
introductory notes to this file. XML breaks out the dual role of the,
say, Java package declaration into two seperate syntactical constructs:
one parameter entity decl and reference in the internal DTD subset
(to do the implicit including) and one simple entity attribute value (to
declare the naming context).
To place an interface in the default namespace, simply do not specify a
namingContext (could have gone with null stringed PUBLIC ID? or a
predefined PUBLIC ID for "defaultPackage").
It is an application level error for the entity in the 'moduleRef'
attribute to be anything besides a document conforming to the ModuleDef
DTD.
(Note: COM DLLs are related to physical packaging not logical so that
is not what "namingContext" is about even though the two often
match each other).
(ToDo: Does this conflict or miss the meaing in CORBA? reflect MS
Repository and OIM's label for this? Other candidates:
logicalGroupingName, moduleDecl)
-->
<!ELEMENT namingContextRef EMPTY>
<!ATTLIST namingContextRef
moduleRef ENTITY #REQUIRED
>
todo: the hytime arch form
todo: what's the diff between extended link and extended group link? XLinked
and HyTime
<!-- ========================================================================
'interface' is the main subject of LCDInterface documents.
-->
<!ELEMENT interface (interfaceName, methods) >
what about interfaceName and what about it mapping to its PUBLIC ID
<!-- ========================================================================
The 'interface' element has attributes. The attribute 'id" is the uuid
of the interface. If using the COM "IID" as the public ID then these two
must match.
If the 'superInterface' attribute is not explicitly assigned then there
is no super-interface for the interface being defined.
? In Java and COM+ (CORBA?), interfaces can inherit from (possibly muliple) other
interfaces. The 'superInterfaces' attribute is how such relationships
are established. Note that LCDInterfaceDef only deals with interfaces.
Class inheritance is not addressed.
(The issue of super-interfaces has (at least) two solutions. The
(possibly multiple) super-interfaces which an interface extends could
simply be listed in sub-elements. Alternatively, each super-interface
can be declared to be an ENTITY of NOTATION 'lcdInterfaceDef' in the
internal DTD of an LCDInterfaceDef instance document. These entities
are then referenced as the values of an attribute of type ENTITIES. The
second option was chosen because it more fully leverages the power of
the XML 1.0 processor (less code, more interoperability, plus
developers already use 'wizards' to define IDL files so no whining
about lack of readability).
Going with the notated entity attributes options may seem like overkill
to a HTML person but these documents are not for UI but rather for
use in an operating system and related tools. Actually, although this
choice results in slightly more typing I find the results to be more
readable; in the entity definition we can give the method any old
friendly which appears in the attribute assignment. This also makes more
explicit the fact that the friendly name is just that, the IID uuid is
what really matters. I.e. by going with declaring entities, the option
is presented to use either SYSTEM or PUBLIC IDs and the PUBLIC ID can be
a IID uuid which works with IDL very nicely.)
(TODO: when have datatyping on attribute, make it 'XM-Data:uuid')
-->
<!ATTLIST interface
id ID #REQUIRED
superInterfaces ENTITIES #IMPLIED
>
<!-- ========================================================================
An interfaceRef is just a reference to another interface which has
been previously defined as an ENTITY. It is an application layer error
for the referenced entity to be anything other than another InterfaceDef
document
-->
<!ELEMENT interfaceRef EMPTY>
<!ATTLIST interfaceRef
interface ENTITY #REQUIRED
>
<!-- EveM: Is that correct? -->
<!-- ========================================================================
Note that currently there is no concept of a constructor or a 'new'
message. Java interfaces do not allow for constructors. CORBA interfaces
do not allow for constructor.
-->
<!ELEMENT methods ( methodDef* ) >
<!-- ========================================================================
A methodDef has a name (which programmers see), a return type,
optionally some parameters to the method, and optionally some exceptions
which the method can throw. Note that this version of WebBroker makes no
special distinction between "normal" methods and get/set methods a.k.a.
attributesin IDL. Attributes are defined in the FullLegacyInterfaceDef
DTD. Java does not have attributes in interfaces so the "no attributes"
constraint is required for "lowest common denominator". CORBA has
mappings for attributes-to-Java but that is not supported here
for reasons of simplicity.
?? the methodDef's id is isomorphic to MIDL methodIDs
Another argument for only having one interface defined in a document is
that the methodDef has an ID attribute. If there is only one
interfaceDef per document then this ID can be used in instances of the
ObjectMethodMessages DTD i.e. the serialized method calls. In MIDL, each
interface is a seperate "namespace" for method IDs.
what happens when one interface extends another? would like to keep the ids
seperate and unique across the combined namespace. This can be done because
in the WebBroker system, each interface has a unique uuid. If an interface is
modified it is given a new uuid (versioning). Therefore at the time of
interface inheriting, the ids are known and will be always fixed so this can
be done.
In the OMM, that looks like:
&myIDef;?ID(thisHereIDvalue)
so in OMM methodID needs to be an IDREF i.e. ToUnique
how do you do ID refs out of document in XLink?
(how terse is theis compared to DCOM headers for InterRef ala recent
DCOM protocol artile in MSJ?)
now, how do I make the OMM intefaceRef ENTITY work with the XPointer
-->
comment that need methodID b/ the OMMess can say:
<methodCall methodID="&someIface;#id(method4)" >
(in MIDL is the returnval a unique attrib?)
note that parameterDef is "scoped to a methodDef i.e no method would ever
have knowledge of an other methods param (except reflection?) Otherwise don't
make no sence. So even though CORBA paramterDefs are independent objects from
methodDefs, that is not the case here b/ want to have minimal roundtrips over
the Web.
the methodsig name cannot be an ID b/ of polymorphism. Address polymorphism
Note: could have gone with parameters which has parameterDefs and throws
which has exceptionRefs
went with methodsign and not methodDef why? implies name, return and params
<!ELEMENT methodDef (returnType, methodName, parameters?, throws?) >
<!ATTLIST methodDef
id ID #IMPLIED
-- maybe should be #REQUIRED for more strength and ref from OMMessage
>
note that the 'name' attribute is not an ID so it is not required to be
unique within an interfaceDef document. This allows for polymorphic methods.
Two methods with the same name can be distinguished by their IDs.
<!-- The methodName is the human readable name programmers see -->
what about this better b/ CDATA is freer than xml names, stupid
<!ELEMENT methodName (#PCDATA)>
Fuck. I need to be able to say same as dt:dt so why this? Ugly too.
Nothe taht dt:dt is really a message to the XML 1.0 processor's application
which in this case includes teh DataTyper which ias previously mentioned is
not part of the MXL 1.0 prossore. In general, whould be mroe
power to the XML1.0 if dt:dt were defined to a na attibute of type
ENTITY or were "enumerated to be a parmaterEntREf (or just enumerated attrib as is)
<!-- The returnType contains an empty element of one of the allowed types
e.g.: <returnType><string/></returnType>
-->
<!ELEMENT returnType
( %loquaciousPrimativesPlusObjectRefs; | void | %struct;)>
Now how do I say struct? sounds like a ENITY attrib on the mehodDef
would need entityRefs for all the primative. see "wishfull thinking"
<!-- ========================================================================
'parameters' is the list of parmeters to a method(Def). If a
method has not parameters the 'parameters' element should not occur. If
it does occur it must contain at least one 'parameterDef'
-->
<!ELEMENT parameters ( parameterDef+ ) >
<!-- ========================================================================
A 'parameterDef' defines a parameter to a method(Def).
A parameter's type is expressed as a subelement in order
to imply that entire XML structures (elements and subelements) may be
passed as parameters (later). What about the type indirection issue?
It has the following attributes:
id: for dispatch reasons this is isomorphic to the info in TypeLibs
name: user friendly name
The parameterDef ID can be used in an ObjectMethodMessage to identify
which parameter is being passed. This is useful for languages such as
Visual Basic where parameters can be named and may be optional.
Note that there is no marshalling direction attribute. For simplicity,
all parameters are marshalled in only. FullLegacyInterfaceDef addresses
marshalling by adding the 'marshalling' attribute to this element type.
The 'dt:dt' attribute is used to declare what data type the parameter
can have. Although 'dt:dt' namespace colonized, an XML 1.0 processor
does not know about ':' being a special name character and does not
know about namespaces. The XML-Data name space is declared in one of
the documents which are entity referenced into these definition. A
XML 1.0 processor simply passes it on as a processsing instruction to
the XML application and does not recognise the significance. This way
data typing can be expressed in XML 1.0 documents and later when we have
'XML-Data' processors, the data typing can be left to the 'smarter'
processor. With WebBroker the XML application recognises the
signifigance of the 'dt:dt' attribute.
As defined here, parameter instances can be null but not 'void'.
-->
what else is going on in the CORBA paramDef
<!ELEMENT parameterDef EMPTY>
<!ATTLIST parameterDef
id ID #IMPLIED
name CDATA #REQUIRED
dt:dt CDATA %loquaciousPrimativesPlusObjectRefs; #REQUIRED
>
<!-- ========================================================================
'throws' declares what exceptions a method can throw. Exceptions are
defined in seperate documents. the 'exceptionRef' is simply a reference
to the externally defined exception.
If a method does not throw exceptions then a 'throws' element should not
occur. If a 'throws' element occurs it must contain references to one or
more 'exceptionDef's
-->
<!ELEMENT throws ( exceptionRef+ ) >
<!-- ========================================================================
'exceptionRef' is a reference to an ExceptionDef document. It is an
application level error for the value of the 'exception' attribute to be
anything besides a document which complies to the ExceptionDef DTD.
-->
<!ELEMENT exceptionRef EMPTY>
<!ATTLIST exceptionRef
exception ENTITY #REQUIRED
>
<!-- todo: EveM: is this distributeInfo stuff correct?
I'm trying to say that "distributionInfo" is a link to a document. That
document will always have the notation "OSD"
-->
<!-- ========================================================================
'distributionInfo' is a pointer to where executable code can be found
which acts as a proxy to the interface being defined. It is essentially
a link to an OSD file. In an instance of this document type, something
like the following should occur:
<!ENTITY someOsdDoc SYSTEM "http://a.b.com/osd1.osd" NDATA OSD >
After defining this document as above, something like the following
should occur:
<distributionInfo osdDoc="someOsdDoc" />
Declaring the OSD document to be an entity and of a particular notation
allows the processor to do more "checking" for us. Extra work but better
results when trying to assure these document instances will work over
the Web.
'distributionInfo' is a reference to an Open Software Distribution (OSD)
document. It is an application level error for the value of the 'osdDoc'
attribute to be anything besides a document which complies to the OSD
DTD.
-->
<!NOTATION OSD
PUBLIC
"-//WhoOwnsIt//blah blah fpi"
>
<!-- todo: check for the PUBLIC id of OSD -->
<!ELEMENT distributionInfo EMPTY >
<!ATTLIST distributionInfo
osdDoc ENTITY #REQUIRED
>
<!-- EveM: are these NOTATION correct? is this how to say, link to a doc which
has been declared an entity and has notation (i.e. declared doctype) of
OSD?
<!-- ========================================================================
A 'constantDef' is the definition of a constant. Instances of this
element type have a datatype, a value, and a name.
These definitions and related DTDs, constrain CORBA such that
'constantDef's are always children of 'interfaceDef's. The restriction
is that in CORBA constantDefs can also be children of moduleDefs. This
restriction is imposed by Java. Constants can still be defined in CORBA
but only within 'interfaceDef's.
These definitions constrain Java in that only primative data types or
object references can occur as constants in interfaces. In Java,
arbitrary class instances can occur in interfaces.
-->
<!ELEMENT constantDef (#PCDATA) >
<!ATTLIST constantDef
id ID #REQUIRED
name CDATA #IMPLIED
dt:dt CDATA %loquaciousPrimativesPlusObjectRefs; #REQUIRED
>
<!-- ToDo: Adding constant objects gets close to COM+. What would the
implications be for CORBA? On which side of the interface do the objects
exist? If the interface is on an object then it would seem the constant
would also exist where the object resides.
-->
<!-- ========================================================================
Wistful thinking:
&null;
would like to refer to primative types just like interfaces or at least
as ENTITIES (maybe they are Refs to PrimativeDataTypeDefs, one for each
primative data type. Each a PUBLIC id or a doc? it'd be very explicit for
the processor and can say type indirectly and directly just the same
primative datatypes as entity refs allows direct and indirect ref. The
dt:dt attribute becomes an entity. can entity attribs be enumerated?
don't think so.
are int() i.e. parans legal name chars?
No: each interface has its own InterfaceDef.
Perhaps each datatype does to
want entity for each primative datatype plus object + void
this is what would be inported not OMMs Anonymous data
now structs and primatives can be refed the same way.
This is unwieldly just for the designer, system is stronger and
the user just does an include but primatives can now be refered
to as:
&primativesDefInstance;#ID(5)
the ENTITY attrib which declares the datatype does the same thing as
the dt:dt attribute. One ala XML 1.0 one for XML-data processors
That stuff goes right in there with the boilerplate for notations
Can an InterfaceDef have multiple interfaces in one doc?
No. EVIL b/ PUBLIC id is name of interface i.e. unique and distingable
InterfaceDef.dtd could also have an element type of InterfaceDefs
<!Element InterfaceDefs (InterfaceDef*) >
That's how a moduleDef would work.
(TODO: subtly express that CORBA has no constructors. What about the
2.2 mapping? How does CORBA handle remote activation?)
-->