CleanSheets is a spreadsheet application for the Java platform, featuring Excel-style formulas and an extension mechanism. The application requires the Java 2 Platform Standard Edition 5.0 to compile and run.
This is a special fork from the original CleanSheets project that is used by the LAPR4 course of the Informatics Engineering undergraduate program at ISEP (http://www.isep.pt).
Questions and comments can be addressed to Alexandre Braganca (atb@isep.ipp.pt).
This technical documentation is divided in the following sections:
Project Workflow
Application Startup
Extension Mechaninsm
Domain Model
Persistence
Languages
Shared Memory
This sections explains the workflow of the LAPR4 project.
The team and the repository
The LAPR4 project is to be developed by a group (team) of 3 students during 3 weeks at full time.
Each group will have a supervisor which is a teacher of LAPR4.
Each group should make a fork of the CleanSheets repository at bitbucket (https://bitbucket.org). This is a Git repository.
The resulting repository should by private and acessible only by the group members, the group supervisor and the LAPR4 regent (atb@isep.ipp.pt)
The repository should also have "issues" enabled, since these will be used during the project to register the work of each group member.
The requirements iteractions
The project regards extensions and adaptations to CleanSheets. The requirements of these extensions and adaptations are presented and explained to the group in a iteratively fashion.
At the beginning of each week new requirements are presented to the group. The group is expected to use a scrum-like work method to develop the project.
At the beginning of each week the group should plan the week's "sprint" in order to address the requirements of that week. This should be done with the help and supervision of the Management teachers at the management module class at the beginning of the week.
Issues should be used to register how requirements will be addressed and by whom. It is of paramount importance to use the "issues" feature of bitbucket because it will serve as a major input for the assessment of the project.
The project structure
As stated before each team will be composed of 3 students. The project duration is 3 weeks. The functional requirements are devided in 3 major areas: persistence; languages and shared memory. Each member of a team is supposed to address a specific functional area each week. However that are also common tasks, like tool support, research, documentation, etc. that need to be addressed by the team. The planning of all these tasks is one of the major results of the week's planning class, as denoted before.
The individual assessment of each member is majorated by how many different functional areas has he worked on.
For instance, a group member that addressed 3 different functional areas during the 3 weeks will (normally) have his work better graded than a group member that only addressed a single functional area during the same 3 weeks.
Excepcionally there can be groups with only 2 members. Even so, each member of these groups can address as many as 3 functional areas but less deeply. For instance, a specific student in this case could address the first week requirements for the persistence area during week 1, the second week requirements for the languages area during week 2 (assuming his collegue had worked this area in the first week) and the first week requirements for the shared memory area during the final week.
Each team should configure the issues features of the project in bitbucket as follows:
- Components: persistence; languages; shared memory.
- Milestones: week1(alfa), week2(beta), week3(release candidate).
- Version: 1.5a
Working with issues in bitbucket
At the beginning of the week the team shall meet to plan the sprint. A series of issues resulting from the requirements should be defined. Each team member should be responsible for one or more issues. Issues should be registered in bitbucket as described earlier.
Each issue registered in bitbucket is identified by an integer number. Every time a team member commits work in the repository the commit message should contain the related issue number as weel as the email of the author. The following is an example of a commit message "223322@isep.ipp.pt: added the setup classes for the annotation extension ref #1"
There are some keyworks that are specially identified by bitbucket in commits and result in some automatic behavior. In the previous example, the keyword "ref" followed by "#" and the issue number will automatically generate a comment in the issue 1 with the text of the commit message as weel as a reference to the changeset produced by the commit. Other very usefull keyword is "close", which changes the state of the issue to closed. This keyword should be used when the author enters the last commit regarding an issue.
Team members should also use bitbucket to register comments regarding important events or notes in issues. For instance, if a team member did some specific task related to an issue that did not result in a commit he can (shall) register that in a comment of the issue. For instance "Done some research on how to validate xml files. Going to document this in a new section of the technical documentation in a future commit.". Comments in issues can also be used to alert other team members of encountered problems, for instance.
Issues, Requirements and Use Cases
At the beginning of each week a new requirements document is published. From the statement of the requirements one or more use cases can be identified. Usually support tasks are not identified as use cases (i.e., setup or configurations required to support a use case) if they will be addressed by the same team member that will be responsible for the use case.
Each use case will usually also give origin to one issue in bitbucket that will be assigned to one team member.
However, even in these cases, a issue that resulted from a use case will usually require several tasks (each item ~ a working day):
- to scope the problem (i.g., what information to include/exclude when saving a spreadsheet) and to address specific technical problems (e.g. study how xml files can be validated);
- detailed analysis of the use case and first draft of a solution by proposing a use case realization. Identification of possible updates to the domain model. The first draft of unit tests for the use case;
- design (apply design patterns, etc.) and coding of the solution. Address the technical documentation (javadoc);
- when coding is completed do as much tests as possible (this time use case tests, not unit tests). Complete the technical documentation (e.g., domain model diagram, use case relization diagram, technical descriptions, etc.). Commit the issue and mark it as closed so that other team member can run use case tests on it;
- run use case tests (this should be done by a team member that was not the author of the use case). If bugs are detected reopen the issue so that the author can address the bug. When all the issues (use cases) of the sprint are tested and closed a tag should be added to the repository to mark the milestone.
Unit Tests and Use Case Tests
The member that will address a specific requirement (i.e., issue) will also be responsible for: the unit tests regarding the classes used to implement the requirement and the technical documentation of the requirement (i.e., updating this documentation).
However, it is expected that use case tests (i.e., manual tests based on the use cases) be executed by a member that did not design and implement the use case.
The use case tests should be executed after the issue (requirement) is closed by the member that implemented the requirement. If the member that executes the use case test identifies a problem or a bug he should re-open the issue and alert his collegue to this situation.
Obviouslly it is a goal of the developer not to close issues (requirements) that may have problems/bugs. Also, for a use case tester the goal is to identify as many problems/bugs as possible before the release of a version to the end user.
Technical documentation
The technical documentation of the project is the one presented in this collection of html files that was generated by javadoc. Javadoc is a tool (included in the java sdk) that essentially generates the technical documentation from special comments on the source code of the project.
Therefore the technical documentation that javadoc usually produces regards documentation about elements of the code (classes, methods, etc.). For this kind of project this is not enough since a very important part of the technical documentation regards aspects that relate to other stages of the software development process, like analysis and design. In these cases, documentation usually does not directely relate to code elements. Formats such as narrative text or visual diagrams are used (e.g., UML diagrams).
Since javadoc does not provide direct support to generate UML diagrams a tool named PlanUML (plantuml.sourceforge.net) was adopted to generate the diagrams and incorporate them in the html that is generated with javadoc.
PlantUML is not a drawing tool, it is a tool that generates diagrams from textual descriptions of the diagrams, by using a simple and intuitive textual language.
These textual descriptions of the diagrams can be incorporated in comments, near the javadoc comments. Javadoc directives can then reference the diagrams (since plantuml will generate an image for each diagram).
All the documentation of this technical documentation was generate from javadoc comments inside the java source files of the project (with plantuml diagrams) except for this page (javadoc-overview.html) that is the main and default page (and is not generated by javadoc but is included in the folder containing the generated documentation).
By following this approach it becomes more easy to maintain the documentation in synch with the code and always in control by the DVCS (Distributed Version Control System).
The PlanUML jar is included in the project (in the lib folder). PlanUML requires that Graphviz (http://www.graphviz.org/) be installed in th system for the generation of all types of diagrams except sequence diagrams.
Design
Cleansheets uses a lot of design patterns. You should study carefully its code to identify and learn how several design patterns - that you have studied in other courses of the Informatics Engineering program - were applied.
We invite you to use an IDE (Netbeans or Eclipse) to debug the application and learn the code.
You will see that one of the principles of the extension mechanism of cleansheets is also known as the hollywood principle: "don't call us, we will call you". This principle is widely used in frameworks and is known as the Inversion of Control (IOC) pattern. In this pattern "your" code don't call the framework (base) code, the framework code will call "your" code when needed.
The structure of the repository
This section describes the artifacts that compose the project (files and folders).
These are the main artifacts:
- readme.txt: This file contains the "must read before all things" information. For instance it should state how to generate and open this documentation.
- src: This folder contains the java source code of the project.
- src-resources: This folder contains other artifacts that are used/necessary to configure or build the project but are not java source files (e.g., image files, property files)
- src-tests: This folder contains the source code for the unit tests
- scripts: This folder contains scripts that can be used to execute several tasks (e.g., build the cleanseets jar, generate the technical documentation)
- lib: This folder contains dependencies that are required for building cleansheets. Initially antlr.jar, junit-4.10.jar and plantuml.jar.
- legal: Legal information regarding the Cleansheets project.
- doc: This folder contains files related to the technical documentation that are not generated from the javadoc comments in the source files. The documentation generated from javadoc is created in the subfolder "api" (which is not required to be in the DVCS because it is generated)
- dist: This folder should contain all files that are required to execute cleansheets. Initially it contains antlr.jar and csheets.jar. Since these files result from the building process they are not required to be controlled by the DVCS.
- tmp-build: This folder contains the output of the building process. It should not be in the DVCS.
- tmp-build-tests: This folder contains the output of building the junit tests. It should not be in the DVCS.
These are the artifacts specific of eclipse:
- .classpath: This file contains several paths of the eclipse project
- .project: This is the main project file of the eclipse project
- res: This folder contains de result of the building process of eclipse. It should not be in the DVCS.
These are the artifacts specific of netbeans:
- nbproject: This is the main folder for the netbeans project
- nbproject/private: This subfolder is not required to be tracked by the DVCS
- build.xml: This file is auto-generated by the netbeans. It should not be in the DVCS.
- manifest.mf: This subfolder is not required to be tracked by the DVCS
- build: This folder contains the result of the netbeans building process. It should not be tracked by the DVCS
- nbdist: This folder is not required to be tracked by the DVCS
- lib/nblibraries.properties: This is required for Netbeans
These are the artifacts required for the DVCS (Git):
- .gitignore: This file contains entries that specify files or folders that we want to exclude from the DVCS
- .git: This folder contains all the data of the repository
Scripts
The project includes scripts that are used to accomplish several tasks in the project. Even if the team uses netbeans or eclipse as an environment for the development process it should always maintain the scripts updated. The scripts will always be used for presentation of the project and for evaluations.
The project comes with scripts for Linux and Mac OS (.sh) and for Windows (.bat). Team members should keep the scripts up-to-date.
Scripts should be executed within a terminal/console and with the "scripts" folder as current folder
To build the Cleansheets jar:
./cc.sh - this generates lexer and parser code from the .g files
./makejar.sh - this compiles the java code (by calling build.sh); adds the resource files; creates the csheets.jar file and updates the dist folder
To run cleansheets (from the builded csheets.jar in the dist folder):
./run.sh
To build the technical documentation of the project:
./makeuml.sh - builds the diagrams (images) from their descriptions inside java comments and in javadoc-overview.html.
./makedoc.sh - buils the javadoc documentation of the project from the javadoc comments it encounters in the java source code of the project
To build the unit tests of the project:
./build_tests.sh - compiles the junit tests
./run_tests.sh - runs the junit tests
To run a simple console to experiment formulas
./console.sh - nao actualizado
To clean all the contents of folders that only contain generated files (dist, tmp-build, tmp-build-tests)
./clean.sh
The following diagram illustrates how the application starts. Particularly, it illustrates the initial loading of extensions by the application.
The extensions of the application are "special" classes that are registered in specific property files as denoted by the diagram.
Finally (but also within the main method) the user interface is created.
The following diagram depicts this last setup task.
The MenuBar class will build the menu options. These menu options include not only the base menu options but also menu options that may have been declared by the application extensions.
Place here documentation regarding the extension mechanism.
Place here documentation regarding the domain model.
The formulas...
Place here documentation regarding the persistence functional area of the project.
Place here documentation regarding the languages functional area of the project.
Place here documentation regarding the shared memory functional area of the project.
This is a special fork from the original CleanSheets project that is used by the LAPR4 course of the Informatics Engineering undergraduate program at ISEP (http://www.isep.pt).
Questions and comments can be addressed to Alexandre Braganca (atb@isep.ipp.pt).
Technical documentation regarding LAPR4 project extensions
This technical documentation is divided in the following sections:
| Project Workflow |
|---|
This sections explains the workflow of the LAPR4 project.
The team and the repository
The LAPR4 project is to be developed by a group (team) of 3 students during 3 weeks at full time.
Each group will have a supervisor which is a teacher of LAPR4.
Each group should make a fork of the CleanSheets repository at bitbucket (https://bitbucket.org). This is a Git repository.
The resulting repository should by private and acessible only by the group members, the group supervisor and the LAPR4 regent (atb@isep.ipp.pt)
The repository should also have "issues" enabled, since these will be used during the project to register the work of each group member.
The requirements iteractions
The project regards extensions and adaptations to CleanSheets. The requirements of these extensions and adaptations are presented and explained to the group in a iteratively fashion.
At the beginning of each week new requirements are presented to the group. The group is expected to use a scrum-like work method to develop the project.
At the beginning of each week the group should plan the week's "sprint" in order to address the requirements of that week. This should be done with the help and supervision of the Management teachers at the management module class at the beginning of the week.
Issues should be used to register how requirements will be addressed and by whom. It is of paramount importance to use the "issues" feature of bitbucket because it will serve as a major input for the assessment of the project.
The project structure
As stated before each team will be composed of 3 students. The project duration is 3 weeks. The functional requirements are devided in 3 major areas: persistence; languages and shared memory. Each member of a team is supposed to address a specific functional area each week. However that are also common tasks, like tool support, research, documentation, etc. that need to be addressed by the team. The planning of all these tasks is one of the major results of the week's planning class, as denoted before.
The individual assessment of each member is majorated by how many different functional areas has he worked on.
For instance, a group member that addressed 3 different functional areas during the 3 weeks will (normally) have his work better graded than a group member that only addressed a single functional area during the same 3 weeks.
Excepcionally there can be groups with only 2 members. Even so, each member of these groups can address as many as 3 functional areas but less deeply. For instance, a specific student in this case could address the first week requirements for the persistence area during week 1, the second week requirements for the languages area during week 2 (assuming his collegue had worked this area in the first week) and the first week requirements for the shared memory area during the final week.
Each team should configure the issues features of the project in bitbucket as follows:
- Components: persistence; languages; shared memory.
- Milestones: week1(alfa), week2(beta), week3(release candidate).
- Version: 1.5a
Working with issues in bitbucket
At the beginning of the week the team shall meet to plan the sprint. A series of issues resulting from the requirements should be defined. Each team member should be responsible for one or more issues. Issues should be registered in bitbucket as described earlier.
Each issue registered in bitbucket is identified by an integer number. Every time a team member commits work in the repository the commit message should contain the related issue number as weel as the email of the author. The following is an example of a commit message "223322@isep.ipp.pt: added the setup classes for the annotation extension ref #1"
There are some keyworks that are specially identified by bitbucket in commits and result in some automatic behavior. In the previous example, the keyword "ref" followed by "#" and the issue number will automatically generate a comment in the issue 1 with the text of the commit message as weel as a reference to the changeset produced by the commit. Other very usefull keyword is "close", which changes the state of the issue to closed. This keyword should be used when the author enters the last commit regarding an issue.
Team members should also use bitbucket to register comments regarding important events or notes in issues. For instance, if a team member did some specific task related to an issue that did not result in a commit he can (shall) register that in a comment of the issue. For instance "Done some research on how to validate xml files. Going to document this in a new section of the technical documentation in a future commit.". Comments in issues can also be used to alert other team members of encountered problems, for instance.
Issues, Requirements and Use Cases
At the beginning of each week a new requirements document is published. From the statement of the requirements one or more use cases can be identified. Usually support tasks are not identified as use cases (i.e., setup or configurations required to support a use case) if they will be addressed by the same team member that will be responsible for the use case.
Each use case will usually also give origin to one issue in bitbucket that will be assigned to one team member.
However, even in these cases, a issue that resulted from a use case will usually require several tasks (each item ~ a working day):
- to scope the problem (i.g., what information to include/exclude when saving a spreadsheet) and to address specific technical problems (e.g. study how xml files can be validated);
- detailed analysis of the use case and first draft of a solution by proposing a use case realization. Identification of possible updates to the domain model. The first draft of unit tests for the use case;
- design (apply design patterns, etc.) and coding of the solution. Address the technical documentation (javadoc);
- when coding is completed do as much tests as possible (this time use case tests, not unit tests). Complete the technical documentation (e.g., domain model diagram, use case relization diagram, technical descriptions, etc.). Commit the issue and mark it as closed so that other team member can run use case tests on it;
- run use case tests (this should be done by a team member that was not the author of the use case). If bugs are detected reopen the issue so that the author can address the bug. When all the issues (use cases) of the sprint are tested and closed a tag should be added to the repository to mark the milestone.
Unit Tests and Use Case Tests
The member that will address a specific requirement (i.e., issue) will also be responsible for: the unit tests regarding the classes used to implement the requirement and the technical documentation of the requirement (i.e., updating this documentation).
However, it is expected that use case tests (i.e., manual tests based on the use cases) be executed by a member that did not design and implement the use case.
The use case tests should be executed after the issue (requirement) is closed by the member that implemented the requirement. If the member that executes the use case test identifies a problem or a bug he should re-open the issue and alert his collegue to this situation.
Obviouslly it is a goal of the developer not to close issues (requirements) that may have problems/bugs. Also, for a use case tester the goal is to identify as many problems/bugs as possible before the release of a version to the end user.
Technical documentation
The technical documentation of the project is the one presented in this collection of html files that was generated by javadoc. Javadoc is a tool (included in the java sdk) that essentially generates the technical documentation from special comments on the source code of the project.
Therefore the technical documentation that javadoc usually produces regards documentation about elements of the code (classes, methods, etc.). For this kind of project this is not enough since a very important part of the technical documentation regards aspects that relate to other stages of the software development process, like analysis and design. In these cases, documentation usually does not directely relate to code elements. Formats such as narrative text or visual diagrams are used (e.g., UML diagrams).
Since javadoc does not provide direct support to generate UML diagrams a tool named PlanUML (plantuml.sourceforge.net) was adopted to generate the diagrams and incorporate them in the html that is generated with javadoc.
PlantUML is not a drawing tool, it is a tool that generates diagrams from textual descriptions of the diagrams, by using a simple and intuitive textual language.
These textual descriptions of the diagrams can be incorporated in comments, near the javadoc comments. Javadoc directives can then reference the diagrams (since plantuml will generate an image for each diagram).
All the documentation of this technical documentation was generate from javadoc comments inside the java source files of the project (with plantuml diagrams) except for this page (javadoc-overview.html) that is the main and default page (and is not generated by javadoc but is included in the folder containing the generated documentation).
By following this approach it becomes more easy to maintain the documentation in synch with the code and always in control by the DVCS (Distributed Version Control System).
The PlanUML jar is included in the project (in the lib folder). PlanUML requires that Graphviz (http://www.graphviz.org/) be installed in th system for the generation of all types of diagrams except sequence diagrams.
Design
Cleansheets uses a lot of design patterns. You should study carefully its code to identify and learn how several design patterns - that you have studied in other courses of the Informatics Engineering program - were applied.
We invite you to use an IDE (Netbeans or Eclipse) to debug the application and learn the code.
You will see that one of the principles of the extension mechanism of cleansheets is also known as the hollywood principle: "don't call us, we will call you". This principle is widely used in frameworks and is known as the Inversion of Control (IOC) pattern. In this pattern "your" code don't call the framework (base) code, the framework code will call "your" code when needed.
The structure of the repository
This section describes the artifacts that compose the project (files and folders).
These are the main artifacts:
- readme.txt: This file contains the "must read before all things" information. For instance it should state how to generate and open this documentation.
- src: This folder contains the java source code of the project.
- src-resources: This folder contains other artifacts that are used/necessary to configure or build the project but are not java source files (e.g., image files, property files)
- src-tests: This folder contains the source code for the unit tests
- scripts: This folder contains scripts that can be used to execute several tasks (e.g., build the cleanseets jar, generate the technical documentation)
- lib: This folder contains dependencies that are required for building cleansheets. Initially antlr.jar, junit-4.10.jar and plantuml.jar.
- legal: Legal information regarding the Cleansheets project.
- doc: This folder contains files related to the technical documentation that are not generated from the javadoc comments in the source files. The documentation generated from javadoc is created in the subfolder "api" (which is not required to be in the DVCS because it is generated)
- dist: This folder should contain all files that are required to execute cleansheets. Initially it contains antlr.jar and csheets.jar. Since these files result from the building process they are not required to be controlled by the DVCS.
- tmp-build: This folder contains the output of the building process. It should not be in the DVCS.
- tmp-build-tests: This folder contains the output of building the junit tests. It should not be in the DVCS.
These are the artifacts specific of eclipse:
- .classpath: This file contains several paths of the eclipse project
- .project: This is the main project file of the eclipse project
- res: This folder contains de result of the building process of eclipse. It should not be in the DVCS.
These are the artifacts specific of netbeans:
- nbproject: This is the main folder for the netbeans project
- nbproject/private: This subfolder is not required to be tracked by the DVCS
- build.xml: This file is auto-generated by the netbeans. It should not be in the DVCS.
- manifest.mf: This subfolder is not required to be tracked by the DVCS
- build: This folder contains the result of the netbeans building process. It should not be tracked by the DVCS
- nbdist: This folder is not required to be tracked by the DVCS
- lib/nblibraries.properties: This is required for Netbeans
These are the artifacts required for the DVCS (Git):
- .gitignore: This file contains entries that specify files or folders that we want to exclude from the DVCS
- .git: This folder contains all the data of the repository
Scripts
The project includes scripts that are used to accomplish several tasks in the project. Even if the team uses netbeans or eclipse as an environment for the development process it should always maintain the scripts updated. The scripts will always be used for presentation of the project and for evaluations.
The project comes with scripts for Linux and Mac OS (.sh) and for Windows (.bat). Team members should keep the scripts up-to-date.
Scripts should be executed within a terminal/console and with the "scripts" folder as current folder
To build the Cleansheets jar:
./cc.sh - this generates lexer and parser code from the .g files
./makejar.sh - this compiles the java code (by calling build.sh); adds the resource files; creates the csheets.jar file and updates the dist folder
To run cleansheets (from the builded csheets.jar in the dist folder):
./run.sh
To build the technical documentation of the project:
./makeuml.sh - builds the diagrams (images) from their descriptions inside java comments and in javadoc-overview.html.
./makedoc.sh - buils the javadoc documentation of the project from the javadoc comments it encounters in the java source code of the project
To build the unit tests of the project:
./build_tests.sh - compiles the junit tests
./run_tests.sh - runs the junit tests
To run a simple console to experiment formulas
./console.sh - nao actualizado
To clean all the contents of folders that only contain generated files (dist, tmp-build, tmp-build-tests)
./clean.sh
| Application Startup |
|---|
The extensions of the application are "special" classes that are registered in specific property files as denoted by the diagram.
Finally (but also within the main method) the user interface is created.
The following diagram depicts this last setup task.
The MenuBar class will build the menu options. These menu options include not only the base menu options but also menu options that may have been declared by the application extensions.
| Extension Mechanism |
|---|
| Domain Model |
|---|
Place here documentation regarding the domain model.
The formulas...
| Persistence |
|---|
| Languages |
|---|
| Shared Memory |
|---|
- Version:
- 1.4c, 1.4b
- Author:
- Alexandre Braganca, Einar Pehrson