javalin.org

Javalin Classes

This document details the use of classes within Javalin. Probably the simplest way of explaining a Javalin class is by starting with a small example:

jpackage org.javalin.examples
jclass public, JMyClass
    private qword,   m_count
    public  method, JMyClass
    public  method, getCount
    public  method, setCount, qword new_count
    public  method, finalise
jendclass

The macro jpackage indicates that the classes we define in this particular source file belong to the package named org.javalin.examples. All class definitions for a package must be contained within the package's include file. The actual source code that implements the class methods must be contained in its own source file. Note however that a large class may be split into multiple source files with each file containing the class methods to be assembled. At a minimum there will be at least 2 separate files per package - one file containing the definitions of the classes and another file containing the code that implements the class methods. All packages must have a package definition import file. Most package projects will likely have many source files that implement the class methods of all classes contained within the package.

The macro jclass indicates the start of the class definition. The public keyword indicates that this particular class is visibile to all packages. If the private keyword were used instead then the class would not be accessible to other packages, only to other classes within its own package (eg: org.javalin.examples).

In this example we've named our class JMyClass. Note that the actual name of the class can be any name you wish. Prepending the uppercase letter J to the class name simply helps with identifying the class as being defined and instantiated with the Javalin system and is a recommended coding convention.

By default, unless specified otherwise, a class inherits from JObject. All classes defined within Javalin's inheritance chain eventually inherit from JObject. You can inherit the member variables and methods of another class simply by specifying the parent class name following the class name, like this:

jclass public, JMyClass, JMyParentClass  

When you inherit from another class then the package of the class being inherited from must be imported using the macro keyword jimport. This macro is similar in functionality to the include statement. Its job is to bring in the file that contains the definitions of all classes in the package that we can inherit from. If the class is contained within the same package then jimport is not needed because the jpackage macro will have already brought it in for us. For example, JMyParentClass is not a member of the same package as JMyClass so we must import like so:

jimport com.vendor.packagename

Contained within the jclass / jendclass bounding macros are the data types and methods associated with this class. The macro keywords public and private are required for each line of code and indicate the scope of visibility. The line private qword, m_count defines a class variable that is 8 bytes in size and is not visible outside this package. By encapsulating this variable we help prevent incorrect use by classes in other packages.

The next two lines show method definitions using the jmethod macro keyword. Note that both are public methods which indicates that the methods are visible and can be executed by all other classes. A method marked private can only be called by other methods contained within the same package. This particular example demonstrates the standard way of exposing public methods to manipulate private data to help insure data integrity.

To create, or instantiate, the example class object we use the jnew macro keyword. When we are finished with the object we call the jdelete macro. Calling a class method is done by using the macro jinvoke. The following code snippet shows this:

jnew JMyClass       ; create a new class object
mov rcx, rax        ; save the reference pointer (using  64 bit mode)
jinvoke rcx, JMyClass.getCount
mov rdx, rax        ; store count returned by method to register rdx
jdelete rcx         ; freeing the memory

Note that the two macros jnew and jdelete are responsible for allocating and freeing the memory that will contain the class object within the system. All class objects are instantiated using the heap. The register rax (eax for 32bit systems) is used by jnew to return the reference pointer (data type refptr). The refptr should be saved before using and then deleted when finished. Forgetting to delete the refptr will cause memory leaks. There is no automatic garbage collection performed by Javalin.