Interactive
Software Engineering		 EiffelCOM

[ISE Home] [ Home ] [ Release Notes ] [ Technology Papers ] [ Installation Notes ] [ About Eiffel ]

Getting Started

This chapter explains how to use the EiffelCOM wizard to create COM components and to access existing components.
Creating a new COM component
The first tutorial describes creating a COM component from a COM definition file that is either an IDL file or a Type Library. The tutorial focuses on creating an in-process (DLL) component, called StringManipulator. The component exposes one interface IString that includes the functions ReplaceSubstring and PruneAll corresponding respectively to the features replace_substring and prune_all of the EiffelBase STRING and the property String that represents the manipulated string. The property can be set or read. Other languages will be able to access these features.
Step by step instructions
  • Launch the EiffelCOM Wizard (from the Start menu, open Programs then EiffelXX and click EiffelCOM Wizard)
  • Choose Create a new project from a COM definition.
  • Click Next
  • Choose Server code for a new component
  • Click Next
  • Click the top Browse button and open the file $EIFFEL5\examples\com\wizard\string_manipulator\string_manipulator.idl where $EIFFEL5 represents the path to your EIFFEL50 directory.
  • Click the bottom Browse button and select the directory where you want to create the project (later referenced as destination folder). Choose $EIFFEL5\examples\com\wizard\string_manipulator\generated where $EIFFEL5 represents the path to your EIFFEL50 directory. If you work on a Windows9x machine, please choose a directory with a shorter path, for example c:\string_manipulator because Windows9x are unable to handle long path names.
  • Click Next
  • Choose Automation
  • Click Next
  • Click Finish
  • Wait until the wizard is done.
First look at the generated code

At the end of the processing the wizard automatically launches EiffelBench with the generated project to help you navigate created Eiffel classes. You might want to look at the file generated.txt in the destination folder, which contains a list of files generated by the wizard. The file string_manipulator.log holds summary of the processing and error and warning messages.

The deferred class STRING_MANIPULATOR_COCLASS represents component functionality. It inherits from ISTRING_INTERFACE that corresponds to the IString interface. It has one descendant STRING_MANIPULATOR_COCLASS_IMP that implements the deferred features. The default implementation is empty.

implementing the component
To do something more interesting than merely return an error to a client edit the implementation of the STRING_MANIPULATOR_COCLASS_IMP class. The wizard would not overwrite this class in future executions. There is an implementation of the class in $EIFFEL5\examples\com\wizard\string_manipulator\server\. Copy this file over to $EIFFEL5\examples\com\wizard\string_manipulator\generated\server\component and freeze the project. Voila!, you have your first EiffelCOM component up and running.
Tips
  • To develop an EiffelCOM component you need to set the registry entry MELT_PATH because the system is not launched from the directory containing the byte code (by default EIFGEN\W_code). The EiffelCOM component client launches the server from its current location and causes the server to crash if the MELT_PATH key does not setup properly. To put this value in your registry, create a key under HKEY_CURRENT_USER\SOFTWARE\ISE\Eiffel45 with the same name as the name of your project (e.g. string_manipulator) and add the string value named MELT_PATH containing the path to the byte code (.melted file). You will find an example of such entry in the file melted_path.reg in $EIFFEL5\wizard\config. Edit this file as needed (replace string_manipulator with the name of your system and change the path to point on the correct location using `\\' as directory separator) and then double click on it to enter the information into the registry.
  • To test the component, you need to register it first. Register an in-process component via the regsvr32 utility using the following syntax: regsvr32 system_name.dll where system_name is the name of the dll (e.g. string_manipulator). Register an out-of-process component using the following syntax: system_name.exe -Regserver where system_name is the name of the component executable file.
  • To complete this tutorial you need to register the component with the following command (run from a dos console): regsvr32 string_manipulator.dll and to enter the information in $EIFFEL5\wizard\config\melted_path.reg. You have to change the content of this file if you have not installed Eiffel under C:\ and/or have used a different destination directory.
Creating a new component from an Eiffel project

The second tutorial describes creating a COM component from an Eiffel system. The tutorial example String is almost identical to StringManipulator of the previous tutorial. In the StringManipulator example the wizard starts from IDL file and builds an Eiffel System; in contrast, the String example takes an Eiffel system and generates an IDL file and the required plumbing code to make the Eiffel project accessible to COM runtime. You do not need to modify any Eiffel or C code.

Step by step instructions
  • Create a new Eiffel project in the directory $EIFFEL5\examples\com\wizard\e2idl\eproject where $EIFFEL5 represents the path to your EIFFEL50 directory.
  • Select Ace file from the same directory and compile.
  • Launch the EiffelCOM Wizard (from the Start menu, open Programs then EiffelXX and click EiffelCOM Wizard)
  • Choose Create a new project from an existing Eiffel project.
  • Click Next
  • Click Next again
  • Click the top Browse button and open the file $EIFFEL5\examples\com\wizard\e2idl\eproject\string.epr where $EIFFEL5 represents the path to your EIFFEL50 directory.
  • Click the second Browse button and open the file $EIFFEL5\examples\com\wizard\e2idl\ eproject\Ace.ace where $EIFFEL5 represents the path to your EIFFEL50 directory.
  • In the third entry field enter string_manipulator.
  • In the forth entry field enter root_cluster.
  • Click Next.
  • Click the Browse button and select the directory where you want to create the project (the destination folder). Choose $EIFFEL5\examples\com\wizard\e2idl\generated where $EIFFEL5 represents the path to your EIFFEL50 directory. If you work on a Windows 9x machine, please choose a directory with a shorter path, for example c:\e2idl.
  • Click Next
  • Choose Automation
  • Click Next
  • Click Finish
  • Wait until the wizard is done.
First look at the generated code
The only generated Eiffel class is COM_<Name_of_system>_REGISTRATION. You do not need to modify or implement any classes. The wizard produces a ready-to-use component.
Tips
  • In most Eiffel systems functionality is spread out throughout the system. No single class exposes the full functionality of the system and can serve as a Facade to the outside world. Running the wizard on any such class would not be practical. Before starting the wizard write an Eiffel class that acts as a Facade and forwards client calls to the appropriate sybsystems. Enter the Facade class name into "Enter Eiffel class name" field of the third dialog (Eiffel Project File Dialog). The wizard generates an IDL file from this class.
Accessing a component
The third tutorial describes how to access a COM component and build reusable library.
Step by step instructions
  • Launch the wizard
  • Choose Create a new project from a COM definition and click Next
  • Click Next again
  • Click the top Browse button and open the file $EIFFEL5\examples\com\wizard\string_manipulator\string_manipulator.idl where $EIFFEL5 represents the path to your EIFFEL50 directory. You could also choose to open the type library (.tlb) that was generated by the wizard when Creating a new COM component. in the destination folder of that first project.
  • Click the bottom Browse button and select the directory where you want to create the project (later referenced as destination folder). Choose $EIFFEL5\examples\com\wizard\string_manipulator\client\generated where $EIFFEL5 represents the path to your EIFFEL50 directory.
  • Click Next
  • Click Finish
  • Wait until the wizard is done.
First look at the generated code
At the and of the generation the wizard precompiles the generated code and open EiffelBench on the precompilation project. Note: a precompilation project is read-only, you need to start another EiffelBench to reuse the generated classes. The interesting classes are all related to the coclass proxy STRING_MANIPULATOR_PROXY. The proxy is the Eiffel class that gives access to the component. Each feature on the proxy calls the corresponding interface function on the component. You can use the EiffelBench opened by the wizard to browse through the generated classes and study the class hierarchy.

 

Implementing a client
To implement a client of the StringManipulator component open a new EiffelBench. Create the project in $EIFFEL5\examples\com\wizard\string_manipulator\client using the ace file found in that directory. Freeze and run the project. You are now accessing the previously built component and calling functions on its interfaces!. The class MY_STRING_MANIPULATOR inherits from the generated STRING_MANIPULATOR_PROXY and redefines the feature replace_substring_user_precondition. The generated interfaces include contracts for each exposed function. You can redefine the user_precondition features to implement your own preconditions.
Contracts
Contracts can be broken directly on the proxy in which case you will get a standard contract violation or in the server. If contracts are broken on the server then the exception will be forwarded by the EiffelCOM runtime to the client. The feature replace_substring_user_precondition in MY_STRING_MANIPULATOR includes the following commented line:
    -- Result := True
Un-comment this line by removing the preceding ` -- ' and comment out the rest of the feature. Now the contract of the replace_substring feature is wrong and erroneous calls can be made. Quick melt the changes and run the client. Enter some invalid numbers in the fields used to call this feature. After you click Replace you will see an error message box warning you that a precondition was violated on the server side. This is how you can use contracts `over the wire'. The preconditions was violated in the server, this exception was caught by the EiffelCOM runtime and sent back to the client.
Summary
You now have the basic knowledge needed to run the EiffelCOM wizard and produce or access COM components. The benefits of using the wizard are numerous including a fast and easy generation of "plumbing" code as well as enhanced debugging capabilities through the use of contracts. The wizard is also very generic, it can generate or wrap any kind of components. We hope you enjoy using it as much as we enjoyed developing it,
The EiffelCOM team.