Guide to Annotations

NeuroKernel Applications may use a list of annotations to ease the code generation, configuration and caching. Here you will find the detailed explanation of each annotation used in NeuroKernel API. Some of these annotations can only be used with the main application class that extends the NApplication class.

Configure annotation is used to set the runtime preferences of a task. This annotation can only be used with application main class to be effective.

import com.neurokernel.client.*;
import com.neurokernel.system.annotation.Configure;
import com.neurokernel.system.annotation.LoadResources;
import com.neurokernel.system.annotation.Source;
 
@LoadResources(
     resources = {
        @Source(value = "resources/banner.png", name = "banner")
     }
)
@Configure(socketTransport=true)
public class ConfigureExample extends NApplication {
      @Override
      public void main(int argc, String[] argv) {
          NFrame mainFrame=getMainFrame();
          new NImageView(mainFrame, (NImage)getResource("banner"));
 
          mainFrame.setTitle("Configure");
          mainFrame.setBounds(20,20,200,200);
          mainFrame.setVisible(true);
      }
}

This annotation is used to create necessary bootstrap files for an application. It can only be used with classes extending NApplication. Both Remote and Executable annotations can be used at the same time. Remote annotation is used as target for generating bootstrap files if both are defined. Applications solely deployed to servlet container and require JRE to run at server side, does not need this annotation.

import com.neurokernel.client.*;
import com.neurokernel.system.constants.CodeSegment;
import com.neurokernel.system.annotation.Executable;
import com.neurokernel.system.annotation.LoadResources;
import com.neurokernel.system.annotation.Source;
 
@Executable (
        value = "Banner",
        version= "0.1",
        workerSupport=true,
)
@LoadResources(
     resources = {
        @Source(value = "resources/banner.png", name = "banner")
     }
)
public class ExecutableExample extends NApplication {
      @Override
      public void main(int argc, String[] argv) {
          NFrame mainFrame=getMainFrame();
          new NImageView(mainFrame, (NImage)getResource("banner"));
 
          mainFrame.setTitle("Executable");
          mainFrame.setBounds(20,20,200,200);
          mainFrame.setVisible(true);
      }
}

This annotation tells generator to exclude specified task container modules from the executable code to shrink the produced code size. This is for advanced development because wrong doing will break execution at some point. It is important to note that there must be either Excludes or Includes. Both can not be used, and first one defined will be taken and processed.

This annotation tells generator which task container modules to include in the executable code and omit the others to shrink the generated code size. This is for advanced development because wrong doing will break execution at some point.

Code segments are the designators of sub modules available in a task container which can be included or excluded from the executable code to shrink the size of the file generated. This enum class is used with Exclude and Include annotations.

This annotation is used to create necessary remotely accessible bootstrap files for an application. It can only be used with classes extending NApplication. Executable annotation will be ignored when Remote annotation is used. There is an internal Executable annotation definition in Remote annotation.

NeuroKernel meta tags generated for the remote application are listed below depending on the annotation configuration entered. An application may have more than one device implementation including a file system.

import com.neurokernel.client.*;
import com.neurokernel.system.annotation.*;
 
@LoadResources(
     resources = {
        @Source(value = "resources/banner.png", name = "banner")
     }
)
@Remote( 
     value="appcachedemo",
     executable = @Executable (
           version= "0.1",
           workerSupport=true,
     )
);
public class RemoteExample extends NApplication {
      @Override
      public void main(int argc, String[] argv) {
          NFrame mainFrame=getMainFrame();
          new NImageView(mainFrame, (NImage)getResource("banner"));
 
          mainFrame.setTitle("Remote Example");
          mainFrame.setBounds(20,20,200,200);
          mainFrame.setVisible(true);
      }
}

LoadResources tells bootstrap file generator to include the resources in the executable so that task can automatically load resources and make them available from getResource method of NApplication class. This includes all runtime targets. This annotation can only be used with application and container classes. For applications, which require JRE to execute at server side, this annotation can still be used but the resources must be manually put the required folders in the class path of the application.

import com.neurokernel.client.*;
import com.neurokernel.system.annotation.LoadResources;
import com.neurokernel.system.annotation.Source;
 
@LoadResources(
        resources = {
            @Source(value = "resources/myicon.gif", name = "appicon")
            @Source(value = "resources/banner.png", name = "banner"),
        }, 
        loadIcon = false
)
public class ResourcesExample extends NApplication {
      @Override
      public void main(int argc, String[] argv) {
          loadIcon(getResource("appicon"));
          new NImageView(getMainFrame(), (NImage)getResource("banner"));
          setVisible("Resources");
      }
}

Source annotation is used to define a source for a resource such as Image in LoadResources annotation

A Plugin application can define one or more devices to be used by the parent application. The advantage of using a device is the way the IPC is used. Although the event based communication is still available to use, devices also introduce RPC methods that can be called by parents. This makes the use same type devices by different applications from different authors to be used for the same purpose. The devices must have the same footprint by their name and method definitions. Some commonly used devices may be standardized by NeuroKernel Research via an NDR (NeuroKernel Device Request). NDRs will be considered after NeuroKernel is widely adapted by the community.

import com.neurokernel.system.ICallback;
import com.neurokernel.system.device.*;
import com.neurokernel.client.NApplication;
import com.neurokernel.system.constants.DataType;
import com.neurokernel.system.annotation.Device;
import com.neurokernel.system.annotation.Method;
import java.util.Date;
 
@Device(
        value="NDayTime", 
        type="DayTimeDevice", 
        methods={
            @Method(value="getTime",returnType=DataType.LONG),
            @Method(value="getDate",returnType=DataType.DATE)
        }
)
public class NDayTimeDevice extends NApplication {
 
    @Override
    public void main(int argc, String[] argv) {
         NDevice deviceInfo=getSystem().getDevice();
 
         deviceInfo.getDeviceMethod("getTime").
                setCallProcessor((response, args) -> System.currentTimeMillis());
 
         deviceInfo.getDeviceMethod("getDate").
                setCallProcessor((response, args) -> new Date());
    }
}

Devices can define any number of methods which are used for RPC (Remote Procedure Call). It is not used for implementation. It is used to create a device definition info so that it can be easily recognized and used by plugin container and plugin system itself.

An application can define and handle any number of devices in itself. This annotation is used to define multiple device profiles.

import com.neurokernel.client.*;
import com.neurokernel.system.device.*;
import com.neurokernel.system.annotation.*;
 
@DeviceArray(
        devices={
            @Device(
                    value="TempGauge", 
                    type="GaugeDevice", 
                    title="Temperature Gauge",
                    visual=true,
                    methods={
                        @Method(value="setValue",params=DataType.INTEGER),
                    }
            ),
            @Device(
                    value="NDayTime", 
                    type="DayTimeDevice", 
                    methods={
                         @Method(value="getTime",returnType=DataType.LONG),
                         @Method(value="getDate",returnType=DataType.DATE)
                    }
            )
        }
)
public class DeviceArray extends NApplication {
 
    @Override
    public void main(int argc, String[] argv) {
        NDevice deviceInfo=getSystem().getDeviceByType("DayTimeDevice");
 
        deviceInfo.getDeviceMethod("getTime").
            setCallProcessor( (response, args) -> System.currentTimeMillis());
 
        deviceInfo.getDeviceMethod("getDate").
            setCallProcessor((response, args) -> new Date());
 
        NGauge gauge=renderGauge(getMainFrame());
        getSystem().getDeviceByType("GaugeDevice").getDeviceMethod("setValue").
            setCallProcessor((response, args) -> {
               gauge.setValue((Integer)args[0],false);
               return null;
            });
 
        setVisible("Gauge Device");
    }
 
    private NGauge renderGauge(NContainer container) {
        NGauge gauge=new NGauge(container);
        gauge.setMinimum(-50);
        gauge.setMaximum(50);
        gauge.setName("Temperature");
        gauge.setStrokeTicks(false);
        gauge.setShadowGlow(true);
        gauge.setUnits("°C");
 
        gauge.setColor(NGauge.GaugePart.PLATE, new NColor(0x22,0x22,0x22));
        gauge.setColor(NGauge.GaugePart.MAJOR_TICKS, new NColor(0xf5,0xf5,0xf5));
        gauge.setColor(NGauge.GaugePart.MINOR_TICKS, new NColor(0xdd,0xdd,0xdd));
        gauge.setColor(NGauge.GaugePart.TITLE, NColor.WHITE);
        gauge.setColor(NGauge.GaugePart.NUMBERS, new NColor(0xee,0xee,0xee));
        gauge.setMajorTicks("-50","-40","-30","-20","-10","0","10","20","30","40","50");
        gauge.setValueBox(new NGaugeValueBox().setValueFormat(2,2));
        gauge.addColorRange(-50, 0, new NColor(0,255,0,50));
        gauge.addColorRange(0, 50, new NColor(255,0,0,50));
        gauge.setValue(0,false);
 
        container.setBackground(NColor.BLACK);
        return gauge;
    }
}

Applications can cache their protocol from the initial launch to up until the main window is fully visible on the screen. This will increase the launch speed of the applications because protocol is already created for the main window and stored. Protocol can be stored to persistent storage if available so that when the same application is executed again in a new session, system will pick its initial protocol from the persistent storage and immediately process it. Initial protocol for each window can also be cached to persistent storage. For remote applications, request to access to the data storage may be asked by the browser.

import com.neurokernel.client.*;
import com.neurokernel.system.annotation.*;
 
@ProtocolCache("ProtocolCache")
public class ProtocolCacheExample extends NApplication {
      @Override
      public void main(int argc, String[] argv) {
          NFrame mainFrame=getMainFrame();
          new NButton(mainFrame, "Hello");
 
          mainFrame.setTitle("Protocol Cache Example");
          mainFrame.setBounds(20,20,200,200);
          mainFrame.setVisible(true);
      }
}

NeuroKernel client side applications can be cached to the browser for offline access. This may be particularly useful if the site to the application is down. Service workers are supported including fallback to AppCache mode. There may be client based limitations that could be solved in a later version. Please take note that, the site must have an HTTPS certification for this to work.

import com.neurokernel.client.*;
import com.neurokernel.system.annotation.*;
 
@LoadResources(
        resources = {
            @Source(value = "resources/banner.png", name = "banner"),
        }
)
@Executable(
        cache = {
            @ApplicationCache(version = "1.0")
        }
)
public class AppCacheExample extends NApplication {
      @Override
      public void main(int argc, String[] argv) {
          NFrame mainFrame=getMainFrame();
          new NImageView(mainFrame, (NImage)getResource("banner"));
 
          mainFrame.setTitle("AppCache Example");
          mainFrame.setBounds(20,20,200,200);
          mainFrame.setVisible(true);
      }
}