fresh commit

Author: michaelzhao820

.clang-format

@@ -0,0 +1,5 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+TabWidth: 4
+UseTab: Never
+ContinuationIndentWidth: 8

.github/workflows/maven.yml

@@ -0,0 +1,54 @@
+# This workflow will build a Java project with Maven, and cache/restore any dependencies to improve the workflow execution time
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-java-with-maven
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Java CI with Maven
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    
+    env:
+      LD_LIBRARY_PATH: ./src/main/c/build
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up JDK 21
+      uses: actions/setup-java@v4
+      with:
+        java-version: '21'
+        distribution: 'temurin'
+        cache: maven
+    
+    - name: Verify JAVA_HOME is set
+      run: echo "JAVA_HOME is set to $JAVA_HOME"
+    
+    - name: Install system dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y cmake clang-format
+    
+    - name: Install Conan
+      run: pip install 'conan==2.24.0'
+    
+    - name: Make build script executable
+      run: chmod +x tasks.sh
+    
+    - name: Check dependencies
+      run: ./tasks.sh check_deps
+    
+    - name: Compile OGO
+      run: ./tasks.sh compile
+      
+    - name: Run tests
+      run: ./tasks.sh tests

.gitignore

@@ -0,0 +1,9 @@
+.venv/
+build/
+surefire-reports/
+target/
+.cache/
+.vscode/
+.ekstazi/
+.idea/
+src/main/c/generated/

README.md

@@ -0,0 +1,168 @@
+## OGO ##
+<img src="images/ogo_logo.png" width="700" />
+
+Object Graph Programming (OGO) enables manipulating the JVM heap
+declaratively through queries. The queries are written using the
+[Cypher Query Language](https://neo4j.com/developer/cypher/). OGO
+supports two high-level modes, $OGO^{Neo}$ and $OGO^{Mem}$. The former
+serializes a sub-graph of the entire JVM heap object graph, loads it
+into a standalone Neo4J database and executes queries inside it. The
+latter executes queries in-memory (inside the native agent) using
+[Antlr](https://www.antlr.org/) to parse the query and visitors to
+execute it Currently, $OGO^{Mem}$ is under construction and not all
+functionalities may work.
+
+## Examples ##
+
+1. Searching an `ArrayList` for a given element.
+   ```java
+   ArrayList<Long> lst = new ArrayList<Long>();
+   lst.add(10L);
+   lst.add(20L);
+   lst.add(30L);
+   query("MATCH ({$1})-[:elementData]->()-[]->({value : 20}) RETURN TRUE");
+   ```
+   In this example, we use imperative code to instantiate and add elements to
+   an `ArrayList` and then use `Cypher` query through `OGO` to query `lst` to
+   check if it contains element 20.
+
+2. Implementing the `containsKey` method of `java.util.HashMap` class.
+   ```java
+   public boolean containsKeyOgoImpl(HashMap map, object key){
+      queryBool("MATCH ({$1})-[:table]->()-[]->()-[:key]->(n)"
+               +"MATCH (m {$2})"
+               +"WHERE n.`equals`(m)"
+               +"RETURN COUNT(n) <> 0", map, key);
+   }
+   ```
+   In this example, the first `MATCH` clause matches a pattern that collects
+   all the objects corresponding to the `key` field of `HashMap's` inner class
+   `Node` into the variable `n`. The second `MATCH` clause collects the given key
+   object into the variable `m`. The `WHERE` clause filters the elements of `n`
+   based on the output of the `java.lang.Object` class's `equals` method evaluating to
+   true for pairwise inputs from `n` and `m`. This predicate is expected to filter number of
+   elements of `n` to 1 if the given key is present in the `map` and to 0 if absent.
+   Finally, we use the `RETURN` clause to return the value of the expression that
+   compares equality of number of elements of `n` to 0. The query is hence expected to
+   return true iff the number of elements in `n` is non-zero which is true only if the
+   given key is contained in `map`.
+
+
+## Getting Started ##
+
+### Prerequisites
+The project requires the following dependencies:
+- **Maven** 
+- **Java 21** 
+- **Conan 2.24.0** 
+- **CMake** 
+- **Clang Format** 
+
+### Installation
+
+#### 1. Install Dependencies
+Run the installation script to automatically install all required dependencies:
+
+```bash
+./tasks.sh install_deps
+```
+
+This will check for and install any missing dependencies on your system.
+
+Alternatively, verify your dependencies are correctly installed:
+```bash
+./tasks.sh check_deps
+```
+
+#### 2. Build the Project
+Compile the OGO project:
+
+```bash
+./tasks.sh compile
+```
+
+#### 3. Full Installation
+To compile and install the complete project:
+
+```bash
+./tasks.sh install
+```
+
+### Running the Project
+
+#### Run Tests
+Execute the test suite:
+
+```bash
+./tasks.sh tests
+```
+
+#### Run the Application
+Test out the OGO application by running it against Main.java
+
+```bash
+./tasks.sh exec
+```
+
+#### Format Code
+Auto-format Java and C++ code according to project standards:
+
+```bash
+./tasks.sh format
+```
+
+#### End-to-End Setup
+Perform a complete setup with dependency checks and full installation:
+
+```bash
+./tasks.sh end_to_end
+```
+
+## Using OGO in a Maven Project
+
+After packaging, OGO can be used in any maven project.
+
+1. ### Include Client dependency:
+    
+	The client jar can be added as a dependency to a third-party project by adding the following to its pom.
+	```xml
+	<dependency>
+	  <groupId>org.ogo</groupId>
+      <artifactId>ogo</artifactId>
+      <version>0.1.0</version>
+      <scope>system</scope>
+      <systemPath><!-- ENTER full path to client jar including jar name --></systemPath>
+    </dependency>
+	```
+
+2. ### Include Native Agent:
+
+    The native agent can be included during execution by adding the following to the third-party pom.
+	```xml
+    <configuration>
+      <!-- for adding native agent ogoAgent -->
+	  <argLine>-agentpath:<!-- ENTER full path to native agent including native agent name --></argLine>
+    </configuration>
+	```
+    Some third-party project tend to use other plugins which may overwrite `argLine`. It may be necessary
+	to explicitly specify this argument while running the tests using maven. This can be done using:
+	```bash
+	mvn test -DargLine="-agentpath:<ENTER full path to native agent including native agent name>"
+	```
+    
+## Citation ##
+If you use OGO in your research, please cite the following paper:
+
+```bibtex
+@inproceedings{ThimmaiahETAL24OGO,
+  author    = {Thimmaiah, Aditya and Lampropoulos, Leonidas and Rossbach, Christopher and Gligoric, Milos},
+  title     = {Object Graph Programming},
+  year      = {2024},
+  doi       = {10.1145/3597503.3623319},
+  booktitle = {International Conference on Software Engineering},
+  pages     = {1--13},
+}
+```
+
+The paper can be found
+[here](https://users.ece.utexas.edu/~gligoric/papers/ThimmaiahETAL24OGO.pdf).

descriptor-client.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0"?>
+<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.1.1 http://maven.apache.org/xsd/assembly-2.1.1.xsd">
+  <id>client</id>
+  <formats>
+    <format>jar</format>
+  </formats>
+  <includeBaseDirectory>false</includeBaseDirectory>
+  <fileSets>
+    <fileSet>
+      <directory>${basedir}/target/classes</directory>
+      <includes>
+        <include>ogo.properties</include>
+        <include>org/ogo/client/*.class</include>
+        <include>org/ogo/util/*.class</include>
+        <include>org/ogo/bridge/*.class</include>
+	<include>org/ogo/*.class</include>
+      </includes>
+      <outputDirectory>/</outputDirectory>
+    </fileSet>
+  </fileSets>
+</assembly>

examples/ArrayListExamples.java

@@ -0,0 +1,65 @@
+import org.ogo.client.OGO;
+import java.util.ArrayList;
+
+import static org.ogo.client.OGO.queryBool;
+import static org.ogo.client.OGO.queryInt;
+ 
+/**
+ * Example class to demonstrate the usage of OGO
+ * for querying ArrayLists.
+ */
+public class ArrayListExamples{
+
+    /**
+     * @brief Example that demonstrates using OGO to query an
+     * ArrayList to search for a given element.
+     * @returns true/false
+     */
+    public boolean containsMethodExample() throws Exception{
+        // Create an ArrayList instance and insert elements into it
+        // using imperative style.
+        ArrayList<Long> lst = new ArrayList<Long>();
+        lst.add(10L);
+        lst.add(20L);
+        lst.add(30L);
+
+        // Query the ArrayList instance to check if it contains the
+        // element 20L and return True if it does and false if it doesn't.
+        return queryBool("MATCH ({$1})-[:elementData]->()-[]->({value:20}) RETURN TRUE", lst);
+    }
+    
+    /**
+     * @brief Example that demonstrates using OGO to query an
+     * ArrayList to find its size.
+     * @returns size of the ArrayList
+     */
+    public int arrayListSizeExample() throws Exception{
+        // Create an ArrayList instance and insert elements into it
+        // using imperative style.
+        ArrayList<Long> lst = new ArrayList<Long>();
+        lst.add(10L);
+        lst.add(20L);
+        lst.add(30L);
+
+        // Query the ArrayList instance to find its size.
+        return queryInt("MATCH ({$1})-[:elementData]->()-[]->(n) RETURN COUNT(n)", lst);
+    }
+    
+    /**
+     * @brief Example that demonstrates using OGO to query an
+     * ArrayList to retrieve an element at a given index.
+     * @returns element at index 1
+     */
+    public long arrayGetElementAtExample() throws Exception{
+        // Create an ArrayList instance and insert elements into it
+        // using imperative style.
+        ArrayList<Long> lst = new ArrayList<Long>();
+        lst.add(10L);
+        lst.add(20L);
+        lst.add(30L);
+
+        // Query the ArrayList instance to retrieve the element at
+        // index 1.
+        return queryLong("MATCH ({$1})-[:elementData]->()-[:`1`]->(n) RETURN n", lst);
+    }
+}