|
1 | | -# liquidjava-examples |
2 | | -Examples to use with [LiquidJava](https://catarinagamboa.github.io/liquidjava.html) |
| 1 | +# LiquidJava Examples |
| 2 | + |
| 3 | +Welcome to the LiquidJava examples repository! |
| 4 | + |
| 5 | +This collection demonstrates how to use LiquidJava, a powerful extension for Java that enables expressive type refinements through annotations. Whether you're new to LiquidJava or looking to deepen your understanding, these examples will help you explore its capabilities and learn how to enhance your Java code with sophisticated type checking. |
| 6 | + |
| 7 | +For more information about LiquidJava, visit our [website](https://catarinagamboa.github.io/liquidjava.html)! |
| 8 | + |
| 9 | +## Development Environment Setup |
| 10 | + |
| 11 | +### Setup Instructions |
| 12 | + |
| 13 | +#### Option 1: Using Codespaces or Dev Containers (Recommended) |
| 14 | + |
| 15 | +1. Open the repository in GitHub Codespaces or use VS Code's "Remote-Containers: Open Folder in Container" command. |
| 16 | +2. Install the extension: View → Extensions → ... → Install from VSIX → `/workspaces/liquidjava-examples/extension/liquid-java-0.0.15.vsix` |
| 17 | +3. After the information that the extension is activated, do `Ctrl + Shift + P` and write `Developer: Reload Window ` |
| 18 | +4. Open examples: File → Open Folder → `examples/demo/src/` |
| 19 | + |
| 20 | + |
| 21 | + |
| 22 | + |
| 23 | + |
| 24 | +#### Extension Activation |
| 25 | + |
| 26 | +- The extension may take some time to be activated. While a small wheel in the bottom right of VS Code window is spinning, the extension is being loaded. |
| 27 | +- The extension will only activate when opening a Java project with the liquidjava-api.jar present. |
| 28 | + |
| 29 | + |
| 30 | +#### Option 2: Manual Setup |
| 31 | + |
| 32 | +If the automatic setup didn't work correctly, follow these manual steps: |
| 33 | + |
| 34 | +1. Install Git LFS if not already installed: |
| 35 | + ```bash |
| 36 | + sudo apt-get update && sudo apt-get install -y git-lfs |
| 37 | + git lfs install |
| 38 | + ``` |
| 39 | + |
| 40 | +2. Pull LFS files: |
| 41 | + ```bash |
| 42 | + git lfs pull |
| 43 | + ``` |
| 44 | + |
| 45 | +3. Install the extension: |
| 46 | + - In VS Code, go to the Extensions view (View → Extensions) |
| 47 | + - Click on the "..." (More Actions) button |
| 48 | + - Select "Install from VSIX..." |
| 49 | + - Navigate to `extension/liquid-java-0.0.15.vsix` in the repository |
| 50 | + - Click "Install" |
| 51 | + |
| 52 | + Alternatively, use the terminal: |
| 53 | + ```bash |
| 54 | + code --install-extension extension/liquid-java-0.0.15.vsix |
| 55 | + ``` |
| 56 | + |
| 57 | +4. Ensure the redhat extension for [Language Support for Java™](https://marketplace.visualstudio.com/items?itemName=redhat.java) is installed and enabled. |
| 58 | + |
| 59 | +5. Open examples: |
| 60 | + - Go to File → Open Folder → examples/demo/src/ |
| 61 | + - Or use the terminal: |
| 62 | + ```bash |
| 63 | + code examples/demo/src/ |
| 64 | + ``` |
| 65 | + |
| 66 | +### Troubleshooting |
| 67 | + |
| 68 | +#### VSIX File Issues |
| 69 | + |
| 70 | +If you see "End of central directory record signature not found" or similar errors: |
| 71 | + |
| 72 | +1. This is likely a Git LFS issue. Make sure Git LFS is installed and run: |
| 73 | + ```bash |
| 74 | + git lfs pull |
| 75 | + ``` |
| 76 | + |
| 77 | +2. Verify the VSIX file isn't just a pointer: |
| 78 | + ```bash |
| 79 | + cat ./extension/liquid-java-0.0.15.vsix | head |
| 80 | + ``` |
| 81 | + |
| 82 | + |
| 83 | +## Working with the Extension |
| 84 | + |
| 85 | +1. Ensure your project is correctly set up with the `liquidjava-api.jar`. |
| 86 | +2. When opening a Java file, the extension will automatically verify your LiquidJava annotations. |
| 87 | +3. Errors will be highlighted directly in your code editor. |
| 88 | + |
| 89 | +## Download JARs |
| 90 | + |
| 91 | +`examples/demo/lib` folder contains the api jar that you can use in your projects. |
| 92 | + |
3 | 93 |
|
4 | 94 | ## Examples |
5 | | -### part1-plainJava |
| 95 | +``` |
| 96 | +liquidjava-examples/ |
| 97 | +├── examples/ |
| 98 | +│ ├── demo/ # Simple demo examples |
| 99 | +│ │ ├── src/main/java/com/example # Examples start with "Test*.java" |
| 100 | +├── user_study_23/ # Example projects used for user study of 2023 |
| 101 | +│ ├── part1-plainJava/ # Java projects without LiquidJava |
| 102 | +│ ├── part3-liquidJava/ # Projects with LiquidJava annotations |
| 103 | +│ └── part4/ # Files to be annotated with LiquidJava |
| 104 | +├── extension/ # Contains the VSIX extension file |
| 105 | +... |
| 106 | +``` |
| 107 | +### 2022/23 User Study: |
| 108 | +#### part1-plainJava |
6 | 109 | Contains Java projects without LiquidJava. |
7 | | -Open one of the folders on VSCode and find the error. |
| 110 | +Open one of the folders on VS Code and find the error. |
8 | 111 |
|
9 | | - |
10 | | -### part3-liquidJava |
| 112 | +#### part3-liquidJava |
11 | 113 | Contains LiquidJava projects. |
12 | 114 |
|
13 | | -Open one of the folders on VSCode with the extension running. Uncomment the code in the Test file and find the error. You can open the folder through the terminal by going to the correct path and typing `code` or open through the VSCode GUI. |
14 | | - |
| 115 | +Open one of the folders on VS Code with the extension running. Uncomment the code in the Test file and find the error. You can open the folder through the terminal by going to the correct path and typing `code` or open through the VS Code GUI. |
15 | 116 |
|
16 | | -### part4 |
| 117 | +#### part4 |
17 | 118 | Contains Java files to be annotated with LiquidJava. |
18 | 119 | - **Variable.java** - Add the annotation and check the correct and wrong assignment |
19 | | -- **TrafficLight.java** - Add the annotations on the fields and model the state using `@StateSet` and `@StateRefinement`. To check if the modelling is correct, uncomment the file `TestTLCorrect.java` (that should be correct) and then uncomment the file `TestTLWrong.java` that should present an error. |
20 | | - |
21 | | - |
22 | | -## Install Visual Studio Code Extension |
23 | | -1. Open the terminal on the extension folder |
24 | | -2. `code --install-extension liquid-java-0.0.X.vsix`, where X is the current version of the extension |
25 | | -3. Ensure that VSCode has the redhat extension for [Language support for Java ™](https://marketplace.visualstudio.com/items?itemName=redhat.java) installed and enabled (Java 11 is the minimum required for this extension to run). |
26 | | -4. Open Visual Studio Code and open a Java project (with src folder inside). If the project contains the liquidjava-api.jar then the extension will be activated, otherwise the LiquidJava verification is not applied. |
27 | | -5. The extension may take some time to be activated. While a small wheel in the bottom right of VSCode window is spinning the extension is being loaded. |
| 120 | +- **TrafficLight.java** - Add the annotations on the fields and model the state using `@StateSet` and `@StateRefinement`. To check if the modelling is correct, uncomment the file `TestTLCorrect.java` (that should be correct) and then uncomment the file `TestTLWrong.java` that should present an error. |
| 121 | +## Advanced Development |
28 | 122 |
|
29 | | -## Download jars |
30 | | -`liquidjava-jars` folder contains the api and verifier jars. |
| 123 | +For extension development: |
| 124 | +- Refer to the VS Code Extension API documentation |
| 125 | +- Make changes to your code and test using the provided examples |
| 126 | +- Use the debug console to troubleshoot any issues |
0 commit comments