Menu
▾
▴
[ccmtools-cvs] ccmtools/doc/manual/InterfaceDefinitionLanguage Interfaces.tex, 1.1, 1.2 SourceFiles.tex, 1.1, 1.2 Modules.tex, 1.1, 1.2 InterfaceDefinitionLanguage.tex, 1.1, 1.2 Introduction.tex, 1.1, 1.2 BasicTypes.tex, 1.1, 1.2 UserTypes.tex, 1.1, 1.2 Components.tex, 1.1, NONE
|
From: Teiniker E. <tei...@us...> - 2007-01-24 15:35:36
|
Update of /cvsroot/ccmtools/ccmtools/doc/manual/InterfaceDefinitionLanguage In directory sc8-pr-cvs4.sourceforge.net:/tmp/cvs-serv5911/doc/manual/InterfaceDefinitionLanguage Modified Files: Interfaces.tex SourceFiles.tex Modules.tex InterfaceDefinitionLanguage.tex Introduction.tex BasicTypes.tex UserTypes.tex Removed Files: Components.tex Log Message: Added some manual pages. Index: BasicTypes.tex =================================================================== RCS file: /cvsroot/ccmtools/ccmtools/doc/manual/InterfaceDefinitionLanguage/BasicTypes.tex,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** BasicTypes.tex 15 Aug 2006 15:45:08 -0000 1.1 --- BasicTypes.tex 24 Jan 2007 15:35:29 -0000 1.2 *************** *** 1,3 **** - % $Id$ %============================================================================= \section{Basic IDL Types} --- 1,2 ---- *************** *** 69,72 **** will eventually need to transmit between client and server, you can find out at runtime what type of value is contained in the {\tt any}. ! \newpage --- 68,78 ---- will eventually need to transmit between client and server, you can find out at runtime what type of value is contained in the {\tt any}. + It is recommended to use a {\tt typedef} construct to introduce any types in your + interface definition files. ! \vspace{2mm} ! Example: ! \begin{verbatim} ! typedef any GenericType; ! \end{verbatim} ! Index: Interfaces.tex =================================================================== RCS file: /cvsroot/ccmtools/ccmtools/doc/manual/InterfaceDefinitionLanguage/Interfaces.tex,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** Interfaces.tex 15 Aug 2006 15:45:07 -0000 1.1 --- Interfaces.tex 24 Jan 2007 15:35:29 -0000 1.2 *************** *** 1,28 **** - % $Id$ %============================================================================= \section{Interfaces} %============================================================================= %----------------------------------------------------------------------------- ! \subsection{Constant Definitions and Literals} %----------------------------------------------------------------------------- %----------------------------------------------------------------------------- ! \subsection{Operations} %----------------------------------------------------------------------------- %----------------------------------------------------------------------------- ! \subsection{Attributes} %----------------------------------------------------------------------------- %----------------------------------------------------------------------------- ! \subsection{User Exceptions} %----------------------------------------------------------------------------- %----------------------------------------------------------------------------- \subsection{Inheritance} %----------------------------------------------------------------------------- ! \newpage --- 1,253 ---- %============================================================================= \section{Interfaces} %============================================================================= + The focus of IDL is on interfaces and operations. + IDL interfaces define only the interface to an object and say nothing about the + object's implementation. This has the following consequences: + \begin{itemize} + \item By definition, everything in an interface is public. + Things are made private by simply not saying anything about them. + + \item IDL interfaces don't have member variables. + Member variables store state, and the state of an object is an implementation + concern. + \end{itemize} + + IDL interfaces form a namespace. You can nest the following constructs inside + an interface: constant definitions, attribute definitions, and operation definitions. + + \newpage + Example: + \begin{verbatim} + module world + { + interface IFace + { + /** Constant definitions */ + + /** Attibute definitions */ + + /** Operation definitions */ + }; + }; // end of module world + \end{verbatim} + + It is important to note that IDL operations and attributes define the only + communication path between objects. + The kinds of information traveling along the communication path are the + parameters, return value, and exceptions of an operation. + + %----------------------------------------------------------------------------- ! \subsection{Constant Definitions} %----------------------------------------------------------------------------- + IDL permits the definition of constants, thus, you can define floating--point, + integer, character, string, boolean, and octet constants. + IDL does not allow you to define a constant of type {\tt any} nor a user--defined + complex type. + + \vspace{2mm} + Example: + \begin{verbatim} + module europe + { + interface ConstantsTest + { + const boolean BOOLEAN_CONST = TRUE; + const octet OCTET_CONST = 255; + const short SHORT_CONST = -10; + const unsigned short USHORT_CONST = 7; + const long LONG_CONST = -7777; + const unsigned long ULONG_CONST = 7777; + const char CHAR_CONST = 'c'; + const string STRING_CONST = "1234567890"; + const float FLOAT_CONST = 3.14; + const double DOUBLE_CONST = 3.1415926; + }; + }; // end of module europe + \end{verbatim} + + %----------------------------------------------------------------------------- ! \subsection{Attributes} %----------------------------------------------------------------------------- + An attribute can be used to create something like a public member variable. + In fact, an attribute defines a pair of operations the client can call to + sent and receive a value. + Note that IDL attributes don't define storage or state. + + \vspace{2mm} + Example: + \begin{verbatim} + module america + { + struct Person + { + long id; + string name; + }; + + interface AttributeInterface + { + attribute long longAttr; + attribute double doubleAttr; + attribute string stringAttr; + attribute Person personAttr; + }; + }; // end of module america + \end{verbatim} + + Attributes can be of any type, including user--defined complex types. + + %----------------------------------------------------------------------------- ! \subsection{Operations} %----------------------------------------------------------------------------- + An operation definition can occur only as part of an interface definition, and + must contain: + + \begin{itemize} + \item A return result type + \item An operation name + \item Zero or more parameter declarations + \end{itemize} + + \vspace{2mm} + Example: + \begin{verbatim} + module austria + { + interface SimpleInterface + { + /** + * This is the simplest possible operation, because + * op requires no parameters and does not return a value. + */ + void op(); + }; + }; // end of module austria + \end{verbatim} + + Notice that a parameter must be qualified with one of three + {\bf directional attributes}: + \begin{itemize} + \item {\bf in}\\ + The {\tt in} attribute indicates that the parameter is sent from + the client to the server. + \item {\bf out}\\ + The {\tt out} attribute indicates that the parameter is sent from + the server to the client. + \item {\bf inout}\\ + The {\tt inout} attribute indicates a parameter that is initialized by + the client and sent to the server. + The server can modify the parameter value, so, after the operation + completes, the client--supplied parameter value may have been changed + by the server. + \end{itemize} + + \vspace{2mm} + Example: + \begin{verbatim} + module styria + { + interface AnotherInterface + { + long op(in long p1, inout string p2, out double p3); + }; + }; // end of module styria + \end{verbatim} + + Operation names are scoped by their enclosing interface and must be unique + within that interface, so {\bf overloading of operations is not possible in IDL}. + + + %----------------------------------------------------------------------------- ! \subsection{Exceptions} %----------------------------------------------------------------------------- + IDL uses exceptions as a standard way to indicate error conditions. + Basically, an exception is defined much like an IDL structure, + and can contain an arbitrary amount of error information of + arbitrary type. + + Operations may raise more than one type of exception, and + must indicate all the exceptions they may possible raise. + It is illegal for an operation to throw an exception that is + not listed in the {\tt raises} expression. + + \newpage + Example: + \begin{verbatim} + module world + { + exception SuperError + { + }; + + exception FatalError + { + string message; + }; + + module europe + { + interface IFace + { + long op(in string name) raises (SuperError, FatalError); + }; + }; // end of module europe + }; + \end{verbatim} + + {\bf IDL does not support exception inheritance.} + That means that you cannot arrange error conditions into logical + hierarchies and catch all exceptions in a subtree by catching a + base exception. + + %----------------------------------------------------------------------------- \subsection{Inheritance} %----------------------------------------------------------------------------- + IDL interfaces can inherit from each other. A derived interface can be + treated as if it were a base interface, so in all contexts in which a + base interface is expected, a derived interface can actually be passed + at runtime (some call it polymorphism). ! \vspace{2mm} ! Example: ! \begin{verbatim} ! module america ! { ! interface SuperType1 ! { ! attribute long attr1; ! long op1(in string str); ! }; ! }; // end of module america ! ! module europe ! { ! interface SuperType2 ! { ! attribute long attr2; ! long op2(in string str); ! }; ! ! interface SubType : america::SuperType1, SuperType2 ! { ! attribute long attr3; ! long op3(in string str); ! }; ! }; // end of module europe ! \end{verbatim} ! ! As shown in the example, IDL supports multiple inheritance too. ! ! Note that any form of {\bf operation or attribute overloading is illegal} in IDL. Index: UserTypes.tex =================================================================== RCS file: /cvsroot/ccmtools/ccmtools/doc/manual/InterfaceDefinitionLanguage/UserTypes.tex,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** UserTypes.tex 15 Aug 2006 15:45:07 -0000 1.1 --- UserTypes.tex 24 Jan 2007 15:35:29 -0000 1.2 *************** *** 1,3 **** - % $Id$ %============================================================================= \section{User--Defined IDL Types} --- 1,2 ---- *************** *** 6,9 **** --- 5,10 ---- complex types: enumerations, structures and sequences. You can also use {\tt typedef} to explicitly name a type. + \vspace{5mm} + %----------------------------------------------------------------------------- *************** *** 14,20 **** existing type. Example: \begin{verbatim} ! typedef long TimeStamp; \end{verbatim} --- 15,25 ---- existing type. + \vspace{2mm} Example: \begin{verbatim} ! module world ! { ! typedef long TimeStamp; ! }; // end of module world \end{verbatim} *************** *** 31,42 **** An IDL enumerated type definition looks much like the C++ version. Example: \begin{verbatim} ! enum Color { ! red, ! green, ! blue ! }; \end{verbatim} --- 36,51 ---- An IDL enumerated type definition looks much like the C++ version. + \vspace{2mm} Example: \begin{verbatim} ! module world { ! enum Color ! { ! red, ! green, ! blue ! }; ! }; // end of module world \end{verbatim} *************** *** 49,62 **** %----------------------------------------------------------------------------- IDL supports structures containing one or more named members of arbitrary type, ! includeing user--defined complex types. Example: \begin{verbatim} ! struct TimeOfDay { ! short hh; ! short mm; ! short ss; ! }; \end{verbatim} --- 58,75 ---- %----------------------------------------------------------------------------- IDL supports structures containing one or more named members of arbitrary type, ! including user--defined complex types. + \vspace{4mm} Example: \begin{verbatim} ! module world { ! struct TimeOfDay ! { ! short hh; ! short mm; ! short ss; ! }; ! }; // end of module world \end{verbatim} *************** *** 70,76 **** Sequences are variable--length vectors that can contain any element type. Example: \begin{verbatim} ! typedef sequence<Color> Colors; \end{verbatim} --- 83,93 ---- Sequences are variable--length vectors that can contain any element type. + \vspace{2mm} Example: \begin{verbatim} ! module world ! { ! typedef sequence<Color> Colors; ! }; // end of module world \end{verbatim} *************** *** 78,80 **** platform. ! \newpage --- 95,98 ---- platform. ! \vspace{5mm} ! Index: Introduction.tex =================================================================== RCS file: /cvsroot/ccmtools/ccmtools/doc/manual/InterfaceDefinitionLanguage/Introduction.tex,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** Introduction.tex 15 Aug 2006 15:45:06 -0000 1.1 --- Introduction.tex 24 Jan 2007 15:35:29 -0000 1.2 *************** *** 1,14 **** - % $Id$ %============================================================================= \section{Introduction} %============================================================================= ! In the CCM Tools framework, a subset of CORBA's Interface Definition Language ! (IDL) is used to define components, interfaces and parameters. ! \dots ! Independent of the used implementation language (e.g. C++, Java, etc.) - \dots \newpage --- 1,23 ---- %============================================================================= \section{Introduction} %============================================================================= ! In the CCM Tools framework, a subset of OMG's Interface Definition Language ! (IDL3) is used to define components, interfaces and parameters, as shown in ! Fig.~\ref{figure:IDLSubSet}. ! \begin{figure}[htbp] ! \begin{center} ! \includegraphics [width=10cm,angle=0] {figures/IDLSubSet} ! \caption{ CCM Tools support a subset of OMG's Interface Definition Language.} ! \label{figure:IDLSubSet} ! \end{center} ! \end{figure} ! Using an explicit IDL, we can define the structure of component--based ! software systems completely independent of any particular programming ! language (e.g. C++ or Java). ! Also, a clear separation between system design and implementation is ! guaranteed. \newpage --- Components.tex DELETED --- Index: Modules.tex =================================================================== RCS file: /cvsroot/ccmtools/ccmtools/doc/manual/InterfaceDefinitionLanguage/Modules.tex,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** Modules.tex 15 Aug 2006 15:45:08 -0000 1.1 --- Modules.tex 24 Jan 2007 15:35:29 -0000 1.2 *************** *** 1,3 **** - % $Id$ %============================================================================= \section{Modules} --- 1,2 ---- *************** *** 6,18 **** Modules combine related definitions into a logical group and prevent pollution of the global namespace. - Identifiers in a module need be unique only within that module. ! Modules do not hide their contents, so you can use a type defined in one module ! inside another module. - Modules can contain any definition that can appear at global scope. In addition, modules can contain other modules, so you can create nested hierarchies. Modules can be reopened. Incremental definition of modules is useful if specifications are written by a --- 5,38 ---- Modules combine related definitions into a logical group and prevent pollution of the global namespace. Identifiers in a module need be unique only within that module. ! The IDL parser searches for the definition of an identifier from the ! innermost scope outward toward the outermost scope. ! ! \vspace{2mm} ! Example: ! \begin{verbatim} ! module world ! { ! /** Some IDL definitions */ ! }; ! \end{verbatim} In addition, modules can contain other modules, so you can create nested hierarchies. + \newpage + Example: + \begin{verbatim} + module world + { + /** Some IDL definitions */ + + module europe + { + /** Other IDL definitions */ + }; + }; + \end{verbatim} + Modules can be reopened. Incremental definition of modules is useful if specifications are written by a *************** *** 20,23 **** module, you can break the module into a number of separate source files). - \newpage \ No newline at end of file --- 40,60 ---- module, you can break the module into a number of separate source files). + \vspace{2mm} + Example: + \begin{verbatim} + module world + { + /** Some IDL definitions */ + }; + + // ... + + module world + { + /** Other IDL definitions */ + }; + \end{verbatim} + + The CCM Tools don't support global scope IDL definitions, thus, every IDL artefact + must be placed within at least one module. Index: SourceFiles.tex =================================================================== RCS file: /cvsroot/ccmtools/ccmtools/doc/manual/InterfaceDefinitionLanguage/SourceFiles.tex,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** SourceFiles.tex 15 Aug 2006 15:45:08 -0000 1.1 --- SourceFiles.tex 24 Jan 2007 15:35:29 -0000 1.2 *************** *** 1,3 **** - % $Id$ %============================================================================= \section{Source Files} --- 1,2 ---- *************** *** 10,14 **** %----------------------------------------------------------------------------- The names of source files containing IDL definitions must end in {\bf \tt .idl} ! (for example, we can define a file named {\tt Components.idl}). %----------------------------------------------------------------------------- --- 9,13 ---- %----------------------------------------------------------------------------- The names of source files containing IDL definitions must end in {\bf \tt .idl} ! (for example, we can define a file named {\tt ccmtools.idl}). %----------------------------------------------------------------------------- *************** *** 48,52 **** IDL constructs (modules, interfaces, type definitions) can appear in any order you prefer. ! However, identifiers must be declared befor they can be use. --- 47,51 ---- IDL constructs (modules, interfaces, type definitions) can appear in any order you prefer. ! However, identifiers must be declared before they can be use. *************** *** 81,84 **** --- 80,84 ---- can't have a leading underscore. + \vspace{2mm} Identifiers are case--insensitive but must be capitalized consistently. This rule exists to permit mappings of IDL to languages that ignore case in *************** *** 86,92 **** capitalized identifiers as distinct (e.g. C++, Java). IDL permits you to create identifiers that happen to be keywords in one or more implementation languages, but to make life easier, you should try to avoid IDL identifiers that are likely to be implementation language keywords. - \newpage --- 86,92 ---- capitalized identifiers as distinct (e.g. C++, Java). + \vspace{2mm} IDL permits you to create identifiers that happen to be keywords in one or more implementation languages, but to make life easier, you should try to avoid IDL identifiers that are likely to be implementation language keywords. Index: InterfaceDefinitionLanguage.tex =================================================================== RCS file: /cvsroot/ccmtools/ccmtools/doc/manual/InterfaceDefinitionLanguage/InterfaceDefinitionLanguage.tex,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** InterfaceDefinitionLanguage.tex 15 Aug 2006 15:45:07 -0000 1.1 --- InterfaceDefinitionLanguage.tex 24 Jan 2007 15:35:29 -0000 1.2 *************** *** 1,3 **** - % $Id$ %============================================================================= \chapter{Interface Definition Language} --- 1,2 ---- *************** *** 7,14 **** \input{InterfaceDefinitionLanguage/Introduction} \input{InterfaceDefinitionLanguage/SourceFiles} \input{InterfaceDefinitionLanguage/BasicTypes} \input{InterfaceDefinitionLanguage/UserTypes} - \input{InterfaceDefinitionLanguage/Modules} \input{InterfaceDefinitionLanguage/Interfaces} ! \input{InterfaceDefinitionLanguage/Components} --- 6,14 ---- \input{InterfaceDefinitionLanguage/Introduction} \input{InterfaceDefinitionLanguage/SourceFiles} + + \input{InterfaceDefinitionLanguage/Modules} \input{InterfaceDefinitionLanguage/BasicTypes} \input{InterfaceDefinitionLanguage/UserTypes} \input{InterfaceDefinitionLanguage/Interfaces} ! |
