IDL Importer

IDL Importer supports converting OMG (Object Management Group) IDL format files into ALFA.

IDL is converted to ALFA constructs as outlined below.

Furthermore, comments associated with IDL constructs are imported into ALFA. By convention, comments immediately before the IDL construct is considered documentation associated with that element. See example below, and screenshot of documentation.

IDL	ALFA
module	namespace
struct	record
typedef	typedef
const	const
interface	service
enum	enum
exception	@Exception record
[] - array	list
map	map<K,V>
union	union

Other specific IDL features are converted to the closest ALFA construct. For example an attribute defined in a interface in IDL is converted to ALFA service methods - get/set, depending on being readonly or not.

Given the numerous approaches to IDL and its versions, we recommend using the ALFA IDL importer and contacting us if you have any questions using info@schemarise.com.

IDL Import example

Java and Apache Maven (mvn command) is required to run this example.

1. Create an example IDL file, such as the one below and save as example.idl.

   // Example Bank Package
   module BankDemo {
           // Customer record
           struct CustomerDetails {
               // Customer Id
               string custID;
               // Last name
               string lname;
               // Firstname
               string fname;
               // Age
               short age;
           };
   
           // Bank API
           interface Bank {
               // Retrieve Customer record given Id
               CustomerDetails getCustomerDetails(in string custID);
           };
   };
   

2. Run the ALFA Maven CLI, import IDL to ALFA

   mvn com.schemarise.alfa.utils:alfa-maven-plugin:3.4.6:cli -Dalfa.importers=idl -Dalfa.output=generated -Dalfa.sourcepath=example.idl
   

3. Open the generated/example.alfa file, which is generated as shown below.

   Note the full definition, including comments as documentation have been imported.

   # Example Bank Package
   namespace BankDemo
   
   # Customer record
   record CustomerDetails {
       # Customer Id
       custID : string
       # Last name
       lname : string
       # Firstname
       fname : string
       # Age
       age : int
   }
   
   # Bank API
   service Bank
   {
       # Retrieve Customer record given Id
       getCustomerDetails( in custID : string ) : BankDemo.CustomerDetails
   }
   

Optional steps

• The generated ALFA file can be used as input for code generation, such as Markdown documentation.

  mvn com.schemarise.alfa.utils:alfa-maven-plugin:3.4.6:cli -Dalfa.exporters=markdown -Dalfa.output=docs -Dalfa.sourcepath=generated
  

• Open the docs folder in VSCode and Preview the index.md file.

• Markdown (*.md) files generated to HTML or using server-side formatting to HTML, can be hosted as a website to be viewed by users.