Creating and using your own external Java library for your TotalCross Applications

If you have your own design components and want to use them in your application, this article is for you.

One of the biggest advantages of using the Java language is the variety of Design Patterns that allow you to reuse your written code within a lot of different projects. The possibility to create your own libraries can help you to implement these Design Patterns and save you a lot of time in the creation of your application. This article shows how you can create your Java library using TotalCross components, how to use this lib in your project, and, finally, how to deploy this lib on the device, together with your app.

Creating your own library

In TotalCross, the basic difference between a library and a regular project is the existence of one Java class extending the MainWindow. When creating a library, it is strongly recommended not to have any class extending the MainWindow, that way TotalCross will not make any mistake when running your app. On the other hand, you can create new UI components, extend the existing ones and use the entire TotalCross API to build a new API of components or to create rules of validation that can be reused in a lot of projects.

The library built in this sample is available at GitHub. It is a new project to allow developers to draw all the UI using Android Studio and run the Android XML directly on the device using TotalCross. The name of this lib is KnowCode.

As you can see, the structure of the project follows the same TotalCross Guideline but without a MainWindow and also with no “Application” class (class required to run the simulator).

These classes render the Android XML and load all the UI components, in real time.

For every different Android layout, there is a respective Java class to load the specific configuration and run properly on the device

Let’s build this project into a library to use in a different project. To achieve this, some configurations are needed in the Maven file, pom.xml:

1. Remove all the <platform> from the XML, as this is not a deployable application, there is no need to specify the target operating systems;
2. On <name> tag adds a suffix at the end of your project’s name <name>KnowcodeLib</name> This is needed to inform TotalCross, in the runtime, that this is a lib and that it needs to be loaded to run the application.

Your pom.xml should look like this, at the plugin section:

<plugin>
     <groupId>com.totalcross</groupId>
     <artifactId>totalcross-maven-plugin</artifactId>
     <version>1.1</version>
     <configuration>
         <name>KnowcodeLib</name>
         <activationKey>${totalcross.activation_key}</activationKey>
         <totalcrossHome>${totalcross.sdkPath}</totalcrossHome>
</configuration>
....

Using TotalCross Plugin for VSCode, you need to run the Package command. TotalCross will create one JAR and one TCZ file. The jar file will be used in the development/compiling time and the tcz will be used in runtime, together with your application. Your target folder should look like this:

Now, your library is ready to be used in any other project.

Using your first library

To finish this example, the project HomeApplianceXML will be used to show how to add the KnowCodeXML dependency, this project is also available at Github. If you like, you can take a closer look at this technology in this video.

This project only has two Java classes, as KnowCodeXML, the library, abstract most operations. The structure of this project should look like this:

1. HomeApplianceXML.java — MainWindow that uses XmlContainerFactory to load the Android XML;
2. HomeApplianceXMLApplication.java — Application class to run the TotalCross Simulator

At the resources folder, the images and Android XML will be placed.

To add the KnowCodeXML dependency in the project, let’s change the maven configuration file pom.xml adding a new <dependency> tag inside the <dependencies> tag.

<dependencies>
........
   <dependency>
     <groupId>com.totalcross.knowcode</groupId>
     <artifactId>totalcross-knowcode</artifactId>
     <version>0.0.1</version>
     <systemPath>YOUR PATH HERE/Knowcode.jar</systemPath>
     <scope>system</scope>
   </dependency>
.......

Here is a short explanation about the tags:

1. GroupID — Usually your package name (your URL backward);
2. ArtifactID — Name of the artifact. The combination groupID + artifactID should be unique;
3. Version — Version of your lib;
4. System Path — location of the Jar file.
5. Scope — This tag indicates how your lib will be used and where maven can find it.

The last two tags are not an obligation. If you publish your libs at Maven repository, you don’t need to inform them. As this configuration is local, they need to be set up.

After this config and compiling the project again, the compiling error should be gone and you can run the TotalCross simulator. The Home Appliance interface should appear:

Running on the device

Last part: let’s run the application on the device!!

As explained before, TotalCross doesn’t use anything from Java to run the application on the device. Java is just the programming language. That said, the application will not use the JAR file in the runtime.

On the target folder of the KnowCodeXML project, you can find the KnowCodeLib.tcz. TotalCross converts the Java bytecodes to its optimized bytecode and instead of “.jar”, the binary extension is “.tcz”.

To add the KnowCodeLib.tcz, you need to create a new file at the root folder of your project, the filename should be “all.pkg” and inside it, you should right the location of the tcz file as indicated below:

[L]YOUR PATH/KnowcodeLib.tcz

the [L] is an internal TotalCross configuration to set where the file will be placed.

After that, you can run the Package command from the VSCode plugin. The target folder should look like this:

And your application should be ready to run in any device! =)

Conclusion

The benefits of applying Design Patterns and reuse of code in projects are well-known in the development community and the usage of Java Libraries makes this task easier.

This article shows how to create your Java libraries with TotalCross, extending existing components and making it possible to reuse your code and speed up your app development process.

What do you think about sharing code between your applications? Which Design Pattern is your favorite? Join the discussion at our social networks and also leave your comments here =)