Element Structure

Here's where you learn to develop your first Element.

Starting with Elements 3.0, we are now providing a way to develop custom extensions in Java Virtual Machine (or JVM) based languages. Refer to the Wikipedia page for a complete list and determine the best language which works for your project. The most popular choices are Java and Kotlin. Elements is natively written in Java which is 100% compatible with any other JVM based language.

We call our fundamental plug-in an Element. Each Element runs in an isolated environment using a ClassLoader which isolates Element from the rest of the system. A common problem Java developers face is conflicting dependencies within a single application, colloquially known as "Jar Hell."

Our approach allows you to use develop in an environment without having to worry about conflicts between the Elements 3.0 code base and your Element's code. We provide a set of interfaces, but isolate their implementations from your code. When developing an Element, these are the key points you must know:

• You can incorporate almost any existing Java code base into Elements that are based on standard Java frameworks. Elements 3.0 Currently Supports:

  • Jakarta RS 4.0.0

  • Jakarta Websockets 2.1.0

• You can include almost any third-party library into your code base without having to worry about it conflicting with the frameworks used to build Elements

  • Note: You will need to copy all dependencies into your Element, except those as provided by Elements 3.0.

• An Element does not have strict isolation, nor does it run in a sandbox. This is by design, as trying to enforce strong encapsulation using a Security Manager (or similar) would introduce a lot of overhead for no benefits. Take special care when accessing the System ClassLoader.

Defining an Element

An Element exists as a Java package and, optionally, include all sub-packages recursively. Elements are similar to JPMS Modules but without the one jar per module restrictions.

The following example shows how to define an Element in your Java code. Note we do require that you define a package-info for the package. The following is the simplest Element possible.

package-info.java

// Defines the Package. Specifies as recursive.
@ElementDefinition(recursive = true)
package com.mystudio.mygame.api;

// Imports the Element SDK Annotation
import dev.getelements.elements.sdk.annotation.Element

This indicates that the package com.mystudio.mygame.apiand all sub packages will be included in the Element for associated services.

Packaging an Element

Packaging an Element or collection of Elements uses a simple directory structure. Elements 3.0 will search for the following files and directories when loading the assets associated with an Element:

• dev.getelements.element.attributes.properties - A standard Java Properties file which define the Element's application

• libs - A directory containing jar files. The loader scans the directory for jar files and adds them to the Element's classpath.

• classpath - A directory containing assets to add directly to the Element's classpath.

Additionally, the following rules apply when scanning a directory for Elements.

• Any file not otherwise specified would be ignored.

• Any directory will be treated as a new Element, provided that that at least libs or classpath exist.

  • Note: Elements defined in directories will inherit the classpath of the parent which allows you to put common code in the parent directory.