UCov is a proof of concept implementation of syntactic API usage analysis for Java libraries. It enables developers to better design their software library API as well as understand the usage patterns between their software library and their clients. UCov parses and analyzes the source code of Java libraries to produce syntactic usage models (SUM) and the source code of Java clients to produce syntactic usage footprints (SUF) and their coverage. UCov implements a specific API syntactic usage model (SUM) for Java, as follows:
public enum SymbolKind {
SYMBOL_KIND_TYPE,
SYMBOL_KIND_CLASS,
SYMBOL_KIND_INTERFACE,
SYMBOL_KIND_METHOD,
SYMBOL_KIND_CONSTRUCTOR,
SYMBOL_KIND_FIELD
}
public enum SymbolUse {
SYMBOL_USE_INSTANTIATION, // TYPE_USE, CLASS_USE
SYMBOL_USE_TYPE_REFERENCE, // TYPE_USE
SYMBOL_USE_INHERITANCE, // CLASS_USE
SYMBOL_USE_IMPLEMENTATION, // INTERFACE_USE
SYMBOL_USE_EXTENSION, // INTERFACE_USE
SYMBOL_USE_INVOCATION, // METHOD_USE
SYMBOL_USE_STATIC_INVOCATION, // METHOD_USE
SYMBOL_USE_OVERRIDING, // METHOD_USE
SYMBOL_USE_INSTANCE_FIELD_READ, // FIELD_USE
SYMBOL_USE_INSTANCE_FIELD_WRITE, // FIELD_USE,
SYMBOL_USE_VIRTUAL_INVOCATION
}UCov outputs a set of report files:
- The API of the Java library (generated by Roseau) exported as a JSON file:
.API.json - The syntactic usage model (SUM) of the Java library (list of all possible uses permitted by the library) exported as a CSV file
.SUM.csv - The syntactic usage footprint (SUF) of a client using the Java library (list of all uses made by the client out of the API) exported as a CSV file
.SUF.csv
For the SUM and SUF reports, here's a sample SUF result extract from the analysis of the Spark 2.9.3 Library (the SUM report follows the same format):
| projectId | projectType | projectLocation | usagePosition | usageEndPosition | usageFullyQualifiedName | usageKind | usageType |
|---|---|---|---|---|---|---|---|
| Spark-2.9.3 | SAMPLE | I:/UCov/Repro/spark/Samples | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(16:23) | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(79:1) | spark.Route | SYMBOL_KIND_INTERFACE | SYMBOL_USE_IMPLEMENTATION |
| Spark-2.9.3 | SAMPLE | I:/UCov/Repro/spark/Samples | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(16:97) | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(16:101) | spark.Route | SYMBOL_KIND_TYPE | SYMBOL_USE_TYPE_REFERENCE |
| Spark-2.9.3 | SAMPLE | I:/UCov/Repro/spark/Samples | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(28:45) | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(28:51) | spark.Request | SYMBOL_KIND_TYPE | SYMBOL_USE_TYPE_REFERENCE |
| Spark-2.9.3 | SAMPLE | I:/UCov/Repro/spark/Samples | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(29:25) | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(29:49) | spark.Request.headers(java.lang.String) | SYMBOL_KIND_METHOD | SYMBOL_USE_INVOCATION |
| Spark-2.9.3 | SAMPLE | I:/UCov/Repro/spark/Samples | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(55:19) | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(77:5) | spark.Route.handle(spark.Request,spark.Response) | SYMBOL_KIND_METHOD | SYMBOL_USE_OVERRIDING |
| Spark-2.9.3 | SAMPLE | I:/UCov/Repro/spark/Samples | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(55:26) | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(55:32) | spark.Request | SYMBOL_KIND_TYPE | SYMBOL_USE_TYPE_REFERENCE |
| Spark-2.9.3 | SAMPLE | I:/UCov/Repro/spark/Samples | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(55:43) | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(55:50) | spark.Response | SYMBOL_KIND_TYPE | SYMBOL_USE_TYPE_REFERENCE |
| Spark-2.9.3 | SAMPLE | I:/UCov/Repro/spark/Samples | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(60:48) | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(60:61) | spark.Request.body() | SYMBOL_KIND_METHOD | SYMBOL_USE_INVOCATION |
| Spark-2.9.3 | SAMPLE | I:/UCov/Repro/spark/Samples | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(62:45) | /blogservice_sparkexample/src/main/java/me/tomassetti/abstractrequesthandler.java(62:60) | spark.Request.params() | SYMBOL_KIND_METHOD | SYMBOL_USE_INVOCATION |
This repository is licensed under the MIT License.
This repository makes use of a third party dependency named Roseau also made available under the MIT license and whose license is reproduced below:
Roseau License Terms
MIT License
Copyright (c) 2023 Roseau
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.