Accessing the API
To access the COM API, a new instance of the Application object must be created in your application (or script). Once you have created the application object, you can start using the functionality of UModel. You will generally either open an existing document, create a new one, or access the active document (IDocument). IDocument corresponds to a UModel project and can be used to include sub-projects, generate documentation, synchronize model and code, while also giving access to the main UMLData objects, see also Object Model.
| Note: | When implementing a UModel IDE plugin, there is no need to create an instance of the application object, because UModel is already running and the current instance of the application object is provided by IApplication as parameter for all important methods of IUModelPlugIn. |
Prerequisites
To make the UModel COM object available in your Visual Studio project, add a reference to the UModel type library (.tlb) file, see How to Reference the UModel Type Library. A sample UModel API client in C# is available at: C:\Users\<username>\Documents\Altova\UModel2024\UModelExamples\API\C#.
In Java, the UModel API is available through Java-COM bridge libraries. These libraries are available in the UModel installation folder: C:\Program Files (x86)\Altova\UModel2024\JavaAPI (note this path is valid when 32-bit UModel runs on 64-bit Windows, otherwise adjust the path accordingly).
•AltovaAutomation.dll: a JNI wrapper for Altova automation servers
•AltovaAutomation.jar: Java classes to access Altova automation servers
•UModelAPI.jar: Java classes that wrap the UModel automation interface
•UModelAPI_JavaDoc.zip: a Javadoc file containing help documentation for the Java API
| Note: | In order to use the Java API, the .dll and .jar files must be on the Java classpath. |
A sample UModel API client in Java is available at: C:\Users\<username>\Documents\Altova\UModel2024\UModelExamples\API\Java.
In scripting languages such as JScript or VBScript, the UModel COM object is accessible through the Microsoft Windows Script Host (see https://msdn.microsoft.com/en-us/library/9bbdkx3k.aspx). Such scripts can be written with a text editor, and do not need compilation, since they are executed by the Windows Script Host packaged with Windows. (To check that the Windows Script Host is running, type wscript.exe /? at the command prompt). Several JScript example files that call the UModel API are available at: C:\Users\<username>\Documents\Altova\UModel2024\UModelExamples\API\JScript.
| Note: | For 32-bit UModel, the registered name, or programmatic identifier (ProgId) of the COM object is UModel.Application. For 64-bit UModel, the name is UModel_64.Application. Be aware, though, that the calling program will access the CLASSES registry entries in its own registry hive, or group (32-bit or 64-bit). Therefore, if you run scripts using the standard command prompt and Windows Explorer on 64-bit Windows, the 64-bit registry entries will be accessed, which point to the 64-bit UModel. For this reason, if both UModel 32-bit and 64-bit are installed, special handling is required in order to call the 32-bit UModel. For example, assuming that Windows Scripting Host is the calling program, do the following: |
1.Change the current directory to C:\Windows\SysWOW64.
2.At the command line, type wscript.exe followed by the path to the script that you would like to run, for example:
C:\Users\...\Documents\Altova\UModel2024\UModelExamples\API\JScript\Start.js |
Guidelines
The following guidelines should be considered in your client code:
•Do not hold references to objects in memory longer than you need them. If a user interacts between two calls of your client, then there is no guarantee that these references are still valid.
•Be aware that if your client code crashes, instances of UModel may still remain in the system. For details on how to handle error messages, see Error handling.
•Free references explicitly, if using languages such as C or C++. In C# and Visual Basic, GC.Collect() can be used to force garbage collection.
•UModel API collections are zero-based. For example, the statement myPackage.InsertPackagedElementAt(0, "Interface"); will insert a new interface as first child of the package.