schaapi
Early detection of breaking changes based on API usage
Schaapi ensures Safe Changes for APIs of libraries. It focuses on detection of semantic breaking changes, but provides a general-purpose pipeline that is also applicable to the detection of other types of breaking changes. The default implementation detects incompatibilities between Java libraries and Java projects using that library.
Schaapi requires JRE 8 and has been tested on Windows and Unix systems.
Usage
Run the JAR as java -jar schaapi.jar <flavor> <args> or run a local build with gradlew :application:run --args='<flavor> <args>'.
Set the system property log.level to debug to enable debug output in the log file.
Pipeline Flavor
Schaapi allows you to mine projects from different sources, such as GitHub. In particular, it recognizes two such pipeline "flavors": directory (locally sourced projects) and github (projects mined from GitHub). Each of these have their own behavior and options. Click on one of the flavors below for a list of command-line options.
Directory flavor options
usage: schaapi -o <arg> [--delete_old_output] -l <arg>
[--skip_user_compile] [--maven_dir <arg>] [--repair_maven] -u <arg>
[--library_type <arg>] [--user_compile_timeout <arg>]
[--pattern_detector_minimum_count <arg>]
[--pattern_detector_maximum_sequence_length <arg>]
[--pattern_minimum_library_usage_count <arg>]
[--test_generator_parallel] [--test_generator_disable_output]
[--test_generator_timeout <arg>]
-o,--output_dir <arg> The output
directory.
--delete_old_output Deletes the output
directory before
running the
pipeline.
-l,--library_dir <arg> The library
directory.
--skip_user_compile Skip compilation of
user projects.
--maven_dir <arg> The directory to
run Maven from.
--repair_maven Repairs the Maven
installation.
-u,--user_base_dir <arg> The directory
containing user
project
directories.
--library_type <arg> The type of
library.
[javamaven,
javajar]
--user_compile_timeout <arg> The maximum number
of seconds the
compilation of a
user project may
take. Set to 0 to
disable the
timeout.
--pattern_detector_minimum_count <arg> The minimum number
of occurrences for
a statement to be
considered
frequent.
--pattern_detector_maximum_sequence_length <arg> The maximum length
of sequences to be
considered for
pattern detection.
--pattern_minimum_library_usage_count <arg> The minimum number
of library usages
per method.
--test_generator_parallel True if test
generator should
run in parallel.
Requires that test
generator output is
disabled.
--test_generator_disable_output True if test
generator output
should be hidden.
--test_generator_timeout <arg> The time limit per
pattern for the
test generator.
GitHub flavor options
usage: schaapi -o <arg> [--delete_old_output] -l <arg> [--maven_dir <arg>]
[--repair_maven] --github_oauth_token <arg> [--max_projects <arg>]
--library_group_id <arg> --library_artifact_id <arg>
--library_version <arg> [--sort_by_stargazers] [--sort_by_watchers]
[--version_verification_timeout <arg>] [--library_type <arg>]
[--user_compile_timeout <arg>]
[--pattern_minimum_library_usage_count <arg>]
[--pattern_detector_minimum_count <arg>]
[--pattern_detector_maximum_sequence_length <arg>]
[--test_generator_parallel] [--test_generator_disable_output]
[--test_generator_timeout <arg>]
-o,--output_dir <arg> The output
directory.
--delete_old_output Deletes the output
directory before
running the
pipeline.
-l,--library_dir <arg> The library
directory.
--maven_dir <arg> The directory to
run Maven from.
--repair_maven Repairs the Maven
installation.
--github_oauth_token <arg> Token of GitHub
account used for
searching.
--max_projects <arg> Maximum amount of
projects to
download from
GitHub.
--library_group_id <arg> Group id of library
mined projects
should have a
dependency on.
--library_artifact_id <arg> Artifact id of
library mined
projects should
have a dependency
on.
--library_version <arg> Version of library
mined projects
should have a
dependency on.
--sort_by_stargazers True if GitHub
projects should be
sorted by stars.
--sort_by_watchers True if GitHub
projects should be
sorted by watchers.
--version_verification_timeout <arg> The maximum number
of seconds the
verification that a
project uses the
library may take.
Set to 0 to disable
the timeout.
--library_type <arg> The type of
library.
[javamaven,
javajar]
--user_compile_timeout <arg> The maximum number
of seconds the
compilation of a
user project may
take. Set to 0 to
disable the
timeout.
--pattern_minimum_library_usage_count <arg> The minimum number
of library usages
per method.
--pattern_detector_minimum_count <arg> The minimum number
of occurrences for
a statement to be
considered
frequent.
--pattern_detector_maximum_sequence_length <arg> The maximum length
of sequences to be
considered for
pattern detection.
--test_generator_parallel True if test
generator should
run in parallel.
Requires that test
generator output is
disabled.
--test_generator_disable_output True if test
generator output
should be hidden.
--test_generator_timeout <arg> The time limit per
pattern for the
test generator.
Library Type
Schaapi can work with different library formats. This "library type" can be one of the following: javajar (a library JAR is provided) or javamaven (the Java Maven project of that library is provided).
Pipeline Stages
1 Mining Pipeline
| Stage | Description |
|---|---|
| 1.1 Mine Projects | Mine version control or library distribution platforms for projects using your software version |
| 1.2 Compile Projects | Compile user projects |
| 1.3 Analyse Usage per Project | Create library usage graphs of user projects |
| 1.4 Find Usage Patterns across all Projects | Find common library usage patterns across usage graphs |
| 1.5 Filter Found Patterns | Filter relevant library usage patterns |
| 1.6 Generate Tests | Generate regression tests for library usage patterns |
1.1 Mine Projects
| Description | Mine version control or library distribution platforms for projects using your software version |
| Interface | org.cafejojo.schaapi.miningpipeline.ProjectMiner |
| Implementations | GitHub Project Miner Mines projects from GitHub using its code search API. Directory Project Miner 'Mines' projects from the file system, finding all projects in one folder. |
1.2 Compile Projects
| Description | Compile user projects |
| Interface | org.cafejojo.schaapi.miningpipeline.ProjectCompiler |
| Implementations | Java Maven Project Compiler Compiles Java Maven projects, by fetching their dependencies and compiling the source code. Java JAR Project Compiler Compiles Java JAR projects, by inspecting the classes contained in the JAR. |
1.3 Analyse Usage per Project
| Description | Create library usage graphs of user projects |
| Interface | org.cafejojo.schaapi.miningpipeline.LibraryUsageGraphGenerator |
| Implementations | Jimple Library Usage Graph Generator Generates library usage graphs for Java using Soot Jimple control flow graphs. |
1.4 Find Usage Patterns across all Projects
| Description | Find common library usage patterns across usage graphs |
| Interface | org.cafejojo.schaapi.miningpipeline.PatternDetector |
| Implementations | PrefixSpan Pattern Detector Identifies frequent sequential patterns in graphs, using the PrefixSpan algorithm. SPAM Pattern Detector Identifies frequent sequential patterns in graphs, using the SPAM algorithm. CCSpan Pattern Detector Identifies frequent sequential patterns in graphs, using the CCSpan algorithm. |
1.5 Filter Found Patterns
| Description | Filter relevant library usage patterns |
| Interface | org.cafejojo.schaapi.miningpipeline.PatternFilterRule |
| Implementations | Jimple Pattern Filters Collection of filters that work with Soot Jimple based library usage graphs. |
1.6 Generate Tests
| Description | Generate regression tests for library usage patterns |
| Interface | org.cafejojo.schaapi.miningpipeline.TestGenerator |
| Implementations | Jimple EvoSuite Test Generator Generates testable classes based on Soot Jimple based patterns, and generates tests for those using EvoSuite. |
2 Validation Pipeline
| Stage | Description |
|---|---|
| 2.1 Execute Tests | Run generated tests against a new library version |
| 2.2 Notify Developers | Notify library developer of possibly affected users |
2.1 Execute Tests
| Description | Run generated tests against a new library version |
| Interface | org.cafejojo.schaapi.validationpipeline.TestRunner |
| Implementations | JUnit Test Runner Executes a JUnit test suite and reports on the results |
2.2 Notify Developers
| Description | Notify library developer of possibly affected users |
| Interface | -- |
| Implementations |
Changelog
Please see releases for more information on what has changed recently.
Testing
$ ./gradlew check
Documentation
$ ./gradlew dokka
Contributing
Please see CONTRIBUTING for details.
Security
If you discover any security-related issues, please email security@cafejojo.org instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see the license file for more information.
