Initial commit

.gitignore

@@ -0,0 +1,15 @@
+.idea
+.gradle
+*.iml
+applet/out
+applet/build
+simulator/build
+simulator/out
+tester/build
+tester/out
+
+*.class
+*.cap
+*~
+# virtual machine crash logs, see http:https://www.java.com/en/download/help/error_hotspot.xml
+hs_err_pid*

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "libs-sdks"]
+ path = libs-sdks
+ url = https://github.com/martinpaljak/oracle_javacard_sdks/

.travis.yml

@@ -0,0 +1,6 @@
+language: java
+jdk: oraclejdk11
+script:
+ - ./gradlew check --info
+ - ./gradlew buildJavaCard --info
+

INTEGRATION.md

@@ -0,0 +1,306 @@
+# Using this template with existing code
+
+This template is suitable for starting a new JavaCard project as it provides all 
+required tools to start developing JavaCard applets straight away.
+Readme shows how to use this template to run the HelloWorld.
+
+Here follows the quick overview how to use this template with already existing 
+JavaCard code.
+
+## Variant A - Copy the code
+
+This variant is suitable for no longer maintained JavaCard codes or not 
+git-versioned codes. This is rather simple as just pure copying of the sources will
+do the job. 
+
+- Clone this template
+- Copy the java files to `applet/src/main/java`.
+
+#### 1. Clone the template 
+Clone the template repository to a new directory.
+
+```bash
+git clone --recursive [email protected]:crocs-muni/javacard-gradle-template-edu.git javacard-calculator-wrapper
+```
+
+We now reinitialize the git history of the template. The reason is
+you typically want to have a clean commit history without unrelated template commits.
+
+```bash
+cd javacard-calculator-wrapper
+rm -rf .git
+rm -rf libs-sdks/
+git init
+git add .
+git commit -m 'Initial commit'
+git submodule add https://github.com/martinpaljak/oracle_javacard_sdks.git libs-sdks
+git add libs-sdks
+git commit -m 'SDKs added'
+```
+
+#### 2. Test the template. 
+The command will download all required dependencies. We make
+sure the template works before doing major changes. 
+
+```bash
+./gradlew test
+```
+
+## Variant B - Maintained code
+
+With maintained code, it is a bit difficult as we usually want to 
+pull-request our changes to the original repository. In that case, we cannot use
+the copy variant A as the git history will be lost and the pull request cannot be created. 
+
+Depending on the project size we have another two options:
+
+### B.1 Use the template project structure
+
+In this case, we change the existing project structure and we 
+basically transform it to the structure of the template. 
+
+It would go like this:
+
+- Fork the existing JavaCard repository to your own account so you can do pull requests.
+- Copy the template files (libs, libs-sdk, gradle, applet, ...) to the forked repository
+- Move the existing code to the right place, `applet/src/main/java`
+- Modify `applet/build.gradle`, define CAP file parameters as previously defined, probably in `pom.xml` (Maven) or `build.xml` (Ant)
+
+
+This approach is obviously suitable for simple/small projects lacking proper gradle support. 
+If the project is big and actively maintained owners probably won't be very cheerful to change the whole project structure
+and another approach has to be chosen.
+
+
+### B.2 Non-intrusive gradle extension
+
+This variant is very lightweight in term of the original repository modifications. 
+We add only minimal gradle-related files to the project keeping the original
+project structure intact. This will require adapting gradle paths a bit but the benefit
+is the original project can work simultaneously in multiple build environments 
+and the modifications are small thus the probability of a successful merge is easier. 
+The downside is there is no wrapping gradle root module which does not have to
+be a blocker, and this issue can be addressed later when the project grows large. 
+
+
+I will demonstrate this in the example:
+https://github.com/sgamerith/javacard-calculator
+
+#### 1. Fork the project.
+Fork the javacard-calculator repository to your account. 
+This step is required so you can work with the existing maintained code, 
+submit pull requests, etc.
+
+My fork I use in this description is here (you will obviously use your fork address):
+https://github.com/ph4r05-edu/javacard-calculator-gradle
+
+#### 2. Add JavaCard SDK submodules:
+
+```
+git submodule add https://github.com/martinpaljak/oracle_javacard_sdks.git libs-sdks
+```
+
+The SDKs are required to build CAP files from the applet.
+
+SDKs can also be in your home dir or outside the project structure, depends on your consideration.
+The gradle script will have to be changed to reflect the SDK directory location. 
+Current version assumes SDKs are in the `libs-sdks` directory in the project root. 
+If the `jckit` property is not set manually in the `build.gradle` 
+the `JC_HOME` environment variable with the SDK directory will be used.
+
+#### 3. Copy `build.gradle`
+Copy the main gradle files:
+```
+./gradle
+./gradlew
+./gradlew.bat
+build.gradle
+```
+
+The source paths with java files have to be set if it differs from the default gradle paths.
+
+This particular project has source paths as gradle expects, so no additional configuration is needed.
+
+For next steps follow steps 6-9 inclusive from the following list.
+
+#### Demo
+
+The result of this scenario is in this repo: https://github.com/ph4r05-edu/javacard-calculator-gradle
+
+Take a look at commits to see the performed modifications.
+
+### B.3 Git submodule approach
+
+If you feel that changing the project structure won't be merged via pull request, it has to be done a bit differently.
+This approach preserves existing project structure by embedding the project into the template project
+which acts as a wrapper. The existing project is added to the wrapper as a [git-submodule].
+
+I will demonstrate this in the example:
+https://github.com/sgamerith/javacard-calculator
+
+#### 1. Fork the project.
+Fork the javacard-calculator repository to your account. 
+This step is required so you can work with the existing maintained code, 
+submit pull requests, etc.
+
+My fork I use in this description is here (you will obviously use your fork address):
+https://github.com/ph4r05-edu/javacard-calculator
+
+#### 2. Clone the template 
+Clone the template repository to a new directory.
+
+```bash
+git clone --recursive [email protected]:crocs-muni/javacard-gradle-template-edu.git javacard-calculator-wrapper
+```
+
+We now reinitialize the git history of the template. The reason is
+you typically want to have a clean commit history without unrelated template commits.
+
+```bash
+cd javacard-calculator-wrapper
+rm -rf .git
+rm -rf libs-sdks/
+git init
+git add .
+git commit -m 'Initial commit'
+git submodule add https://github.com/martinpaljak/oracle_javacard_sdks.git libs-sdks
+git add libs-sdks
+git commit -m 'SDKs added'
+```
+
+#### 3. Test the template. 
+The command will download all required dependencies. We make
+sure the template works before doing major changes. 
+
+```bash
+./gradlew test
+```
+
+#### 4. Cleanup
+Remove HelloWorld related files.
+
+```bash
+/bin/rm -rf applet/src
+```
+
+Our current project has working tests with JCardSim so we dont need to use 
+our test/cardtools utilities. If your particular project has no test 
+you may need to add tests from the scratch. The HelloWorld test suite is a good 
+inspiration. You may backup `applet/src/test` somewhere if you need it later.
+
+
+#### 5. Add the project as a git submodule
+Add the project we are going to work on as a submodule:
+
+```bash
+# Add the project as a submodule
+# In your case use your fork address.
+git submodule add https://github.com/ph4r05-edu/javacard-calculator applet/project
+```
+
+#### 6. Set the source paths.
+We have to adjust gradle source paths (folders with java files / packages) a bit as 
+we placed the project as a submodule which has source files on a different place
+than gradle expects by default. 
+
+The main reason is that we wrapped the whole project
+in the `project` folder. However, this approach is flexible as we don't need 
+the project to follow some standard folder hierarchy.
+
+Update `applet/build.gradle`: Add the following piece of 
+code below `dependencies` section (note: not inside `buildscript` section).
+
+```groovy
+sourceSets {
+ main {
+ java {
+ srcDir 'project/src/main/java'
+ }
+ }
+
+ test {
+ java {
+ srcDir 'project/src/test/java'
+ }
+ resources {
+ srcDir 'project/src/test/resources'
+ }
+ }
+}
+```
+
+This configures gradle source directories. 
+If you are using IntelliJ Idea press Gradle refresh button so 
+Idea gets a new file layout also.
+
+Gradle refresh button: right-hand side vertical bar -> Gradle -> Blue refresh button.
+
+
+#### 7. Fix the project
+
+Now you may end up with a project that won't build. 
+In this particular case a dependency is missing. CalculatorTest.java is missing 
+`import org.apache.commons.lang3.ArrayUtils;`
+
+By Googling you may find the following page
+https://mvnrepository.com/artifact/org.apache.commons/commons-lang3/3.0
+
+Which suggests adding the following line to the `applet/build.gradle` to the `dependencies` section
+
+```groovy
+dependencies{
+ compile group: 'org.apache.commons', name: 'commons-lang3', version: '3.0'
+}
+```
+
+Refresh the Gradle project
+
+Now the project is still broken. The culprit is the following line:
+
+```java
+ResponseAPDU actual = simulator.transmitCommand(commandAPDU);
+```
+
+Obviously, the simulator contract for the method `transmitCommand` has changed.
+We change it to the following form:
+
+```java
+ResponseAPDU actual = new ResponseAPDU(simulator.transmitCommand(commandAPDU.getBytes()));
+```
+
+Note: 
+The changes performed in the test file are visible only in the submodule repository, not in the main wrapper.
+Wrapper repository does not see the change so you cannot commit it to the wrapper, but you have to do it in the submodule.
+
+#### 8. Test
+
+Now you are ready to test the project.
+
+#### 9. Modify Cap settings
+
+Now you need to adapt CAP build configuration from the previous project. 
+Modify `applet/build.gradle`, the `javacard` section.
+Mainly adjust package and the applet class name.
+
+Configuration directives are very similar. When you are done, build cap file
+
+```bash
+./gradlew build
+```
+
+#### 10. Push wrapper repository
+
+Create a new GitHub repository for your wrapper. Then add the remote repository 
+and push.
+
+```bash
+git remote add origin https://github.com/ph4r05-edu/javacard-calculator-wrapper.git
+git push origin master
+```
+
+#### Demo
+
+- https://github.com/ph4r05-edu/javacard-calculator-wrapper
+- https://github.com/ph4r05-edu/javacard-calculator 
+
+[git-submodule]: https://git-scm.com/docs/git-submodule

LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Dusan Klinec, Martin Paljak, Petr Svenda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+