iArch-U

Documentation

This is the documentation for iArch 1.1.

iArch-U

OverView

OverView

iArch-U is the IDE, which supports the “uncertainty-aware software development”. iArch-U has the interface component Archface-U as the central mechanism to support uncertainty-aware software development. The word “Archface-U” is coined from “Architecture”, “Interface”, and “Uncertainty”.

The common restrictions for the entire development process are expressed in Archface-U, especially at design and implementation. iArch-U continuously checks UML model against Archface-U to keep consistency, and also checks code against it. That enables consistent development throughout design and implementation phase.

Archface-U also contains description of uncertainty occurred in development process. In the context of Archface-U, “uncertainty” is an unfixed design or an unfixed way to implementation. Thus the following situations should be described in Archface-U, for example.

Describing uncertainty in Archface-U is the sufficient way to manage uncertainty. Additionally, iArch-U assures consistency between model, code, and Archface-U, considering uncertainty. That enables you to continue the development process while involving uncertainty. Here we provide iArch-U as the sufficient solution for the “uncertainty-aware software development”.

We broadly classify features of iArch-U like the following.

GUI

ScreenShot

iArch is distributed as an Eclipse plugin. That provides graphical views to manage uncertainty. Detailed information is in this documentation.

Terminology

Archface-U

Archface-U is a new interface designed to enable continuous development with ensuring traceability between software design and implementation. It is an interface between UML models and Java code described on the iArch-U IDE. Traceability is maintained by the type checking process so that the UML models and Java code are designed and implemented to conform to Archface.

Archface-U is based on component-and-connector architecture and consists of two kinds of interface: component and connector. The former exposes a set of architectural points that should be shared among requirements models, design models and programs, and the latter defines how to coordinate them.

Syntax

Archface-U syntax to define a component is roughly the same as the Java syntax for interface declaration, except that it needs an additional component keyword, and the syntax for connector definition is based on the syntax of Finite State Process (FSP).

interface component ComponentName {
	ReturnType methodName(ArgumentType argumentName, ...);
	...
}

interface connector ConnectorName {
	ClassName = (ClassName.methodName -> ClassName.methodName -> ...);
	...
}

In a component definition, you can list method signatures whose enclosing class should have. In a connector definition, you can declare ordered sequences of methods that should be called in that order when the program is executed.

When you want to introduce uncertainty into Archface-U definition, it can be expressed by enclosing uncertain parts of the program with brackets, along with replacing interface keyword with uncertain. There are two types of uncertainty Archface-U supports:

uncertain component ComponentName {
	{ ReturnType methodName(ArgumentType argumentName, ...);,
	ReturnType methodName(ArgumentType argumentName, ...);, ... }

	[ ReturnType methodName(ArgumentType argumentName, ...); ]
}

uncertain connector ConnectorName {
	ClassName = ({ ClassName.methodName, ClassName.methodName, ... } -> ...);

	ClassName = ([ ClassName.methodName ] -> ...);
}

You can declare alternative by bracketing a method with {} (curly brackets) and optional by [] (square brackets).

Features

iArch-U provides various functionalities to support the development process employing the Java language.

Modelling

In the modelling process using iArch-U, we can express two types of uncertainty, optional and alternative, by extended class diagrams and sequence diagrams. Archface-U compiler also runs type checking on models so that we have to draw class diagrams and sequence diagrams conforming to interfaces defined in Archcode.

In the class diagram, uncertain methods are marked by {} or [], for alternative and optional respectively, as the same way as in Archface-U. In the sequence diagram, uncertainty is expressed by complex fragments labelled with u-alt or u-opt, for alternative and optional respectively, to distinguish them from normal alt and opt fragments.

Creating a new model diagram

At first, select File -> New -> Other. After the dialogue box is displayed, select Examples -> Graphiti -> Graphiti Diagram, and push Next button.

New diagram 1

In the next pane, you will be asked to select a diagram type. If you want to draw a class diagram, select ClassDiagram, or if you want to draw a sequence diagram, select SequenceDiagram, and push Next button.

New diagram 2

Lastly, enter an appropriate diagram name, and push Finish button. This will create a new model file and it will be opened by the model editor.

New diagram 3

Common operations of the model editor

You can choose a model element from the right-hand side of the model editor and place it on the grid.

Class diagram

Sequence diagram

Some elements in Objects can be placed only within an already placed element. Elements belonging to Connections can be used to connect elements on the grid by selecting them. You can change the location or the size of model elements by dragging them, and also you can change the name of model elements by clicking them.

In the Properties view, you can see information of the selected element. The name of some types of elements can be changed from the Properties view.

Properties view

Operations for the class diagram

Operations for the sequence diagram

Editing uncertainty in the model editor

In the model editor, you can choose one of the following four operations from the context menu where you want to edit uncertainty.

Setting uncertainty

Setting uncertainty introduces optional or alternative uncertainty into a method declaration in the class diagram or a method call in the sequence diagram.

To set optional uncertainty, select iArch: Set Optional. This operation changes not only the model element you choose but also the corresponding Archcode element.

Slicing optional 1

Slicing optional 2

Slicing optional 3

To set alternative uncertainty, select iArch: Set Alternative. Enter method names with separating spaces in the dialogue box. This operation changes not only the model element you choose but also the corresponding Archcode element.

Slicing alternative 1

Slicing alternative 2

Slicing alternative 3

Slicing alternative 3

Removing uncertainty

Removing uncertainty is an operation to get rid of now unnecessary uncertainty. You can choose either to remove uncertainty because the element in question turned to be necessary, and you want to preserve it, or to remove uncertainty because the element is now clearly unnecessary.

To remove uncertainty when the element turned to be necessary, select iArch: Remove Uncertainty as Necessary. This operation changes not only the model element you choose but also the corresponding Archcode element.

To remove uncertainty when the element turned to be unnecessary, select iArch: Remove Uncertainty as Unnecessary. This operation causes following destructive changes:

Type checking

You can check the consistency between model diagrams and Archcode by selecting Type Check from the context menu of the model editor. If the models do not conform to the restrictions imposed by Archcode, it will be displayed in the Problems view.

Diagram type check

Programming

The Archface-U compiler will compile Archcode at the same time as Java code compilation as well as type checking. If your implementation violates the interface description, the Archface-U compiler will return compilation error as a result of type checking.

Editing uncertainty in the program editor

You can manage uncertainty in the program editor, as you can in the model editor. In the program editor, if the cursor is at a method signature line when you invoke the uncertainty editing operation from the context menu, the corresponding component description in Archcode will be changed accordingly. On the other hand, if the cursor is at a method call line, the corresponding connector description will be changed.

Type checking

Type checking is executed every time Java code is compiled. If the code does not conform to the restrictions imposed by Archcode, it will be displayed as a marker at the left side border of the program editor and in the Problems view.

Code type check

Archface-U editor

You can edit Archcode in the Archface-U editor, which offers syntax error checking and syntax highlighting features.

Model inspection and metrics calculation

In Archface-U View, you can check whether an element described in Archcode is uncertain and is already implemented, as a result of type checking. In addition, you can check the metrics about the abstraction (number of design points(DP), program points(PP), and the abstraction ratio) of the project.

Archface-U view

Testing Support

There is a known issue in Java8 environment that may prevent execution of Testing Support.

iArch also provides an easy way to test uncertainty-involving code. You should begin with expressing uncertainty in Archface-U as mentioned above, and then add the annotations which represents how the program should perform in testing. For example, when you have alternative uncertain methods, you specify which method should be executed in testing.

Based on an annotations you added, iArch-U generate Aspect in your project. Aspect is the special source code to control program’s behavior, that makes it possible to test your program depending on the annotations you added without modifying the original code. Aspect and Java source code are compiled together by AspectJ compiler (You may install AJDT for that).

This is a brief description of testing support. For concrete usage examples of each annotation, please see the tutorials.

Method-Execution-Control Annotations

Here we introduce the annotations which specifies how the program should perform in testing. The annotations are added to methods in uncertain component interfaces.

As for behaviors in uncertain connector interface, you must have a corresponding method definition in component interface, so add annotations to it.

Non-probabilistic Effect Annotations

Annotation Effect
@ExecForce To execute the method.
@ExecIgnore Not to execute the method.

Uncertainty-involving program can result in many different instances at the end. To continue development while involving uncertainty, it is important to investigate whether a specific instance meets the requirements. With these annotations, you are able to emulate one instance of uncertainty-involving program in testing.

For Alternative, you can add @ExecForce to the method that should be executed. For Optional, you can add @ExecForce in order to execute the method, or @ExecIgnore to suppress execution.

There are some undefined combinations of annotation. (e.g. @ExecForce added to all of alternative uncertain methods.) For clarity, avoid using undefined combinations.

Probabilistic Effect Annotations

Annotation Effect
@ExecRatio(double p) To execute the method with p probability.
@ExecWeight(double w) To execute the method with w weight.

The representative use case of these annotations is A/B testing, as known as controlled experiment. That is, when you have some candidate implementations, you assign each candidate to a subset of user base, and analyze logs to know which is better. (e.g. In an e-commerce app, red or green, which color for “buy” button makes more sales?)

The difference between @ExecRatio and @ExecWeight is their argument. The value @ExecRatio accepts is a probability to execute the method (e.g. 0.5). On the other hand, @ExecWeight accepts a weight for the method. The weight defines the ratio to execute the method relatively among the alternatives.

If you add @ExecRatio(p) to one alternative method and there are remaining alternative methods, The rest of probability 1 - p should be distributed to the the remaining methods uniformly. For Optional, the remaining method is just an empty method. As for @ExecWeight, the weight for a method without annotation is set to 0.

Practically, for Alternative, you should use @ExecWeight to set ratio, because that is easier to use. For Optional, you should use @ExecRatio instead.

There are some undefined combinations of annotation. (e.g. @ExecRatio and @ExecWeight are used at the same time.) There are also undefined argument values. (e.g. @ExecRatio(p) under p > 1) For clarity, avoid using these undefined expressions.

Labeling Annotations

Annotation Effect
@Label(String l) To label the method as l.

The annotation @Label affects a class name or method name of generated aspect code. By default serial numbers are used in generated aspect code, however, You can set human-readable name to improve readability.

@Label is optional annotation, there is no problem if you add this annotation or not. Unlike the method-execution-control annotations, @Label can be added to not only a method but also an uncertainty itself.

Usage

On GUI, you can generate Aspect by selecting Generate Aspect from the iArch menu of the toolbar. Removing Aspect is done by selecting Remove Aspect.

Management support

When some uncertainty is resolved during the design or coding process, the trace of this uncertainty only remains in the commit history. To find the source and temporal transitions of uncertainty from Java code commit history is a daunting task. iArch-U provides a feature to dig change history of Archcode and to display summary of uncertainty changes.

If the project is managed by git, triggered by the type checking for Java code, commit time and other related information for each uncertainty existing in Archcode are displayed in Archface-U View. Additionally, if you double click an uncertainty element in the view, you can examine detailed history in another window.

Git log dialog

Model checking support

When you need to verify your model, the LTS analyser (http://www.doc.ic.ac.uk/~jnm/LTSdocumention/LTSA.html) will help. The LTS analyser checks FSP code which represents the model. You can generate FSP code from an Archface-U file by selecting Generate FSP for LTS from the iArch menu of the toolbar. Resulting code is displayed in a dialogue, and is saved in the project folder.

Generated FSP

Generation/synchronisation support among Archface-U, model diagrams and Java code

Every time you add/remove the uncertainty to/from the model, both Archface-U and the model diagrams should be updated simultaneously. However, sometimes the relationship among them is disturbed. On the other hand, you want to start managing uncertainty on existing (unmanaged) project, or you wish to avoid writing routine phrases for classes you have modelled already.

iArch gives you the functionalities to generate/synchronise Archface-U, model diagrams, and Java code, by selecting items within the Synchronize from the iArch menu of the toolbar.

Model diagrams to Archface-U

When you select Model -> iArch, you can generate Archface-U description corresponding to the model diagrams which you chose in the configuration described below.

This feature is the same as the one which is previously provided as Generate Archface in the menu, except that the diagram selection by a dialogue is unnecessary.

For example, from a class diagram and a sequence diagram,

model to Archface-U class diagram model to Archface-U sequence diagram

you can get the Archface-U like:

model to Archface-U result

Archface-U to model diagrams

When you select iArch -> Model, you can generate model diagrams corresponding the Archcode which you chose in the configuration described below.

For example, from an Archface-U,

Archface-U to model archfile

you can get class and sequence diagrams like:

Archface-U to model result 1 Archface-U to model result 2 Archface-U to model result 3

Java code to Archface-U

When you select Code -> iArch, you can generate Archface-U description corresponding to the Java code which you chose in the configuration described below.

For example, from 4 classes in the project, you can get the Archface-U like:

code to Archface-U result

Archface-U to Java code

When you select iArch -> Code, you can generate Java code corresponding the Archcode which you chose in the configuration described below.

For example, from an Archface-U,

Archface-U to model archfile

you can get Java code skeltons like:

Archface-U to model result 1 Archface-U to model result 2

Other features

Configuring type checking target

When you select Check Archface Configuration from the iArch menu of the toolbar, a dialogue box to select Archcode, Java code and model diagrams in the project will be displayed. Selected elements are to be type checked when you save Java code.

Select all

Architecture

Extension points

iArch-U provides its functionalities through these Eclipse extension points.

Package structure

iArch-U consists of these Java packages.

Known Issues