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.
| Nota: | en la versión de 32 bits de UModel, el nombre registrado o identificador programático (ProgId) del objeto COM es UModel.Application. Para la versión de 64 bits de UModel, el nombre es UModel_64.Application. Sin embargo, debe tener en cuenta que el programa que realiza las llamadas accede a las entradas de registro CLASSES de su propio subárbol o grupo (de 32 o 64 bits). Por tanto, si ejecuta scripts usando la línea de comandos estándar y el explorador de Windows en una instancia Windows de 64 bits, el programa accederá a las entradas de registro de 64 bits, que apuntan a la versión de 64 bits de UModel. Por eso, si tiene instaladas tanto la versión de 32 bits como la versión de 64 bits de UModel necesitará dar un rodeo para llamar a la versión de 32 bits. Por ejemplo, si el programa que realiza las llamadas es Windows Scripting Host, haga lo siguiente: |
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.