SpeADL for Dynamic Architectures Tutorial¶

• Contenu
• SpeADL for Dynamic Architectures Tutorial
  • Objectives
  • Prerequisites
  • Creating a New Project and Organisation
  • The Logging Ecosystem
    • Defining the Ecosystem and the Species
    • Implementing the Ecosystem and the Species, Logging in One File
    • Implementing the Ecosystem and the Species, Logging in Many Files
  • The Banking Ecosystem
    • Defining the Ecosystem and the Species
    • Implementing the Ecosystem and the Species
  • Composing with Uses into a Bank Application
    • Defining the Ecosystem and the Species
    • Implementing the Ecosystem and the Species
  • Adding a GUI to the Bank Ecosystem
    • Preparing the Other Ecosystems
    • Defining the Ecosystem
    • Implementing the Ecosystem and Species
    • Executing
  • Conclusion
• Wiki Page Resources

This is a tutorial for SpeADL: understanding ecosystems and species, defining a simple ecosystem, composing species together with uses.

Objectives¶

The objective of this tutorial to understand the abstractions of species and uses, how to build architecture with dynamically created components and how to exploit uses to separate concerns in a type-safe way.
We won't focus on the workflow and mostly present already defined architectures and implementation without explaining how we arrived to that solution.

We will create a Logging ecosystem that contains Logger species.
Then we will create a Banking ecosystem that contains Account species that need to log what happens.
After, we will create a Bank ecosystem that compose Account species with Logger species thanks to the use abstraction.
And finally we will add a GUI that will instantiate species and visualise them.

Prerequisites¶

It is needed to understand the content of the SpeADL⁻ tutorial before doing this one.

Creating a New Project and Organisation¶

Create a Java project.
We will use again an organisation of the package and namespaces as explained in this best practice.

The Logging Ecosystem¶

Logging will be an ecosystem, and its particularity is that it will be able to create Loggers: while logging is the subsystem responsible of all logging, each logger will be responsible of logging one particular aspect of the system. Such an aspect will be identified by a name.
We will have multiple implementation for the Logging ecosystem:

• One with only one file where to log with each line prepended with the name.
• One with one file per Logger all in the same directory.

In any case, a port will be provided by Logging to create standalone instances of Logger.

Defining the Ecosystem and the Species¶

Create a SpeADL file named logging.speadl in the package tutorial2.logging.

Define in it the ecosystem and the species in the right namespace as well as the needed interface:

import tutorial2.logging.interfaces.ILog

namespace tutorial2.logging {

    ecosystem Logging {        
        provides create: ICreateLogger

        species Logger(name: String) {
            provides log: ILog
        }
    }

}

package tutorial2.logging.interfaces;

public interface ILog {

    public void addLine(String line);
}

public interface ICreateLogger {

    public Logging.Logger.Component createStandaloneLogger(String name);
}

Implementing the Ecosystem and the Species, Logging in One File¶

Create a new Java class in tutorial2.logging.impl named LoggingImplOneFile that extends Logging, that takes a File as a parameter to the constructor to store the logs, and resolve the error with the Quick Fixes of Eclipse:

package tutorial2.logging.impl;

import java.io.File;
import java.io.FileNotFoundException;
import java.io.FileWriter;
import java.io.IOException;
import java.io.PrintWriter;

import tutorial2.logging.Logging;
import tutorial2.logging.interfaces.ICreateLogger;

public class LoggingImplOneFile extends Logging {

    private PrintWriter logWriter;

    public LoggingImplOneFile(File logFile) {
        // if an exception happens, nothing can be done about it
        // we just let logStream be null and
        // the operations of logging won't be done
        try {
            this.logWriter = new PrintWriter(new FileWriter(logFile), true);
        } catch (FileNotFoundException e) {
            System.err.println("An error happened with the file, nothing will be logged.");
            this.logWriter = null;
        } catch (IOException e) {
            System.err.println("An error happened with the file, nothing will be logged.");
            this.logWriter = null;
        }
    }

    @Override
    protected ICreateLogger make_create() {
        // TODO Auto-generated method stub
        return null;
    }

    @Override
    protected Logger make_Logger(String name) {
        // TODO Auto-generated method stub
        return null;
    }
}

As we can see, the species we defined needs to be implemented and this implementation needs to be returned by the method Logger make_Logger(String name).

Let's define an inner class inside LoggingImplOneFile to do that, it will take as a parameter to the constructor the name of the Logger and will exploit the logWriter to do the actual logging.

public class LoggingImplOneFile extends Logging {

    private PrintWriter logWriter;

    // ...

    @Override
    protected Logger make_Logger(String name) {
        return new LoggerImpl(name);
    }

    private class LoggerImpl extends Logger implements ILog {

        private final String name;

        public LoggerImpl(String name) {
            this.name = name;
        }

        @Override
        protected ILog make_log() {
            return this;
        }

        @Override
        public void addLine(String line) {
            if (logWriter != null) {
                logWriter.println("["+name+"] "+ line);
            }
        }
    }
}

Then let's implement the create port by exploiting the method newLogger(String name) present in the extended class and that instantiates the species:

public class LoggingImplOneFile extends Logging {

    // ...

    @Override
    protected ICreateLogger make_create() {
        return new ICreateLogger() {
            @Override
            public Logger.Component createStandaloneLogger(String name) {
                return newLogger(name);
            }
        };
    }

    // ...
}

We now have a complete implementation for the Logging ecosystem.
Let's test it with a very simple program that we put in the package tutorial2.logging.tests*:

package tutorial2.logging.tests;

import java.io.File;

import tutorial2.logging.Logging;
import tutorial2.logging.Logging.Logger;
import tutorial2.logging.impl.LoggingImplOneFile;

public class LoggingTest {
    public static void main(String[] args) {

        Logging.Component logging = new LoggingImplOneFile(new File("/tmp/tutorial2-logging-test.txt")).newComponent();

        // create new Loggers
        Logger.Component l1 = logging.create().createStandaloneLogger("a");
        Logger.Component l2 = logging.create().createStandaloneLogger("b");
        Logger.Component l3 = logging.create().createStandaloneLogger("c");

        // log things to them
        l1.log().addLine("1 a says hi");
        l1.log().addLine("2 test test");
        l2.log().addLine("3 b says hoy");
        l1.log().addLine("4 blabla");
        l3.log().addLine("5 hop");
    }
}

Execute it and confirm that the file /tmp/tutorial2-logging-test.txt contains the following:

[a] 1 a says hi
[a] 2 test test
[b] 3 b says hoy
[a] 4 blabla
[c] 5 hop

Implementing the Ecosystem and the Species, Logging in Many Files¶

We can now define a second implementation that stores the logs of each Logger in its own file:

package tutorial2.logging.impl;

import java.io.File;
import java.io.FileNotFoundException;
import java.io.FileWriter;
import java.io.IOException;
import java.io.PrintWriter;

import tutorial2.logging.Logging;
import tutorial2.logging.interfaces.ICreateLogger;
import tutorial2.logging.interfaces.ILog;

public class LoggingImplDirectory extends Logging {

    private final File logDir;

    public LoggingImplDirectory(File logDir) {
        this.logDir = logDir;
        this.logDir.mkdirs();
    }

    @Override
    protected Logger make_Logger(String name) {
        return new LoggerImpl(new File(logDir, name+".txt"));
    }

    @Override
    protected ICreateLogger make_create() {
        return new ICreateLogger() {
            @Override
            public Logger.Component createStandaloneLogger(String name) {
                return newLogger(name);
            }
        };
    }

    private class LoggerImpl extends Logger implements ILog {

        private PrintWriter logWriter;

        public LoggerImpl(File logFile) {
            // if an exception happens, nothing can be done about it
            // we just let logStream be null and
            // the operations of logging won't be done
            try {
                this.logWriter = new PrintWriter(new FileWriter(logFile), true);
            } catch (FileNotFoundException e) {
                System.err.println("An error happened with the file, nothing will be logged.");
                this.logWriter = null;
            } catch (IOException e) {
                System.err.println("An error happened with the file, nothing will be logged.");
                this.logWriter = null;
            }
        }

        @Override
        protected ILog make_log() {
            return this;
        }

        @Override
        public void addLine(String line) {
            if (logWriter != null) {
                logWriter.println(line);
            }
        }
    }
}

It can be tested with the previous class by changing the first line instantiating the component:

Logging.Component logging = new LoggingImplDirectory(new File("/tmp/tutorial2-logging-test/")).newComponent();

Execute it and confirm that the /tmp/tutorial2-logging-test/ directory contains one file per Logger with the correct content.

The Banking Ecosystem¶

Banking will also be an ecosystem, it will contain Account that are species with a particularity: they have required ports!
Because of that, they can't simply be created but must be composed with other components or species to be usable.

Defining the Ecosystem and the Species¶

Create a SpeADL file named banking.speadl in the package tutorial2.banking and define a Banking ecosystem in tutorial2.banking namespace:

import tutorial2.banking.interfaces.IAccountOperations
import tutorial2.banking.interfaces.IAccountStatus
import tutorial2.logging.interfaces.ILog

namespace tutorial2.banking {

    ecosystem Banking {

        species Account(owner: String) {

            provides operations: IAccountOperations
            provides status: IAccountStatus

            requires log: ILog
        }
    }
}

Then the interfaces in tutorial2.banking.interfaces:

package tutorial2.banking.interfaces;

public interface IAccountOperations {

    public void deposit(int value);
    public void withdraw(int value);
}

public interface IAccountStatus {

    public int getBalance();
}

Implementing the Ecosystem and the Species¶

We now can define an implementation named BankingImpl in the package tutorial2.banking.impl.
It exploits the provided ports and the required ports of the species, but also the required port of the ecosystem:

package tutorial2.banking.impl;

import java.util.concurrent.atomic.AtomicInteger;

import tutorial2.banking.Banking;
import tutorial2.banking.interfaces.IAccountOperations;
import tutorial2.banking.interfaces.IAccountStatus;

public class BankingImpl extends Banking {

    @Override
    protected Account make_Account(final String owner) {
        return new Account() {

            private final AtomicInteger balance = new AtomicInteger();

            @Override
            protected void start() {
                eco_requires().elog().addLine("Added a new account for "+owner);
            }

            @Override
            protected IAccountOperations make_operations() {
                return new IAccountOperations() {

                    @Override
                    public void withdraw(int value) {
                        provides().operations().deposit(-value);
                        requires().log().addLine(value+" were withdrawn, current balance: "+provides().status().getBalance());
                    }

                    @Override
                    public void deposit(int value) {
                        balance.addAndGet(value);
                        requires().log().addLine(value+" were deposited, current balance: "+provides().status().getBalance());
                    }
                };
            }

            @Override
            protected IAccountStatus make_status() {
                return new IAccountStatus() {
                    @Override
                    public int getBalance() {
                        return balance.get();
                    }
                };
            }
        };
    }
}

Notice the calls to provides() and requires().

Now let's add a bit more log for when a species is instantiated: it must be logged in a file specific to the ecosystem and not to the species.
Let's add a required port to the ecosystem Banking:

requires elog: ILog

Then let's add a start() method to the implementation of Account in BankingImpl:

    @Override
    protected void start() {
        eco_requires().elog().addLine("Added a new account for "+owner);
    }

Notice the use of eco_requires() from within the species to access the ports of the ecosystem.

Composing with Uses into a Bank Application¶

Now that we have the two functionality we need, we can build our application to compose them together.
In order to do that, we need to define an ecosystem with a species that "uses" the other two.

Defining the Ecosystem and the Species¶

Let's define the ecosystem Bank in a SpeADL file named bank.speadl in the package and namespace tutorial2.bank:

import tutorial2.banking.Banking
import tutorial2.banking.interfaces.IAccountOperations
import tutorial2.banking.interfaces.IAccountStatus
import tutorial2.logging.Logging
import tutorial2.logging.interfaces.ILog

namespace tutorial2.bank {

    ecosystem Bank {

        provides elog: ILog

        part l: Logging

        part b: Banking {
            bind elog to elog
        }

        species BankAccount(owner: String) {

            use ll: l.Logger(owner)
            use ba: b.Account(owner) {
                bind log to ll.log
            }
        }
    }
}

Notice the following points:

• Each of the ecosystem that are needed are declared as parts of the Bank ecosystem, and the species we defined in them are declared as uses of the species BankAccount.
• In order to bind the required port of b: Banking, the containing ecosystem needs to provide a port that will be used in the binding. This port is not meant to be used from the exterior but from inside the ecosystem.
• The required ports of the Account species are provided by the Logger species.

The idea behind such a composition is that when an instance of BankAccount is created, then it implies that an instance of Logger and an instance of Account are created at the same time and used as parts of BankAccount.
Each of the species retains its links to its own ecosystem without leaking it to the outside.

Implementing the Ecosystem and the Species¶

Implementing the ecosystem is quite straightforward as there is not so much things to add in the implementation.
Let's create BankImpl in the package tutorial2.bank.impl:

package tutorial2.bank.impl;

import tutorial2.bank.Bank;
import tutorial2.banking.Banking;
import tutorial2.logging.Logging;
import tutorial2.logging.interfaces.ILog;

public class BankImpl extends Bank {

    @Override
    protected ILog make_elog() {
        // TODO Auto-generated method stub
        return null;
    }

    @Override
    protected Logging make_l() {
        // TODO Auto-generated method stub
        return null;
    }

    @Override
    protected Banking make_b() {
        // TODO Auto-generated method stub
        return null;
    }
}

Notice that the make_BankAccount(String owner) method that should normally be overridden does not need to because the species does not have any provided port to implement nor parts.

First, let's fill the methods for the parts:

public class BankImpl extends Bank {

    private final File logDir;

    public BankImpl(File logDir) {
        this.logDir = logDir;
    }

    @Override
    protected Logging make_l() {
        return new LoggingImplDirectory(logDir);
    }

    @Override
    protected Banking make_b() {
        return new BankingImpl();
    }

    // ...
}

Finally, let's use the Logging component to get a special Logger for the whole ecosystem:

public class BankImpl extends Bank {

    // ...

    @Override
    protected ILog make_elog() {
        Logging.Logger.Component eLogger = parts().l().create().createStandaloneLogger("BANK");
        return eLogger.log();
    }

    // ...
}

Notice that because provided ports are initialised after parts (see the lifecycles of components initialisation), it is possible to directly call the create port of the l part to instantiate a Logger and return directly the port of the instance.

Adding a GUI to the Bank Ecosystem¶

In order for the Bank ecosystem to be usable, we need to be able to create new BankAccount and interact with them.
We could add provided ports and interact with it, but here we are going to define another ecosystem encapsulating a GUI for managing the accounts.
This GUI could have been directly added to the Bank ecosystem as it is quite empty, but for the sake of pedagogy, we create another ecosystem in order to show more examples and idioms.

Preparing the Other Ecosystems¶

We need first to add a method to IAccountStatus to be able to get the owner of an account:

    public String getOwner();

The implementation in the species of BankingImpl just returns the owner:

    @Override
    public String getOwner() {
        return owner;
    }

Then we need to add a way to instantiate a new account in the Bank ecosystem, let's add a port for that in the ecosystem:

ecosystem Bank {        
    provides manage: IBankManage
    // ...
}

package tutorial2.bank.interfaces;

public interface IBankManage {
    public void instantiateAccount(String owner);
}

Its implementation in BankImpl simply calls newBankAccount(owner):

    @Override
    protected IBankManage make_manage() {
        return new IBankManage() {
            @Override
            public void instantiateAccount(String owner) {
                newBankAccount(owner);
            }
        };
    }

Notice that we don't return the created instance because we won't need it in the GUI: everything will be done using bindings of ports between the uses.

Defining the Ecosystem¶

Let's define a BankGUI ecosystem in a SpeADL file named gui.speadl in the package and namespace tutorial2.gui:

import tutorial2.bank.interfaces.IBankManage
import tutorial2.banking.interfaces.IAccountOperations
import tutorial2.banking.interfaces.IAccountStatus

namespace tutorial2.gui {

    ecosystem BankGUI {

        requires manage: IBankManage

        species AccountGUI {
            requires operations: IAccountOperations
            requires status: IAccountStatus
        }
    }
}

The species AccountGUI is responsible of the part of the GUI related to one account, while the ecosystem itself is responsible of the whole frame.
In order to manipulate the account, the species has some required ports, and in order to trigger the instantiation of the species, the ecosystem has also some required ports.

We then need to update the Bank ecosystem as follows in order to exploit BankGUI:

namespace tutorial2.bank {

    ecosystem Bank {

        provides manage: IBankManage
        provides elog: ILog

        part l: Logging

        part b: Banking {
            bind elog to elog
        }

        part gui: BankGUI {
            bind manage to manage
        }

        species BankAccount(owner: String) {

            use ll: l.Logger(owner)
            use ba: b.Account(owner) {
                bind log to ll.log
            }
            use ga: gui.AccountGUI {
                bind operations to ba.operations
                bind status to ba.status
            }
        }
    }
}

Now, when a new BankAccount is instantiated, the species AccountGUI will also be along the other ones.
We can exploit that to define in the implementation what happens at that point.

Implementing the Ecosystem and Species¶

The implementation relies on all these ports to instantiate the species when the user clicks on a button.
This instantiation will trigger the instantiation of the AccountGUI species, and we will add a row in our GUI for this account.
Using the required ports, we can fill the row and call the operations on the account.

package tutorial2.gui.impl;

import java.awt.BorderLayout;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;

import javax.swing.BoxLayout;
import javax.swing.JButton;
import javax.swing.JFormattedTextField;
import javax.swing.JFrame;
import javax.swing.JLabel;
import javax.swing.JPanel;
import javax.swing.JTextField;
import javax.swing.SwingUtilities;

import tutorial2.gui.BankGUI;

public class BankGUIImpl extends BankGUI {

    private final JFrame f = new JFrame();
    private final JPanel accPanel = new JPanel();

    @Override
    protected void start() {
        SwingUtilities.invokeLater(new Runnable() {
            @Override
            public void run() {                
                final JTextField tfAccName = new JTextField("OwnerName");
                tfAccName.setColumns(15);
                final JButton bAddAccount = new JButton("Add");
                final JPanel addAccPanel = new JPanel();
                addAccPanel.add(tfAccName);
                addAccPanel.add(bAddAccount);                                
                bAddAccount.addActionListener(new ActionListener() {
                    @Override
                    public void actionPerformed(ActionEvent e) {
                        if (!tfAccName.getText().isEmpty()) {
                            requires().manage().instantiateAccount(tfAccName.getText());
                            tfAccName.setText("");
                        }
                    }
                });
                f.getContentPane().add(addAccPanel, BorderLayout.PAGE_START);
                accPanel.setLayout(new BoxLayout(accPanel, BoxLayout.Y_AXIS));
                f.getContentPane().add(accPanel, BorderLayout.CENTER);

                f.pack();
                f.setVisible(true);
                f.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
            }
        });
    }

    @Override
    protected AccountGUI make_AccountGUI() {
        return new AccountGUI() {

            private final JPanel panel = new JPanel();
            private final JLabel balance = new JLabel();

            @Override
            protected void start() {
                panel.add(new JLabel(requires().status().getOwner()));
                panel.add(balance);
                final JFormattedTextField amount = new JFormattedTextField(new Integer(0));
                amount.setColumns(5);
                panel.add(amount);
                final JButton bPlus = new JButton("+");
                bPlus.addActionListener(new ActionListener() {
                    @Override
                    public void actionPerformed(ActionEvent e) {
                        final int toAdd = ((Number) amount.getValue()).intValue();
                        requires().operations().deposit(toAdd);
                        updateBalance();
                    }
                });
                panel.add(bPlus);
                final JButton bMinus = new JButton("-");
                bMinus.addActionListener(new ActionListener() {
                    @Override
                    public void actionPerformed(ActionEvent e) {
                        final int toRem = ((Number) amount.getValue()).intValue();
                        requires().operations().withdraw(toRem);
                        updateBalance();
                    }
                });
                panel.add(bMinus);
                final JButton bRem = new JButton("Remove");
                bRem.addActionListener(new ActionListener() {
                    @Override
                    public void actionPerformed(ActionEvent e) {
                        accPanel.remove(panel);
                        f.pack();
                    }
                });
                panel.add(bRem);
                updateBalance();
                accPanel.add(panel);
                f.pack();
            }

            private void updateBalance() {
                balance.setText(""+requires().status().getBalance());
            }
        };
    }
}

We can notice that the remove button will simply remove the panel that contains references to the species.
Because the elements of the BankAccount species and its sub-components are all related to each others but not at all with the exterior, the fact that this only reference between the GUI and the species disappear means that the garbage collector of the JVM will remove the instance of the species and its content from the memory.

Executing¶

We can finally define a class to execute all of that:

package tutorial2;

import java.io.File;

public class Application {

    public static void main(String[] args) {
        new BankImpl(new File("/tmp/tutorial2-bank-logs/")).newComponent();
    }
}

Conclusion¶

This tutorial for SpeADL finishes here.

Wiki Page Resources¶