Developer Guide

This page gives an introduction into the project structure for developers who are interested to contribute to this project. Contribution from the community is most appreciated, as we aim for building a base to keep the tool development alive exceeding beyond the PERICLES project lifespan.

Setting up an Eclipse project

PeriCAT is developed using Eclipse. We used the m2e Eclipse plugin for maven integration, and EGit for git integration. To set up the project in Eclipse you will need a Java 7 installation, or higher. TODO: clone project from GitHub into Eclipse +test once released

Understanding the package structure

Six packages of source code can be found at src/main/java, and corresponding test sources at src/test/java.

• main: This package includes the Main class, which handles also command line start parameters. Furthermore this package contains classes for configuration, logging, the API for the integration into external tools (PeriCAT class), and the PET-Adapter.
• model: At this package you can find basic data structures for data sets and the user scenario. Furthermore here are classes to construct the bytestream of a payload sequence, including restoration metadata.
• view: Here are all the graphical user interface classes. The GUI class refers to three GUITabs, which contain different GUIPanels.
• controller: The main controller of the application is the “PeriCATController”. This package includes also its builder which is called once at tool start. The other controlling classes take care of more specific controlling tasks, e.g. handling of load and save, encapsulation, decapsulation etc. (Controllers for the decision mechanism are located at an own package.)
• decisionMechanism: This keeps all controlling classes for the decision mechanism.
• algorithm: At this package you can find a wrapper class for each integrated IE technique.

Integration of new techniques

One of the most frequent development tasks is probably the integration of a new Information Encapsulation technique into the tool. This section has a deeper look in how to resolve this task. First of all navigate to the algorithm package, and create a new class for your algorithm which extends the AbstractAlgorithm class. Let Eclipse add all unimplemented methods automatically. You can have a look at the other algorithm classes, to get implementation examples of these methods.

• encapsulate: This method gets a list of carrier and payload files and returns mostly one file which is the encapsulated file of all the passed files. The method can return more than one file, if necessary, but this is not common. Some algorithms, mostly packaging techniques, will handle carrier and payload files as equal. The distinction is for embedding algorithms which need to handle carrier and payload in a different way. The algorithm can use a model.PayloadSegment to store the payload together with restoration metadata in a well defined way.
• restore: This method gets one encapsulated file and returns the restored original files, as far as practicable. Some algorithms are only able to restore carrier or payload file. Have a look at the model.RestoredFile class. It contains information from the restoration metadata which are provided to the user. You can also add a note for the user, e.g. to explain why one of the files can’t be restored. A lot of information that has to be stored in the RestoredFile can be received from the model.PayloadSegment’s restoration metadata, if the algorithm has used this class.
• getName: This method should return a name string for the algorithm, which will be shown at the graphical user interface.
• getDescription: This method should return a description string for the algorithm, which will be shown to the user at the graphical user interface. Don’t spare with explanations!
• defineScenario: This method defines an ideal use scenario in which the algorithm should be used. It is used at the decision mechanism to suggest the user the use of an algorithm based on his/her scenario. Create a Scenario at the method with a name sting like “my algorithm scenario” have a look at the model.Criterion class to see a list of currently 11 criteria which have to be defined for your algorithm scenario use scenario.setCriterionValue(CRITERION, YES/NO); for each of the listed criteria to characterise your algorithm return the scenario
• configureCarrierFileFilter/configurePayloadFileFilter/configureDecapsulationFileFilter: We use the apache commons SuffixFileFilter to define which file types are allowed as carrier files, payload files, or as input for the decapsulation. The file filters are used automatically before encapsulation or decapsulation.
• fulfilledTechnicalCriteria: This method is called automatically similar to the file filters before encapsulation. Any technical constraints for encapsulation for the carrier and payload files can be defined at this method, e.g. if the payload size fulfills the constraints to use the algorithm. Algorithms for which the user’s data set can’t fulfill the technical criteria or the file type check are displayed as red at the graphical user interface.
• In parallel to your algorithm class, you can create a unit test class at src/test/java/algorithm. This is highly recommended.

The maven pom.xml file can be used to add external sources to the project, if these sources use maven. If you want to add external sources which are not using maven, create a directory at the ExternalTools directory and copy the sources there.

Once the algorithm is finished open the main.Configuration class and add your algorithm to the list of available algorithms at the getAlgorithms() method. This is also the place where you can comment out techniques, which you want to exclude from your PeriCAT instance.

Integration of new decision criteria

If the number of integrated algorithms increases, the necessity to distinguish between the algorithm characteristics becomes more urgent to refine the decision mechanism. The introduction of new decision criteria is quite easy.

• Open the model.Criterion class
• Add a static string to the top of this class which identifies your algorithm, similar to the existing ones
• Open the model.Scenario class
• Create a new Criterion at the Scenario constructor using the ID which you defined at the Criterion class, similar to the existing criteria. The description is used as tool tip at the graphical user interface.
• Add your criterion at the bottom of the constructor with addCriterion(criterion);
• Use your new criterion at the ideal scenarios of the algorithms. This has to be done manually for all algorithms. The default weighting value of a criterion is 50 (middle), if it is not set for a scenario.