JBrew Home

• Please note, the master branch is always live! The latest stable release is reflected on master.
• The branch staged-for-release contains the most recent nightly builds and includes the newest features which will be added to the library to be officially released to Maven Central (after the current development iteration). New contributors should make pull requests into staged-for-release.
• To dive into the concurrency library's source code, please navigate here. The README.md contains information on how to get started, and full documentation is available at jbrew.org.
• Feedback is always welcome, and can be submitted to [email protected]. Thank you!

User Installation

Note that contributors or other users who wish to use the latest nightly build should follow the Upstream Installation guide.

GNU/Linux (Red Hat Enterprise, Fedora, CentOS, Ubuntu, Debian, Arch, Clear), FreeBSD (11.2+)

1. Simply download the file "install.sh" above. FreeBSD users should use the file "install-freebsd.sh" instead.
2. At your desired java.library.path, run "install.sh" in the terminal, like so:
   • ./install.sh will install to the current directory, OR
   • ./install.sh /path/to/java.library.path will install to the directory specified.
3. You may be prompted to enter sudo password. Note that no text or cursor movement will appear on screen.
   • [sudo] password for user:  Enter your credentials, then hit [Enter].
4. Your installation is complete! Important: Make sure you set your java.library.path to the location specied in part 2, appended with /bin (Ex: java.library.path=/path/in-part2/bin) before compiling your code, as these libraries have links to native libraries.
   • Essentially, whenever you run the java command, you will need to add -Djava.library.path=path/to/where-you-ran/install.sh/in-step-2/bin (Don't forget to append "/bin" to the end of the location!). More detailed istructions can be found here. Just remember to append "/bin"!
   • For Maven JUnit tests, it is reccomended you add the Apache Surefire plugin and provide the java.library.path as a compiler argument. Use these instructions if you are unsure how to do this.

JBrew Maven Dependencies

The following libraries are synchronixed with Maven Central, and can be inserted into your project's pom.xml as a dependency.

Concurrency Library

  <dependencies>
    <dependency>
      <groupId>org.jbrew</groupId>
      <artifactId>concurrent</artifactId>
      <version>0.1.0-beta.6</version>
    </dependency>
  </dependencies>

CBrew JNI Library (See User Installation Guide before using)

  <dependencies>
    <dependency>
      <groupId>org.jbrew.cbrew</groupId>
      <artifactId>cbrew</artifactId>
      <version>0.1.0-beta.6</version>
    </dependency>
  </dependencies>

CBrew Libary Validators (See User Installation Guide before using)

  <dependencies>
    <dependency>
      <groupId>org.jbrew.cbrew</groupId>
      <artifactId>cbrew-validators</artifactId>
      <version>0.1.0-beta.6</version>
    </dependency>
  </dependencies>

Native Libary Validators (See User Installation Guide before using)

  <dependencies>
    <dependency>
      <groupId>org.jbrew.native</groupId>
      <artifactId>native-validators</artifactId>
      <version>0.1.0-beta.6</version>
    </dependency>
  </dependencies>

Native Library Core (See User Installation Guide before using)

  <dependencies>
    <dependency>
      <groupId>org.jbrew.native</groupId>
      <artifactId>native</artifactId>
      <version>0.1.0-beta.6</version>
    </dependency>
  </dependencies>

JBrew Core Annotations

  <dependencies>
    <dependency>
      <groupId>org.jbrew.core</groupId>
      <artifactId>annotations</artifactId>
      <version>0.1.0-beta.6</version>
    </dependency>
  </dependencies>

JBrew Core

  <dependencies>
    <dependency>
      <groupId>org.jbrew.core</groupId>
      <artifactId>jbrew-core</artifactId>
      <version>0.1.0-beta.6</version>
    </dependency>
  </dependencies>

Upstream Installation

To install the JBrew library locally, simple clone this libary from the branch staged-for-release to get the latest nightly build. Next, run "mvn package" at the project's root directory. If you receive errors, please proceed to follow the installation steps below for your specific operating system.

GNU/Linux

The GNU/Linux is supported as the primary development for JBrew. As such, no additional configuration is needed for most Linux distros. JBrew is actively tested on the following Linux distrubtions:

• RHEL 8.1/8.2, CentOS, Fedora
• RHEL 7.0+
• CentOS
• Fedora
• Ubuntu

FreeBSD 12.1+

As of release v0.1.0-beta.4, FreeBSD is now supported as part of the CBrew and Native libraries! TO configure JBrew for BSD, simply update the java.library.path from $(user.home}/bin/ to ${user.home}/bin/freebsd/. The reason for this configuration is that by default, C executables are packaged for Linux systems. There are slight variances for FreeBSD systems which must be accounted for, and as such a seperate binaries folder was created to house all FreeBSD C libraries for CBrew and Native.

Windows 10+

As of release v0.1.0-beta.3, Windows 10+ is now supported as part of the CBrew and Native libraries! No additional configuration is needed, as windows dynamically linked libraries are packaged as part of the standard release process.

Solaris

At the moment, SolarisOS is not supported by JBrew. If you would like Solaris support, please open an issue detailing your request.

JBrew Java Concurrency Library

The Concurrent Tasks Library is an easy-to-consume Java concurrency library allowing for "Tasks" to execute business logic in a thread safe manner. This library helps users achieve multi-threading in their applications without worrying about synchronization and blocking for race conditions. Presently, there are 2 types of Tasks: Retrievable and Non-Retrievable.
Please note, the below content is relavent only for v0.0.1 - v0.0.4 of the JBrew concurrency library. For v0.0.5 and above, please refer to the official documentation at jbrew.org. README documentation will be updated with the Release Candidate release of v0.1.0-rc.

Retrievable Tasks

Once RetrievableTask is extended, this allows for @ThreadSafe concurrent execution where business logic executed does need to return back an object. As a result, calling the getVal() method for a Retrievable task returns the object of type T (via use of Java generics) - which is blocked until all logic in the execute() method has terminated.

Example usages: Api calls, I/O, or any other situation warranting concurrent parallel processing.

Note that classes extending RetrievableTask.java should explicity specify object type in the class declaration to enable compile-type type checking. See example:

  public class ExampleTask extends RetrievableTask<String>{}

Finally to return the value, one simple has to set the value for obj or this.obj, as such:

  public class ExampleTask extends RetrievableTask<String>{
      @Overide
      protected void execute(){
        //do work, execute business logic
        
        //then set the return value for ExampleTasks's object
        this.obj = "Example task successfully completed";
      }
  }

Non-Retrievable or Basic Tasks

Once NonRetrievableTask or BasicTask has been extended, this allows for simple concurrent execution where the business logic executed does not need to return back an object. As a result, calling the getVal() method for a NonRetrievableTask throws an java.lang.UnsupportedOperationException.

Example usages: initializers, message dispatchers, or any standalone time-consuming task which you would like to execute concurrently.

Client Usage Examples

Regardless on the type of Task needed, each respective Task should be wrapped within with a Thread and will begin execution upon calling of the start() or run() methods. The start() method executes the Task in a new thread, while the run() method executes the Task in the same thread.

Below is an example of a RetrievableTask and NonRetrievable executing business logic in new threads, and then printing out status messages - based on the designated Task type.

  public class Main{
  
    private Task retrievable, nonRetrievable;
    
    public static void main(String[] args){
      retrieveable = new RTask();
      nonRetrievable = new NRTask();
      
      //start the Retrievable Task
      Thread t = new Thread(retrievable);
      t.start();
      //start the Non-Retrievable Task using an anonymous Thread                   
      new Thread(nonRetrievable).start();
      
      //Print the results of each respective Task
      System.out.println(retrievable.getVal()); // Since this is a RetrievableTask, retrievable.getVal()
                                                // is blocked until its execute() method has completed.
    }
    
    private static class RTask extends RetrievableTask<String>{
      @Override
      protected void execute(){
        //do work, execute business logic
        //...    
        this.obj = "Finished with Retrievable task!";
      }
    }
    
    private static class NRTask extends NonRetrievableTask{
      @Override
      protected void execute(){
        //do work, execute business logic
        //...
        System.out.println("Finished with Non-Retrievable task!");
      }
    } 
    
  }

Console:

  Thread #2 started...
  Thread #1 started...
  Finished with Retrievable task!
  Finished with Non-Retrievable task!

CBrew

This library contains native facade implementations of the JBrew utility libraries with the Java Native Interface (JNI). This set of libraries features specific optimizations for Unix-based systems in terms of performance and memory. This is achieved through careful tuning using the C programming language to not only control for garbage collection, but also to ensure maximum performance for elected library features.