Skip to content

Commit

Permalink
Merge pull request #20 from Electrostat-Lab/scaling-plan
Browse files Browse the repository at this point in the history
Scaling-plan: A scaling plan applied to scale the API for professional use-cases
  • Loading branch information
pavly-gerges authored Jul 26, 2024
2 parents f1275f1 + a7c2a48 commit e7a839c
Show file tree
Hide file tree
Showing 43 changed files with 1,602 additions and 612 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/build-deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ jobs:
deploy:
environment:
name: maven-central
url: https://repo.maven.apache.org/maven2/io/github/software-hardware-codesign/
url: https://repo.maven.apache.org/maven2/io/github/electrostat-lab
runs-on: ${{ matrix.os }}
needs: [compile-assemble]
strategy:
Expand Down
19 changes: 9 additions & 10 deletions .github/workflows/build-test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,18 +16,15 @@ on:
jobs:
build-snaploader:
# runner images with architectures (variants)
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ 'ubuntu-latest' ]
runs-on: 'ubuntu-latest'
name: Build jSnapLoader

# Steps represent a sequence of tasks that will be executed as part of the job
steps:
- name: Checkout Job
uses: actions/checkout@v3

- name: Setup Temurin-JDK-19
- name: Setup temurin JDK
uses: actions/setup-java@v3
with:
distribution: 'temurin'
Expand Down Expand Up @@ -55,7 +52,7 @@ jobs:
- name: Checkout Job
uses: actions/checkout@v3

- name: Setup Oracle-JDK-19
- name: Setup temurin JDK
uses: actions/setup-java@v3
with:
distribution: 'temurin'
Expand All @@ -68,21 +65,23 @@ jobs:
# runner images with architectures (variants)
runs-on: ${{ matrix.os }}
needs: build-snaploader
name: Testing snaploader on ${{ matrix.os }}-${{ matrix.jdk }}
strategy:
matrix:
os: [ 'ubuntu-latest', 'macos-latest', 'windows-latest' ]
name: Testing snaploader on ${{ matrix.os }} for x86-64
os: [ 'ubuntu-latest', 'windows-latest' ]
jdk: ['17', '19']
architecture: ['x86_64']

# Steps represent a sequence of tasks that will be executed as part of the job
steps:
- name: Checkout Job
uses: actions/checkout@v3

- name: Setup Temurin-JDK-19
- name: Setup temurin JDK
uses: actions/setup-java@v3
with:
distribution: 'temurin'
java-version: '19'
java-version: ${{ matrix.jdk }}

- name: Download snaploader-SNAPSHOT.jar library
uses: actions/download-artifact@v3
Expand Down
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
BSD 3-Clause License

Copyright (c) 2023, AvrSandbox, jSnapLoader
Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
Expand Down
32 changes: 27 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,22 @@
# <img src="https://github.com/Software-Hardware-Codesign/jSnapLoader/assets/60224159/85ac90d0-7d10-4d7c-a57e-390246ac5dee" width=60 height=60/> jSnapLoader [![Codacy Badge](https://app.codacy.com/project/badge/Grade/50261f7cc09b4b9bacaf9f44ecc28ea9)](https://app.codacy.com/gh/Software-Hardware-Codesign/jSnapLoader/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [![](https://img.shields.io/badge/jSnapLoader-latest_version-red)](https://github.com/Software-Hardware-Codesign/jSnapLoader/releases)
[![](https://github.com/Software-Hardware-Codesign/jSnapLoader/actions/workflows/build-test.yml/badge.svg)]() [![](https://github.com/Software-Hardware-Codesign/jSnapLoader/actions/workflows/build-deploy.yml/badge.svg)]()

A high-performance cross-platform dynamic library loader API for JVM Applications.
A high-performance cross-platform dynamic library loader API for JVM Applications,
with highly modifiable system-specific registration using platform predicates.

## Software Specification:

| Item | Description | Predicate Calculus |
|---------------------------------|-------------|--------------------|
| _Problem Definition_ | | |
| _Generalized Approach_ | | |
| _jSnapLoader-specific Approach_ | | |
| _Framework Decomposition_ | | |
| _Framework Enhancements_ | | |
| _Credits for other systems_ | | |

## Software Architectural Paradigm:
<img src="https://github.com/Electrostat-Lab/jSnapLoader/architecture/architectural-paradigm.png" alt="Architectural-Paradigm-Placement"/>

## Quick Building and running examples:
```bash
Expand Down Expand Up @@ -30,17 +45,24 @@ BUILD SUCCESSFUL in 1s
4 actionable tasks: 2 executed, 2 up-to-date
```

## Appendix
Features:
## Plug-and-play usage:


## Appendix:
### Features:
- [x] Platform-specific dynamic libraries' registration.
- [x] Platform-specific dynamic libraries building using platform-specific predicates (NEW).
- [x] Locate and load external dynamic libraries directly.
- [x] Extract native libraries from the stock jar library (classpath).
- [x] Locate external jars and extract native libraries from them.
- [x] Define an extract directory.
- [x] Retry Criterion with clean extraction (NEW).
- [x] Exposed the platform-dependent library `NativeDynamicLibrary` (NEW).
- [x] Exposed the `NativeVariant` providing system properties.
- [x] EventDispatchers: Extraction Listeners, Loading Listeners, and System Detection Listeners.
- [ ] Extract automatically based on the application name and version.

Documentation-list:
- [ ] Architecture paradigm.
### Documentation-list:
- [x] Architecture paradigm.
- [x] API documentation.
- [ ] Java-Doc page.
Binary file added architecture/architectural-paradigm.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
104 changes: 104 additions & 0 deletions architecture/architectural-paradigm.puml
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
@startuml
'https://plantuml.com/component-diagram

'Structural composition
package platform {
package util {
component NativeVariant #22AADD {
component [Os] {
}
component [Cpu] {
}
}
component PropertiesProvider {
}
component PlatformPredicate {
}
}
component NativeDynamicLibrary <<platform-dependent>> {
}
note top of [NativeDynamicLibrary]: // PlatformDirectory
note top of [NativeDynamicLibrary]: // Predicate
note top of [NativeDynamicLibrary]: // LibraryInfo
}

node List<NativeDynamicLibrary> <<Object>> {
}

package snaploader {
component LoadingCriterion <<Object>> {
}
interface LoadingListeners {
}
component LibraryInfo <<platform-independent>> {
}

object NativeBinaryLoader {
// Platform Detection
// NativeVariant Object Instantiation
// LibraryLocator
// LibraryExtractor
}
}

package filesystem {
component FileExtractor {
}

component FileLocator {
}

object LibraryExtractor {
// from StockJar
// from ExternalJar
}

object LibraryLocator {
// StockJar
// ExternalJar
}

component ZipCompressionType {
}

interface StreamProvider {
}

interface ExtractionListener {
}

component InputStreamProvider {
}

component OutputStreamProvider {
}
}

'Relations
NativeDynamicLibrary ..-> NativeVariant : Depends-on
NativeDynamicLibrary ..-> PropertiesProvider : Depends-on
NativeDynamicLibrary ..-> PlatformPredicate : Depends-on
NativeDynamicLibrary ...> LibraryInfo : Depends-on


StreamProvider <-. InputStreamProvider : Realized-from
StreamProvider <-. OutputStreamProvider : Realized-from

FileExtractor <-. LibraryExtractor : Realized-from
FileExtractor -(0- ExtractionListener : Assembled-by
FileLocator <-. LibraryLocator : Realized-from
ZipCompressionType <-. FileLocator : Depends-on
LibraryLocator <.. LibraryExtractor : Depends-on

NativeBinaryLoader --(0-- LibraryExtractor : Assembled-by
NativeBinaryLoader --(0-- LoadingListeners : Assembled-by
NativeBinaryLoader --(0-- "List<NativeDynamicLibrary>" : Assembled-by
NativeBinaryLoader --(0-- LibraryInfo : Indirect-assembly
NativeBinaryLoader --(0-- LoadingCriterion : Assembled-by

'Notes
note top of "List<NativeDynamicLibrary>": // List of libraries to check against their predicates
note top of "LibraryInfo": // Provides the Jar path for the locator, and the library extraction path


@enduml
16 changes: 8 additions & 8 deletions helper-scripts/abstract/abstract-sonatype-publish.sh
Original file line number Diff line number Diff line change
Expand Up @@ -14,25 +14,25 @@ function generateGenericPom() {
<name>jSnapLoader API</name> \
<packaging>jar</packaging> \
<description>A high-performance cross-platform dynamic library loader API for JVM Applications with file locator and file extractor interfaces.</description> \
<url>https://github.com/Software-Hardware-Codesign/jSnapLoader</url> \
<url>https://github.com/Electrostat-Lab/jSnapLoader</url> \
<licenses> \
<license> \
<name>The AvrSandbox Project, jSnapLoader BSD-3 Clause License</name> \
<url>https://github.com/Software-Hardware-Codesign/jSnapLoader/blob/master/LICENSE</url> \
<name>The Electrostatic-Sandbox Distributed Simulation Project, jSnapLoader BSD-3 Clause License</name> \
<url>https://github.com/Electrostat-Lab/jSnapLoader/blob/master/LICENSE</url> \
</license> \
</licenses> \
<developers> \
<developer> \
<name>Pavly Gerges aka. pavl_g</name> \
<email>pepogerges33@gmail.com</email> \
<organization>AvrSandbox Project</organization> \
<organizationUrl>https://github.com/Software-Hardware-Codesign</organizationUrl> \
<organization>Electrostat-Lab</organization> \
<organizationUrl>https://github.com/Electrostat-Lab</organizationUrl> \
</developer> \
</developers> \
<scm> \
<connection>scm:git://github.com/Software-Hardware-Codesign/jSnapLoader.git</connection> \
<developerConnection>scm:git:ssh://github.com/Software-Hardware-Codesign/jSnapLoader.git</developerConnection> \
<url>https://github.com/Software-Hardware-Codesign/jSnapLoader/tree/master</url> \
<connection>scm:git://github.com/Electrostat-Lab/jSnapLoader.git</connection> \
<developerConnection>scm:git:ssh://github.com/Electrostat-Lab/jSnapLoader.git</developerConnection> \
<url>https://github.com/Electrostat-Lab/jSnapLoader/tree/master</url> \
</scm> \
</project> \
"
Expand Down
2 changes: 1 addition & 1 deletion helper-scripts/project-impl/variables.sh
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
# ---------------------
sonatype_url="https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/"
repository="ossrh"
groupId="io.github.software-hardware-codesign"
groupId="io.github.electrostat-lab"
maven_version="3.9.4"
maven_bin="./apache-maven-$maven_version/bin/mvn"
desktop_pomFile="./helper-scripts/project-impl/publishing/snaploader.pom"
Expand Down
10 changes: 5 additions & 5 deletions snaploader-examples/build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,23 @@ plugins {
}

application {
mainClass = 'com.avrsandbox.snaploader.examples.TestBasicFeatures'
mainClass = 'electrostatic.snaploader.examples.TestBasicFeatures'
}

tasks.register("TestBasicFeatures") {
application.mainClass = 'com.avrsandbox.snaploader.examples.TestBasicFeatures'
application.mainClass = 'electrostatic.snaploader.examples.TestBasicFeatures'
}

tasks.register("TestMultipleLoads") {
application.mainClass = 'com.avrsandbox.snaploader.examples.TestMultipleLoads'
application.mainClass = 'electrostatic.snaploader.examples.TestMultipleLoads'
}

tasks.register("TestZipExtractor") {
application.mainClass = 'com.avrsandbox.snaploader.examples.TestZipExtractor'
application.mainClass = 'electrostatic.snaploader.examples.TestZipExtractor'
}

tasks.register("TestMultiThreading") {
application.mainClass = 'com.avrsandbox.snaploader.examples.TestMultiThreading'
application.mainClass = 'electrostatic.snaploader.examples.TestMultiThreading'
}

dependencies {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2023, AvrSandbox, jSnapLoader
* Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
Expand Down Expand Up @@ -29,14 +29,19 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
package com.avrsandbox.snaploader.examples;

package electrostatic.snaploader.examples;

import java.io.IOException;
import com.avrsandbox.snaploader.LibraryInfo;
import com.avrsandbox.snaploader.NativeBinaryLoader;
import com.avrsandbox.snaploader.platform.NativeVariant;
import com.avrsandbox.snaploader.platform.PropertiesProvider;
import com.avrsandbox.snaploader.LoadingCriterion;

import electrostatic.snaploader.LibraryInfo;
import electrostatic.snaploader.NativeBinaryLoader;
import electrostatic.snaploader.platform.util.DefaultDynamicLibraries;
import electrostatic.snaploader.platform.NativeDynamicLibrary;
import electrostatic.snaploader.platform.util.NativeVariant;
import electrostatic.snaploader.platform.util.PlatformPredicate;
import electrostatic.snaploader.platform.util.PropertiesProvider;
import electrostatic.snaploader.LoadingCriterion;

/**
* Tests basic features of the {@link NativeBinaryLoader} API.
Expand All @@ -45,17 +50,27 @@
*/
public final class TestBasicFeatures {

protected static final LibraryInfo libraryInfo = new LibraryInfo(getJarFilePath(),
null,
protected static final LibraryInfo libraryInfo = new LibraryInfo(getJarFilePath(),
"lib/placeholder",
getLibraryBaseName(),
getLibrariesAbsolutePath());

protected static NativeBinaryLoader loader;

public static final NativeDynamicLibrary[] libraries = new NativeDynamicLibrary[] {
DefaultDynamicLibraries.LINUX_X86,
DefaultDynamicLibraries.LINUX_X86_64,
new NativeDynamicLibrary("lib/windows/x86", "libjmealloc.dll", PlatformPredicate.WIN_X86),
new NativeDynamicLibrary("lib/windows/x86-64", "libjmealloc.dll", PlatformPredicate.WIN_X86_64),
DefaultDynamicLibraries.MAC_X86,
DefaultDynamicLibraries.MAC_X86_64,
};

public static void main(String[] args) throws IOException {
if (loader == null) {
loader = new NativeBinaryLoader(libraryInfo).initPlatformLibrary();
loader = new NativeBinaryLoader(libraryInfo);
}
loader.registerNativeLibraries(libraries).initPlatformLibrary();
loader.setLoggingEnabled(true);
loader.setRetryWithCleanExtraction(true);
/* Native dynamic library properties */
Expand All @@ -65,12 +80,12 @@ public static void main(String[] args) throws IOException {

protected static void printDetails(NativeBinaryLoader loader) {
System.out.println("--------------------------------------------------------------");
System.out.println("OS: " + NativeVariant.NAME.getProperty());
System.out.println("ARCH: " + NativeVariant.ARCH.getProperty());
System.out.println("VM: " + NativeVariant.VM.getProperty());
System.out.println("OS: " + NativeVariant.OS_NAME.getProperty());
System.out.println("ARCH: " + NativeVariant.OS_ARCH.getProperty());
System.out.println("VM: " + NativeVariant.JVM.getProperty());
System.out.println("--------------------------------------------------------------");
System.out.println("Jar Path: " + loader.getNativeDynamicLibrary().getJarPath());
System.out.println("Library Directory: " + loader.getNativeDynamicLibrary().getLibraryDirectory());
System.out.println("Library Directory: " + loader.getNativeDynamicLibrary().getPlatformDirectory());
System.out.println("Compressed library path: " + loader.getNativeDynamicLibrary().getCompressedLibrary());
System.out.println("Extracted library absolute path: " + loader.getNativeDynamicLibrary().getExtractedLibrary());
System.out.println("Is Extracted: " + loader.getNativeDynamicLibrary().isExtracted());
Expand Down
Loading

0 comments on commit e7a839c

Please sign in to comment.