Eqela Core API and Utilities

Copyright © 2012 Job and Esther Technologies, Inc.
(2) CORE APIS AND
UTILITIES

Eqela core application
framework (eq.api)

eq.api.Object
Base class for all objects (generic)
Automatically assumed as the base class
Declared as “fundamental”
Lightweight

class MyClass
{
// class body
}
class MyClass : Object
{
// class body
}
class MyClass : eq.api.Object
{
// class body
}
eq.api.Object: Examples

public void process_object(Object o) {
if(o is String) {
; // Do string actions
}
if(o is Buffer) {
; // Do buffer actions
}
// etc.
}
Object as a generic type

eq.api.PropertyObject
Ability to add arbitrary properties of various data
types to an object
An object property is something that is identified by a
string name, and with associated data in any data
type
Common way of using is to inherit or by construction

var o = new PropertyObject();
o.set("object", new Object());
o.set_int("integerproperty", 100);
o.set_bool("value_as_boolean", false);
var obj = o.get("object");
var intp = o.get_int("integerproperty", 55); // NOTE: Default value
var b = o.get_bool("value_as_boolean");
eq.api.PropertyObject: Examples
var m = o.synchronize();
// perform operations on shared data
if(m != null) {
m..unlock();
}

eq.api.SignalObject
Ability to configure arbitrary signal/listener constructs for
a class
Signals do not need to be explicitly declared
A signal with any name may be triggered at any time

// Connecting to a signal
var so = new SignalObject();
so.connect_signal("customsignal", myhandler);
// Triggering a signal
so.trigger_signal("customsignal", “optional parameter”);
// Declaring a signal handler
class MyHandlerClass : SignalHandler {
public Object on_signal(Object origin, String sigid, Object parameter) {
Log.message("Got a signal");
return(null);
}
}
eq.api.SignalObject: Examples
The “myhandler” object could be an instance of the class MyHandlerClass
implementing "eq.api.SignalHandler", which must implement a single method
on_signal()

Dynamic object creation

Normally classes are instantiated into objects with the new
operator

Alternative way to create objects

With specific return type
var object = new ClassName();
var object = ObjectFactory.create("custom.module.ClassName");
var object = ObjectFactory.create("custom.module.ClassName") as SignalObject;

What is a primitive type?

Primitive types
● Built in to the language as basic building blocks, and
cannot be extended by the programmer. Passed by
value in method calls.
● strptr, ptr, void, double, bool, int, long, byte
strptr var_name = “abc”.to_strptr();
ptr var_name = null;
double var_name = 123.45;
bool var_name = true;
int var_name = 100000;
long var_name = 100000;
byte var_name = 100;
void //refers to no data type at all

Primitive objects
In themselves, primitive types are NOT objects
Primitive types can be passed as an object by using the
following interfaces:
eq.api.Integer
eq.api.Double
eq.api.Boolean
A class that implements all these interfaces is
eq.api.Primitive

// To make objects out of primitive types.
var p_double = Primitive.for_double(100.5);
var p_int = Primitive.for_integer(100);
var p_bool = Primitive.for_boolean(false);
// Converting objects to primitive types
double val_double = ((Double)p_double).to_double();
int val_int = ((Integer)p_int).to_integer();
bool val_bool = ((Boolean)p_bool).to_boolean();
Primitive objects: Examples
public void my_method(Object obj) {
var obj_double = obj as Double;
if(obj_double != null) {
var val_double = obj_double.to_double();
}
// same way for Integer and Boolean types
}

In Eqela, strings are objects designed to
represent a sequence of characters
An Eqela string object is immutable, therefore
“modifying” a string creates a new object, and will not
change the original
Strings

String objects
A string in Eqela is an object instance of a class that
implements the interface eq.api.String
A String object encapsulates the primitive type strptr, which
is rarely used outside of embedded programming language
code
The easiest way to create a string is to write:
You can also directly call string methods:
var strobject = "This is a string";
var substring = "This is a string".substring(5, 2); // "is"

Constructing strings
var strobject = "This is a string";
var secondobject = strobject.append(" and this one");
What are the values of the two objects below?

Constructing strings
var sb = StringBuffer.create();
sb.append("This ");
sb.append("is ");
sb.append_c('a');
sb.append_c(' ');
sb.append("string");
var as_string = sb.to_string();
A more efficient way to construct a string from
components is to use eq.api.StringBuffer:

Formatting strings
Another way to construct strings is through the use of
string formatting
This can be done through the eq.api.StringFormatter
interface and the built-in printf() method of String
objects
The syntax is familiar to C programmers as being the
same as that of the classic C printf() function

var mystring = "This is %s. Very nice".printf().add("Hello").to_string();
Formatting strings: Example
var anotherstring = "Integer %d and double %f".printf()
.add(Primitive.for_integer(100))
.add(Primitive.for_double(15.64)).to_string();
What are the resulting strings in these cases?

Memory allocation and buffers

eq.api.Buffer

Eqela API supports arbitrary memory buffer
management through the Buffer interface

eq.api.Buffer

An instance of Buffer represents a chunk of memory
of a certain size, wherein the size is measured in
bytes.

A buffer instance has two main characteristics:
− The size of the buffer in bytes
− A pointer to the beginning of the buffer

eq.api.DynamicBuffer

Allocating a chunk of memory can be done through the
use the DynamicBuffer interface

An eq.api.DynamicBuffer is also an instance of
eq.api.Buffer (Buffer is a prerequisite of DynamicBuffer)

Example: To allocate a buffer of 100 bytes:
var mybuffer = DynamicBuffer.create(100);

eq.api.Pointer

To perform operations on a Buffer, use the Pointer
interface

Supports the basic operations such as set_byte(), get_byte()
and cpyfrom()

Example:
int n;
var ptr = mybuffer.get_pointer();
if(ptr != null) {
for(n=0; n<mybuffer.get_size(); n++) {
ptr.set_byte(n, n);
}
}

Collections

Arrays and linked lists
Implemented through types eq.api.Array and
eq.api.LinkedList
Both have eq.api.Collection as prerequisite
eq.api.Collection provides all commonly used features
for manipulating the data

Collections: Examples
var myarray = Array.create();
var mylinkedlist = LinkedList.create();
public void addmethod(Collection c) {
c.add("Hello");
c.add("world");
}
addmethod(myarray);
addmethod(mylinkedlist);
The create() method is used to construct an instance of these types:
You could define a method like this to add data:
The addmethod() could be called like this:
The add() method accepts the data type "eq.api.Object", thus any class that
derives from "eq.api.Object" can be added

Queues and Stacks
Implemented through eq.api.Queue and eq.api.Stack
Both provide push(), pop() and peek() methods and can
be created using their static create() methods
These classes do not implement the collection interface
like arrays and linked lists

What is a HashTable?

eq.api.HashTable
Allows for creating collections of key-value pairs
The key is a string, and the values can be quickly looked
up using the string
var myhashtable = HashTable.create();
myhashtable.set("key1", "First");
myhashtable.set("key2", "Second");
var ff = myhashtable.get("key2");
The variable "ff" would contain a reference to the String object holding
the value "Second"

Iterators
The framework provides a generic way to iterate over
collections of data
This functionality is used in many places throughout the
framework, in eq.api.Collection, eq.api.LinkedList, etc.
eq.api.Iterateable interface defines a single method iterate()
that can be used to obtain an instance of eq.api.Iterator
The Iterator class has a single method next(), which returns
an eq.api.Object

Iterators: Example
var ll = LinkedList.create();
ll.add("first");
ll.add("second");
var it = ll.iterate();
if(it != null) {
Object o;
while((o = it.next()) != null) {
Log.message(o);
}
}
This would print the two entries "first" and
"second" on the output terminal

Iterators: Example using foreach
var ll = LinkedList.create();
ll.add("first");
ll.add("second");
foreach(Object o in ll) {
Log.message(o);
}
Functionally equivalent to the previous, but with
much less code due to use of the foreach
structure

Logging and debugging (eq.api.Log)
Provides message output and logging facilities in all
supported environments
Four main methods:
message()
error()
warning()
debug()
Log.message("This is my message");

Accessing environment variables
Environment variables are a special facility supported on
many platforms to relay variables from a parent process to a
child process
Accessed via eq.api.SystemEnvironment
Methods to interact with environment variables:
get_env_vars()
get_env_var()
set_env_var()

var se = SystemEnvironment.instance();
if(se != null) {
se.set_env_var("EQ_DEBUG", "yes");
var val = se.get_env_var("EQ_DEBUG");
if(val != null && val.equals("yes")) {
Log.message("it worked");
}
}
Environment variables: Example

System clock
Gives access to the current time, as known by the
system/device that the program is running on
The access is provided by eq.api.SystemClock
Methods to retrieve current time:
seconds()
timeval()

Timers
A "timer" is a way of scheduling code to execute at some
later time
The Eqela API provides a facility to create any number of
timers through the "eq.api.EventLoop" type

Timers: Example
// start a timer
var el = EventLoop.instance();
if(el != null) {
var timer = el.start_timer(1000000, handler, null);
}
// An object of this class could be used as a handler:
class MySampleHandler : Timer
{
public bool on_timer(Object arg) {
Log.message("TIMER!");
return(false);
}
}
The object "handler" must be an instance of a class implementing
"eq.api.Timer", which must implement a single method on_timer()

Executing other programs
Eqela provides a mechanism to interact with other programs
on the system
Depends on the platform where this is supported
Implemented through the following types:
eq.api.ProcessManager (Enabling type)
eq.api.ChildProcessCommand (Specifies the command,
process and other parameters for executing the command)
eq.api.ChildProcess (Represents a child process)

Executing programs: Example
// To execute other programs:
var child = ChildProcess.start(ChildProcessCommand.create()
.set_command("firefox"));
int r = ChildProcess.execute(ChildProcessCommand.create()
.set_command("cat /proc/cpuinfo"));
On most computer platforms, this would result in looking for this command in
the PATH, then executing it
It is also possible to execute a command, wait
for it to finish, and then return an integer-based
return value:

Mathematics support

eq.api.Math

Provides mathematical functions, methods and
operations.

To access the mathematical functions:
* For a full reference of the functions, please refer to the Eqela API reference.

eq.api.MathConstant

Provides common mathematical constants.

It does not need to be specifically created.
var math = Math.instance();
var sinpi = math.sin(MathConstant.M_PI);

Generic I/O framework


Readers and writers

The input / output framework in the Eqela API is
fundamentally very much based on the concept of
readers and writers.

eq.api.Reader
− read()

eq.api.Writer
− write()

eq.api.ReaderWriter
− Shortcut for a class that is both a Reader and a Writer.


String reader

Can be used to treat a string as a Reader.
Example:
* This allows the string to be treated the same way as a file or network socket would.
var rd = StringReader.create("This is my string");


Buffer reader

Takes an arbitrary in-memory buffer, and treats it as a
Reader.

Buffer writer

Takes an arbitrary in-memory buffer, and treats it as a
Writer
var buf = DynamicBuffer.create(1000);
var rd = BufferReader.create(buf);
var wr = BufferWriter.create(buf);


eq.api.InputStream

Enables buffered reading and convenience methods
for reading specific kinds of data.

readline()
− per-line reading of text

nextbyte() and getbyte()
− per-byte reading of text

read_all_buffer() and read_all_string()
− read the entire contents to either a buffer or a string
var ins = InputStream.create(StringReader.create("my string to read"));
var str = ins.read_all_string();


eq.api.OutputStream

Similar to input stream, it can be used to print strings,
lines, and/or buffers to a writer.

It could be used as follows:
* The string "Hello world" would be printed, along with a corresponding newline
character, to the buffer.
var os = OutputStream.create(BufferWriter.create(buf));
os.println("Hello world");

Standard I/O streams

Standard I/O streams

Eqela supports the concept of "stdin", "stdout" and
"stderr".
− popularized by C standard I/O library (stdio)

eq.api.Stdin

eq.api.Stdout

eq.api.Stderr

To create streams:
var stdin = Stdin.create(); // of type eq.api.Reader
var stdout = Stdout.create(); // of type eq.api.Writer
var stderr = Stderr.create(); // of type eq.api.Writer
To create readers and writers to
supply standard I/O streams where
they are available

Filesystem access

Filesystem access

The Eqela file path notation

Eqela uses the "/" character as a file name separator on all
platforms.

The first component of the path name is special,
and is interpreted by Eqela.
Common File
Paths
Description
/my
Refers to the user's home directory, or a Documents directory, or some other
place that is reserved for the user's files
/app
Refers to the directory where the application itself is installed, and where its
data files are.
/tmp Refers to a directory where an application may write temporary files.
/native Refers to the filesystem of the underlying operating system.

Filesystem access
Example:
− On a Linux system
To access the system C compiler:
/native/usr/bin/gcc
− On Microsoft Windows:
To access the commonly used “C:Program Files”:
/native/c/Program Files

Filesystem access

The File class

The normal way to access files in an Eqela application is
via the eq.api.File class.

Two ways to construct a File object:
1. Using an Eqela path:
2. Using a platform native file path:
* The path separator used for Windows system is “”.
* Objects file1 and file2 refer to the same file.
var file1 = File.for_eqela_path("/native/c/program files/testfile.txt");
var file2 = File.for_native_path("C:Program Filestestfile.txt");

 Eqela also supports flexibly configured file systems
− (Virtual, network based, local or something else)
 The file system can be used in Eqela as long as
there is a class that implements the
eq.api.FileSystem.
 To construct File objects pointing to files on a
specific filesystem, one can use the File.instance()
method:
var file = File.instance("/dir/file.txt", my_file_system);
Filesystem access

Filesystem access

Reading a file

An "eq.api.Reader" object can be obtained for a file
using the read() method:
* This would read the contents of the file "text.txt" within the user's files into the string
variable "str"

Writing a file

Writing a file can be done through either the write()
method or the append():
var ins = InputStream.create(File.for_eqela_path("/my/text.txt").read());
var str = ins.read_all_string();
var os = OutputStream.create(File.for_eqela_path("/my/hello.txt").write());
os.println("Hello world");

Filesystem access

Reading directory entries

An application can iterate over files and directories in the
filesystem using the entries() method:
foreach(File path in File.for_eqela_path("/my").entries()) {
Log.message(path);
}

Pipes

Allows an execution of an external program or
command on the underlying system.

eq.api.Pipe

Turns its output into an InputStream that can be read by the
program.

To create a Pipe InputStream:

The piped command can be returned as a string through
the use of the read() method:
var pipe = Pipe.execute("ls /usr/bin");
Log.message(Pipe.read_string("ls /usr/bin"));
var buffer = Pipe.read_buffer("ls /usr/bin");

Multithreading

Starting a new thread

Implemented through the eq.api.Thread and
eq.api.Runnable classes.

Usage:
1. Call the static start() method in the
“eq.api.Thread” class.
2. Supply to it an instance of a class implementing
the "eq.api.Runnable" interface.

A class that implements Runnable interface:
To execute a new thread:
class MyRunnable : Runnable
{
public void run() {
Log.message("In a new thread");
}
}
Thread.start(new MyRunnable());
Multithreading: Example

Multithreading

Thread synchronization / locking

This can be done through eq.api.Mutex type.
− Mutex ensures that only one thread can access a section
of code at any given time.
− The section of code protected by a mutex is called a critical
section.

Establishing a mutex:
var mutex = Mutex.create();
mutex.lock();
// ...
// critical section code here
// ...
mutex.unlock();

Multithreading

Task threads

Are special cases of multithreading, implemented
through eq.api.TaskThread.

A task thread can handle a sequence of tasks and can
queue them to execute one after the other.

Possible that this is not implemented on a given
platform, returns null.

Instead of a Runnable, a class must implement the
eq.api.Task interface.

class MyTask : Task
{
public Object run(EventReceiver listener) {
if(listener != null) {
listener.on_event("Hello world");
}
return(null);
}
}
class MyEventListener : EventListener
{
public void on_event(Object o) {
Log.message(o);
}
}
var tt = TaskThread.create();
if(tt != null) {
tt.schedule(new MyTask(), new MyEventListener());
}
The run() method of class
MyTask will be executed first and
then the on_event() method of
class MyEventListener.
TaskThread: Example

Eqela utilities API (eq.util)

 Writing an archive
 Implemented through eq.util.ArchiveWriter
 Creates an archive of files and/or directories to a
format unique only to Eqela.
 add()
− Can add a file or a directory to to be written out
to an archive.
 add_file()
− Adds a file to be written out to an archive.
Generic archive implementation

 add_directory()
− Adds a directory to be written out to an archive.
 write()
− Writes an archive of files and/or directories that have
been added.
var aw = new ArchiveWriter();
aw.add_file(myfile);
aw.add_directory(mydirectory);
aw.write(archivename);
myfile, mydirectory and archivename are of type eq.api.File

 Reading and archive
 Implemented through eq.util.ArchiveReader
 Reads only an archive file created by the
ArchiveWriter.
 You can also set/get the properties of an entry in
the archive through the following types:
− eq.util.ArchiveReaderDirectoryEntry
− eq.util.ArchiveReaderFileEntry
Generic archive implementation

Example:
To construct an instance of an ArchiveReader:
* archivename, of type eq.api.File, should be an archive created by ArchiveWriter.
 An archive can be extracted using the extract_to() method:
* destdir, of type eq.api.File, is a destination directory where you would want the
archive to be extracted.
var ar = ArchiveReader.for_file(archivename);
// using the “ar” instance variable above
ar.extract_to(destdir);

XML Parser

Eqela provides a means of reading an XML file/string and
getting its content through the following classes:

eq.util.XMLParser
− To construct an instance of this class:
− The object to be parsed can come from:
var xml = XMLParser.create();
Source Method
File parse_file()
InputStream parse_input_stream()
Reader parse_reader()
String parse_string()

XML Parser

eq.util.XMLKeyValueParser and
eq.util.XMLHTTPResponseParser
− Both classes contain a static method parse(),
which returns an eq.api.HashTable
var xml = XMLKeyValueParser.parse(str);
var xml = XMLHTTPResponseParser.parse(httpresponse);

Encoding / decoding schemes

URL

URL encoding converts characters into a format
that can be transmitted over the Internet.

Implemented through eq.util.URLEncoder
eq.util.URLDecoder
− Contains static method encode() and decode()
respectively.
− Usage:
var encoded_val = URLEncoder.encode(str);
var decoded_val = URLDecoder.encode(str);


Base64

Base64 is a group of similar encoding schemes that
represent binary data in an ASCII string format by
translating it into a radix-64 representation.

Implemented through eq.util.Base64Encoder
eq.util.Base64Decoder
− Contains static method encode() and decode()
respectively.
− Usage:
var encoded_val = Base64Encoder.encode(str);
var decoded_val = Base64Decoder.encode(str);

Example:
Text to encode:
Using URL encoder:
Using Base 64 encoder:
EQ002: Eqela Application Development
EQ002%3A+Eqela+Application+Development
RVEwMDI6IEVxZWxhIEFwcGxpY2F0aW9uIERldmVsb3BtZW50

Cryptography
Definition

Cryptography is the art of protecting information (plaintext)
by transforming it (encryption) into unreadable format
(ciphertext).

Decryption is moving from ciphertext back to plaintext.

A block cipher is a pair of deterministic algorithm
(encryption and decryption) operating on fixed-length groups
of bits.

The detailed operation of a cipher is controlled both by the
algorithm and in each instance by a key (secret parameter).
Source: http://en.wikipedia.org/wiki/Block_cipher#Definition
http://en.wikipedia.org/wiki/Cryptography

Cryptography

In Eqela, cryptography is implemented through the
following classes:

eq.util.BlockCipherFactory

eq.util.DummyBlockCipher

eq.api.BlockCipher

eq.api.BlockCipherWriter

eq.api.BlockCipherReader

Cryptography

eq.util.BlockCipherFactory

Contains two static methods:
− create(name, key)
− get_ciphers()
var ciphers = BlockCipherFactory.get_ciphers();
var bc = BlockCipherFactory.create(name, key);
The variable “ciphers” holds a collection of supported block ciphers returned by
the get_cipher() method
The variable name could have a string value “dummy”, in which case the
create() method will return an eq.util.DummyBlockCipher object. Or, it could also
have other values of block cipher methods, such as “aes-128”, which will then
return an eq.util.BlockCipher type.

Cryptography

eq.util.BlockCipherWriter

To construct a BlockCipherWriter object:

Example:
Input Plaintext: Hello World
Output Ciphertext: Œ÷(j~~ü§r˜1&ž
var bcw = BlockCipherWriter.create(writer, cipher);
String name = "aes-128";
String key = “password”;
var bcw = BlockCipherWriter.create(File.for_eqela_path("testfile.txt").write(), bc);
bcw.write(“Hello World”.to_utf8_buffer());

Cryptography

eq.util.BlockCipherReader

To construct a BlockCipherReader object:

Example:
Input Ciphertext: Œ÷(j~~ü§r˜1&ž
Output Plaintext: Hello World
var bcr = BlockCipherReader.create(Reader, cipher);
String name = "aes-128";
String key = “password”;
var bcr = BlockCipherReader.create(File.for_eqela_path("testfile.txt").read(), bc);
var ins = InputStream.create(bcr);
Log.message(ins.read_all_string());

Process watchdog

Eqela API includes a utility for monitoring closed
processes.

Implemented through eq.util.ProcessWatchDog

Intended to start a process, and then "watch it". If the
child process dies or exits, then the watchdog restarts
it

Contains the following methods:
− add(cmd, aname);

This method adds a child process to the “watch list” and
then starts it.

Process watchdog
− start();

This method starts watching/monitoring the child
processes that are in the “watch list”.
− stop();

Stops all child processes.
− remove(name);

Removes a child process from the “watch list”.

Thank you

Eqela Core API and Utilities

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

Similaire à Eqela Core API and Utilities

Similaire à Eqela Core API and Utilities (20)

Plus de jobandesther

Plus de jobandesther (7)

Dernier

Dernier (20)

Eqela Core API and Utilities