Usage

Preamble¶

Using the cloudconnector, either as a Command Line Interface (CLI) or as a Maven plugin, uses a similar configuration.

Download the example.

Setting up a Generator¶

For this example we will use a REST client generator and as input an openAPI file.

General configuration¶

It is always necessary to use a configuration for the cloudconnector.

Configuration File¶

CLI¶

The configuration file is a standalone XML file. Per default it is named cloudconnector.xml, but it is possible to use any name. Then the configuration is specified with cloudconnector -f file.xml.

<cloudconnector
    xmlns="https://virtual-developer.com/schema/cloudconnector"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://virtual-developer.com/schema/cloudconnector
        https://maven.virtual-developer.com/repository/cloudconnector/2.1/cloudconnector.xsd">
  <account>company</account>
  ...
</cloudconnector>

Maven¶

The configuration will be inside the configuration section of the plugin.

<build>
  <plugins>
    <plugin>
      <groupId>com.vd</groupId>
      <artifactId>cc-maven-plugin</artifactId>
      <version>2.1.2</version>
      <executions>
        <execution>
          <goals>
            <goal>generate</goal>
          </goals>
        </execution>
      </executions>
      <configuration>
        <account>company</account>
        ...
      </configuration>
    </plugin>
  </plugins>
</build>

Account¶

The account will be used to login to the Virtual Developer platform. If your login URL is for example https://company.virtual-developer.com then you can just use company inside the account tag. This will make the cloudconnector connect to virtual-developer.com with the account company.

<account>company</account>

If you don’t use virtual-developer.com to login (private installation), you need to remove the account tag and specify the identity provider and the connection.

<connection>https://company.virtual-developer.com</connection>
<identityProvider>https://id.virtual-developer.com/auth/realms/company</identityProvider>

The connection is now the URL where you login. And the identity proivder is an OIDC endpoint.

You can either login with an openID Token (recommended) or with username and password.

OpenID Token¶

The first time the cloudconnector is started you will be promted with and URL you have to open. Open the URL in your browser, login with you credentials and copy the Token. Then the token is pasted into the prompt.

The cloudconnector now saves a token in your home folder (~/.vd) and will in addition runs always use the token to login.

Password¶

If it is not possible to use the OpenID Token (e.g. in an build) you can also use username and password.

CLI

cloudconnector -u username -p password

Maven

The first time the maven cloudconnector is run it will output the specific section for your settings.xml.

<servers>
  <server>
    <id>company.virtual-developer.com</id>
    <username>username</username>
    <password>password</password>
  </server>
</servers>

Generator ID and Version¶

For this example we use the generator with the ID com.gs.vd.gen.java.retrofit.openapi and the version 1.0.

Show Generators¶

CLI¶

After the cloudconnector.xml file is created with the account settings, it is now possible to list the available Generators.

cloudconnector -l

Maven¶

Not available with Maven.

Virtual Developer¶

Coming soon.

Settings¶

Now the configuration will be expanded with an generator section.

<account>company</account>
<generator>
  <id>com.gs.vd.gen.java.retrofit.openapi</id>
  <version>1.0</version>
</generator>

Note

Only the major and minor number is used for the version. So the newest generator with this version is always selected. It is also possible to use the full version. Then the generator with this specific version is used, which will probably be updated (and then removed).

Model files¶

The generator needs some input to run the generator.

Generic Model files¶

The model files are added to the generator.

<account>company</account>
<generator>
  <id>com.gs.vd.gen.java.retrofit.openapi</id>
  <version>1.0</version>
  <models>
    <!-- <model>model.yaml</model> -->
    <model>petstore.json</model>
  </models>
</generator>

For this example we can use the Petstore as model.

Modeler¶

If the Virtual Developer Modeler is used for modelling there is a special section to add the ID of the model.

<account>company</account>
<generator>
  <id>com.gs.vd.gen.java.retrofit.modeler</id>
  <version>1.0</version>
  <modeler>
    <elements>1524,24563</elements> <!-- Only select an element (comma separated list) -->
    <modules>12354</modules> <!-- Select a module (comma separated list) -->
    <models>12564</models> <!-- Select a model (comma separated list) -->
    <generations>1215</generations>  <!-- Select a generation input (comma separated list) -->
  </modeler>
</generator>

Virtual Project Mapping¶

The Virtual Poject Mapping is used to tell the generator where to generate the parts of the source code

Show Virtual Projects¶

CLI¶

Coming Soon.

Maven¶

Not available with Maven.

Virtual Developer¶

Coming soon.

Settings¶

The project mapping is also added to the generator section. The directory tag is optional. If it is skipped the code will be generated into the same directory as the configuration file. If it is present, the code will be generated into the directory.

<account>company</account>
<generator>
  <id>com.gs.vd.gen.java.retrofit.openapi</id>
  <version>1.0</version>
  <models>
    <model>petstore.json</model>
  </models>
  <projects>
    <project>
      <virtualProject>Rest Client Interfaces</virtualProject>
      <directory>interface</directory>
    </project>
    <project>
      <virtualProject>Rest Client Classes</virtualProject>
      <directory>classes</directory>
    </project>
  </projects>
</generator>

Note

If the wrong virtual project is used, the cloudconnector will issue a corresponding error message and list the available virtual projects. It follows that if you do not know the virtual projects for this generator, simply use any one and let the cloud connector tell you the correct one.

First run¶

With this configuration it is now possible to run the cloudconnector to generate code.

CLI¶

cloudconnector

Maven¶

mvn clean generate-sources

Generator Opptions¶

Show Generator Options¶

CLI¶

cloudconnector -o

This will print all available options

Maven¶

Not available with Maven.

Virtual Developer¶

Coming soon.

Set general Generator Options¶

For this example we will change the namespace, this will result in an changed package name. The options are also added to the generator section.

<account>company</account>
<generator>
  <id>com.gs.vd.gen.java.retrofit.openapi</id>
  <version>1.0</version>
  <models>
    <model>petstore.json</model>
  </models>
  <projects>
    <project>
      <virtualProject>Rest Client Interfaces</virtualProject>
      <directory>interface</directory>
    </project>
    <project>
      <virtualProject>Rest Client Classes</virtualProject>
      <directory>classes</directory>
    </project>
  </projects>
  <options>
    <option>
      <name>namespace</name>
      <value>com.company.petstore</value>
    </option>
  </options>
</generator>

If the cloudconnector is now rerun the source code will be in the namesapce com.company.petstore.

Set Generator Options for a Virtual Project¶

It is also possible to change the options only for a Virtual Project. For this example we will change the source folder of the interface project from src/main/java to src/interface/java.

<account>company</account>
<generator>
  <id>com.gs.vd.gen.java.retrofit.openapi</id>
  <version>1.0</version>
  <models>
    <model>petstore.json</model>
  </models>
  <projects>
    <project>
      <virtualProject>Rest Client Interfaces</virtualProject>
      <directory>interface</directory>
      <options>
        <option>
          <name>target.uri.prefix</name>
          <value>src/interface/java</value>
        </option>
      </options>
    </project>
    <project>
      <virtualProject>Rest Client Classes</virtualProject>
      <directory>classes</directory>
    </project>
  </projects>
  <options>
    <option>
      <name>namespace</name>
      <value>com.company.petstore</value>
    </option>
  </options>
</generator>

If the cloudconnector is now rerun the source code of the interface will be in the source folder src/interface/java.

Additional Options¶

Timeouts¶

Set the connection and read timeout. Useful when timeouts occur during the execution of the cloudconnector.

<connectionTimeout>10000</connectionTimeout>
<connectionRWTimeout>20000</connectionRWTimeout>

Fail Fast¶

Can be used to immediately stop the generation task when an error occurs.

<failFast>true</failFast>

Charset¶

Set the charset of the files.

<charset>UTF-8</charset>

Report Directory (only CLI)¶

Set the report directory.

<reportDir>report</reportDir>

Parallel¶

Set with the parallel transfomration jobs, how many jobs should run in parallel. Set with the prallel transfomration files how many files should be transformed in one step.

<parallelTransformationJobs>4</parallelTransformationJobs>
<parallelTransformationFiles>8</parallelTransformationFile

Usage

Preamble¶

Setting up a Generator¶

General configuration¶

Configuration File¶

CLI¶

Maven¶

Login¶

Account¶

First Login¶

OpenID Token¶

Password¶

Generator ID and Version¶

Show Generators¶

CLI¶

Maven¶

Virtual Developer¶

Settings¶

Model files¶

Generic Model files¶

Modeler¶

Virtual Project Mapping¶

Show Virtual Projects¶

CLI¶

Maven¶

Virtual Developer¶

Settings¶

First run¶

CLI¶

Maven¶

Generator Opptions¶

Show Generator Options¶

CLI¶

Maven¶

Virtual Developer¶

Set general Generator Options¶

Set Generator Options for a Virtual Project¶

Additional Options¶

Timeouts¶

Fail Fast¶

Charset¶

Report Directory (only CLI)¶

Parallel¶