RadixWare Programmer Guide/Main Objects of RadixWare Platform

From RadixWiki
Jump to: navigation, search

Definitions

Software product development using the RadixWare platform implies creating and editing the model of the product comprising the definitions. In particular, there are the following definitions:

  • units
  • classes
  • tables
  • etc.

The definitions can contain other definitions (for example, the units can contain classes). All the definitions in the product model are identified by GUID (Global Unique Identifier), not by the names as in the majority of programming languages. The references to the definitions from the program code are implemented by means of tags.

Layers and Segments

The software product based on the RadixWare platform comprises a directed graph of layers. Every layer implements the functionality specialized to particular level. The lowest layer (the RadixWare platform) implements the basic functionality (ORM, access control, workflow algorithms, reports, etc.) that can be used in various systems for different purposes. With every next layer the product specialization increases. The topmost layer can be used only to complete the tasks of the particular customer. The layer can use the functionality of previous layers, but not the following ones. Each layer is identified by URI.

example.jpgFor example, the org.radixware.radinsk layer which comprises the Radinsk application is based on the org.radixware. The product user has an opportunity to develop their own org.radixware.radinsk.client_x layer that implements the required functionality based on the org.radixware.radinsk layer functionality. The layer definitions with the Published access mode are available for the next layer definitions and user-defined functions (refer to User-Defined Functions). Such definitions form the API layers.

Each layer consists of the following segments:

  • Kernel. The segment contains the system core classes, implemented on Java SE without using RadixWare Designer. The segment is presented not in all layers.
  • Database Definition Segment (DDS). The segment contains the product DB structure model.
  • Application Definition Segment (ADS). The segment includes the application model as a set of definitions.
  • User Definition Segment (UDS). The segment contains the user definitions sent by the customer for the vendor support and single files to be included in the software product distribution kit.

The segments have different runtime environments. The Kernel segment runs on the Java Virtual Machine. The DDS segment runs on the database. The ADS segment runs on the Application Runtime Environment (ARTE) environment included in RadixWare Server and RadixWare Explorer.

Modules

The definitions of each segment are joined in modules. Each module can depend on other several modules. Therefore, the modules comprise the directed dependence graph. The circular module dependencies are also possible.

The module dependencies define the scope of definitions. For the definition, only those definitions are visible that are located in the same module and in the modules that this module depends on.

The dependence relation is not transitive, i.e. if the module A depends on the module B and the module B depends on the module С, that does not mean that the module A depends on the module C.

The definitions of classes and XML schemas provide dependencies of the module comprising them to the definitions that use them.

example.jpgLet the module B contain the definition of the class Cls with the type T, at that the type T is defined in the module C (it is required that the module B depends on the module C). Let the class Cls1 defined in the module A be inherited from the class Cls (it is required that the module A depends on the module B). Let Cls2 be another class defined in the module A.

deps.png

Then:

  • The type T is available for the class Cls1 since its parent class Cls provides the dependence on the module C in which the type T is defined.
  • The type T is not available for the class Cls2 since the module A does not directly depend on the module C.

The module can act as a companion for another module. The module can use the definitions of the companion module that have the Private and Protected access modes.

The module can be marked as a test module. A standard module cannot depend on the test module.

Tags

Tag is a reference to the definition containing GUID of this definition. RadixWare Designer provides a convenient visual presentation of tags (the editor displays the definition name, not GUID). The tags mechanism provides:

  • The reliable references and guaranteed connectivity. RadixWare Designer can check that the definition being mentioned exists and is of appropriate type.
  • The simplifying of refactoring. In particular, it is always possible to rename any definition. At that, it is not required to change all the references to the definition since the tag contains not the definition name, but its GUID that is not changed in the course of definition "life";.
  • Solution to the name clash problem. Definitions with the same name can exist in different development layers. At that, they are not in conflict with each other since they have different GUID.

The table below provides the supported tag types:

Tag Type

Description

Example of Tag Display

Definition identifier

The identifier of the specified definition.

idof[SomeClass]

Object name in the database

The object name in the database: the name of the table, link, index, etc.

dbName[Radix::PersoComm::Attachment]

RadixWare type

The data type name. It can be either the data type of the JML language or RadixWare class.

SomeClass

Multilingual string

The string constant defined in several languages.

"Test"

Event code

The event message in the form of the multilingual string, the event source and its severity. It is used for tracing.

eventCode["Error"]

Method or property

The reference to the specified method or property of the specified definition.

SomeClass.someMethod

Task

The reminder for the developer. It can be of the TODO, NOTE or FIXME type.

//:FIXME: rewrite this all!

JML

The Java Markup Language (JML) is used in RadixWare to write the program code of the server and presentation definitions. The JML language is based on Java and is translated into the code in Java. The text in JML contains the embedded tags that refer to the model definitions.

Difference between JML and Java

The JML language differs from Java by:

  • Properties. There is a notion of class fields in the Java language. However, each field is characterized only by the name and type. JML supports the class properties like the C# language and some others. The JML enables the developer to create the get- and set- methods for each property. When reading the property value, the respective get- method is invoked; when writing the property value, the respective set- method is invoked.
  • Special comparison operation. In the Java language, the == comparison operation always checks the objects reference equality. In JML, the == operation checks the equality of the values for ones of the following types:
    • String
    • Long
    • Double
    • Boolean
    • Byte
    • Short
    • Float
    • BigDecimal
    • Timestamp

For all other values like in Java, the reference equality is checked.

  • Synonyms of types. JML provides synonyms for some Java language types. The following synonyms are defined:

Java Type

JML Synonym

Boolean

Bool

Character

Char

String

Str

Long

Int

BigDecimal

Num

TimeStamp

DateTime

  • Arithmetic operations for the Num type. In the Java language for the arithmetic operations over the values of the BigDecimal type (that corresponds to the Num type in JML), it is required to call the BigDecimal class methods explicitly. The JML compiler automatically transforms the ordinary record of arithmetical operations over the values of Num type into the calls of the respective methods.
  • Prohibition of Unboxing operation. It is prohibited to assign the boxed values to the variables of the unboxed type (for example, it is impossible to assign the value of the Long type to the variable of the long type). It enables to avoid the runtime NullPointerException.

SQML

The Structured Query Markup Language (SQML) is an SQL language with the embedded tags that refer to the DDS definitions. It is used to write requests, triggers, procedures, etc.

Inheritance and Overriding

According to the object-oriented approach, the RadixWare platform supports the inheritance between classes. The inheritance of RadixWare classes is similar to the inheritance of Java classes. Like in Java, it is possible to override the methods when inheriting if only they are not marked as final. Moreover, the overriding of properties is supported.

RadixWare extends the inheritance concept by supporting it not only for the classes, but for the presentations and roles either. These inheritance options are not directly relevant to the inheritance of the classes in Java. However, the main principle is preserved: it is possible to use the main part of the parent definition functionality and override only part of the attributes.

Overwriting Definitions

In some applications, the layer developer needs to re-define the definition in the lower layer. At that, the lower layer code must call the newly created definition not the original one. For this purpose, the overwrite option is used in RadixWare. The overwritten definition always has the same GUID. Therefore, once it is re-defined, any code that called the original definition before, now will call the overwritten one. In particular, if the original definition was the definition of the class, the code that created the instances of the class will create the instances of the new (overwritten) class.

To overwrite the definition, its parent definition must be overwritten. For example, to overwrite one of the class methods, the class itself must be overwritten. To overwrite the class in the module, the module must be overwritten, etc.

In the DDS segment, only the table definitions can be overwritten.

Some definitions are overwritten completely, others are merged according to the rules that depend on the definition type:

  • User-defined dialog boxes and XML schemas are overwritten completely.
  • When overwriting the lower layer module, the module containing all the same definitions as the original module is created. The definitions of the new module can overwrite the definitions of the original one.
  • Overwriting the RadixWare Designer class definitions automatically creates the same set of properties and methods that the original definition had. The developer can change some of them (without changing the profile) or add the new ones. Therefore, the overwritten definition can only expand the behavior of the original one or substitute the implementation of some methods.

Publishing

The system kernel (the Kernel segment) is implemented on the Java SE platform and contains the basic definitions that can be used by the developer applying RadixWare. However, the Kernel segment is not a part of the product model, therefore these definitions do not have GUID. To include the kernel classes into product model, RadixWare enables to publish the definition from the kernel in the form of adapter-definition of the ADS segment. At that, the definition receives GUID that makes possible to use the published definition in other model parts.

When publishing the class, RadixWare Designer enables to select its methods that must be published. The published methods are called transparent. The profile and body of the transparent method are not editable (since they are defined in the Kernel segment).

The class publishing can be extensible and non-extensible. For the extensible class publishing, RadixWare Designer enables to define new methods, for non-extensible ones - only to publish the class methods already defined in the Kernel segment.

When creating the method in the published class with the name identical to the name of the published class method, the methods do not override each other automatically.

For details on enumerations publishing, refer to Enumerations.

Algorithm of Definition Search

The tags are substituted for the certain definition identifiers in the course of compilation. At that, it is required to define the overwritten or parent definition to which this or that method or object property relates to. The search algorithm includes the following:

  • If the definition under review contains the original property, the search is finished.
  • If the definition under review overwrites another one, the overwritten definition comes under review.
  • If the definition under review is inherited from another one, the parent definition comes under review. At that, if the parent definition was overwritten, the overwriting definition defined in the layer that is the closest one to the original layer will come under review.

example.jpgLet's consider that the classes are defined in the application as on the following diagram. If it is required to call any property of the class A3, the definition will be searched according to the following order: A3, A2, A1, B2, B1. overwrite-diagram.jpg

Polymorphic Tables

Many applications have a multitude of classes presenting the objects that, in fact, are varieties of some particular objects class. For example, the objects of the Terminal class have some common set of properties. The objects of the POS terminal class have the same properties as all other terminals and some specific properties. The objects of the ATM class have the same properties as all other terminals and some specific properties, etc. In the database, such hierarchy of classes looks as follows: the system creates a "terminals" master table that stores common properties of all terminals and a quantity of the so called detail tables ("POS terminals", "ATMs", etc.). Each row of the detail tables stores specific properties of the particular terminal and a reference to the row (foreign key) in the master table storing the common properties of this terminal. Therefore, a master table stores the objects of different types. Such tables are called polymorphic.

Server Instances and Units

The application system can comprise several application server instances. The running application server instance is called an instance. The instances are described by the Radix::System::Instance entity class.

The system units can be started within the instance. A set of system units is defined by the system administrator.

RadixWare system units are implemented in the Kernel segment. To provide interaction between the ADS program code and system units, the latter are presented in ADS as descendants of the Radix::System::Unit entity class. Each application class based on the Radix::System::Unit entity class describes a particular type of the system units. When starting up the unit, its description is read from the database. The columns of the read record are considered as unit settings. It is possible to change the unit settings from RadixWare Explorer.

It is possible to start up several units of each type simultaneously, but units of some certain types can be started one at a time.

Once RadixWare Server is connected to the database, it loads the system units described for this instance in the database.

Within the instance, RadixWare Server starts up the number of the Application RunTime Environment (ARTE) instances defined by the administrator. Each ARTE instance runs in the separate OS flow. Hereafter, it is possible to start up the new ARTE instances and shut down the old ones if required. A set of ARTE instances working within RadixWare Server is called a pool of ARTE instances.

Each of the system units can use one or several ARTE instances.

Services Architecture

RadixWare system units interact with each other using the provided services.

RadixWare ensures the network transparency of interaction between the system units: in the course of interaction between two units, it makes no difference whether they function on a single computer or on different computers in the network.

Client application or external systems can use some of the services provided by the system units.

Some of system units provide the network services - system interfaces supported by the SOAP protocol. Other units of this system, client application or other systems can use the provided services.

To work with the service, the following protocols can be used: the SOAP protocol over TCP/IP protocol or the SOAP protocol over the protocol integrated in RadixWare called an internal pipe. It is used to exchange the data between different flows of the same JVM process.

The system units and RadixWare instances or the components of external systems can act as systems providing the services.

User-Defined Functions

When configuring the application system, the user can describe the functions in the JML language. These functions are dynamically invoked from the class methods and can use API of the software product.

The user-defined functions are the instances of the application classes based on the Radix::UserFunc::UserFunc entity class. Each of these application classes has the main method with the profile identical to the user-defined function profile. This method invokes the Radix::UserFunc::UserFunc.invoke() method directly or indirectly.

In RadixWare Explorer, a special editor is used to edit the properties of application classes which types are the classes of user-defined functions.

Several versions can be stored for each user-defined function. The user can switch between versions and create the new ones.

Profiling

Profiling implies collection of time characteristics of system operation, such as run-time of certain methods. The profiling is used to detect those system parts that decrease the performance and to optimize the system.

Profiling tools of the RadixWare platform enable to collect and analyze the statistics of operation time in terms of application area.

The statistics is collected while in operation for the system parts defined by the administrator.

The minimum system part for collecting the statistics is called timing section. Each timing section is characterized by the identifier comprising several words separated by point. The list of prefixes defines a variety of timing sections for statistics to be collected. Each of the prefixes can comprise several words separated by point. The statistics is collected for those timing sections whose identifiers either identical to one of the defined prefixes or start with one of the prefixes added by a point. For example, when the profiling is switched on for the "Aa", "Bb.Cc" prefixes, the following prefixes must be profiled: "Aa", "Bb.Сс","Aa.Xx", "Bb.Cc.Yy", "Aa.Zz", "Bb.Cc.Yy.Zz", etc.

RadixWare Designer enables to identify for each method what timing section it belongs to. Moreover, RadixWare Designer is used to define additional timing sections.

The system administrator can view and clear the accumulated statistics using RadixWare Explorer.