The library executes a sequence of rules on a physical project (directories and files on disk). The idea is to support continuously upgrade projects to catch up the latest framework. Unlike a one-time upgrade script, rules in Rtran can be implemented in a generic way and able to take configuration. Therefore, for structured project like Maven, a lot of rules can be reused once it's implemented.
Project context: reflects the project to in-memory data (implements com.ebay.rtran.api.IProjectCtx
)
Model: a specific data type that extracted from project context (implements com.ebay.rtran.api.IModel
)
Model provider: the factory that produce a Model instance from project context (implements com.ebay.rtran.api.IModelProvider
)
Rule config: an implementation of com.ebay.rtran.api.IRuleConfig
which usually will be un/marshallable
Rule definition: an implementation of com.ebay.rtran.api.IRule
which may take 0 or 1 rule config parameter
Rule instance: basic unit executed by the engine which is created from rule definition with certain rule config
Rule definitions and model providers can be registered in different modules (JARs) by having a src/resources/META-INF/rtran-meta.conf file.
Here is the example (We use HOCON as the syntax of the .conf file):
// list of IModelProvider implementations
rtran.model-providers = [
com.ebay.rtran.generic.AllFilesModelProvider
com.ebay.rtran.xml.XMLFilesModelProvider
]
// rule definitions keyed by unique rule name
rtran.rules {
"ModifyXMLFilesRule" = {
// implementation of IRule
class = com.ebay.rtran.xml.ModifyXMLFilesRule
// the factory class that create the IRuleConfig instance with certain raw data
// if not specified, the IRuleConfig implementation will be a scala case class and raw data is a JsonNode
config-factory = com.ebay.rtran.xml.ModifyXMLFilesRuleConfigFactory
}
"MoveFilesRule" = {
class = com.ebay.rtran.generic.MoveFilesRule
}
"ModifyFilesRule" = {
class = com.ebay.rtran.generic.ModifyFilesRule
}
}
An external configuration, usually JSON style data can be accepted. Basically it will have a list of object, and each object contains the "name" field that identify the rule definition and optional "config" field that indicate raw configuration of the rule.
Each object in the "ruleConfigs" will be used to create a rule instance and will be executed by the engine sequentially.
For example:
{
"ruleConfigs": [
{
"name": "ModifyFilesRule",
"config": {
"pathPattern": "**/*.java",
"contentMappings": [
{
"regex": "\\.toBlockingObservable\\(\\)",
"replacement": ".toBlocking()"
}
]
}
},
{
"name": "MavenDependenciesMappingRule",
"config": {
"from": [
{
"groupId": "com.netflix.rxjava",
"artifactId": "rxjava-core"
}
],
"to": [
{
"groupId": "io.reactivex",
"artifactId": "rxjava"
}
]
}
}
]
}
The RuleRegistry
will find the rule definition base on the rule name and create a rule instance using the configuration.
Then base on the expected model type of the rule instance, the ModelProviderRegistry
will find the correct model provider and create the model to be executed by the rule
A new model will be created after apply the rule instance to the original model. Then the model provider will save the new model back to disk.
Name | Description |
---|---|
com.ebay.rtran:upgrader-api | the interfaces for the modules to extend |
com.ebay.rtran:upgrader-core | implementation of the rule engine and registry |
com.ebay.rtran:upgrader-generic | provides some generic rules and models (i.e. move and modify files, modify xml files) |
com.ebay.rtran:upgrader-maven | provides rules and models for maven project (i.e. dependency related rules and resolve the POM hierarchy |
- JDK 1.8+
Snapshot: https://oss.sonatype.org/content/repositories/snapshots
Release: https://oss.sonatype.org/service/local/staging/deploy/maven2
Dependency
<dependency>
<groupId>com.ebay.rtran</groupId>
<artifactId>rtran-core</artifactId>
<version>0.8.0-SNAPSHOT</version>
</dependency>
Sample code
val ctx: IProjectCtx = ...
val rules: List[IRule[IModel]] = ...
val ruleEngine = new RuleEngine
ruleEngine.execute(ctx, rules)
<dependency>
<groupId>com.ebay.rtran</groupId>
<artifactId>rtran-maven</artifactId>
<version>0.8.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>com.ebay.rtran</groupId>
<artifactId>rtran-api</artifactId>
<version>0.8.0-SNAPSHOT</version>
</dependency>
- Install Java8 and sbt
- git clone
sbt clean publishLocal
The upgrade tool will generate a nice .md file as a report. The idea here is to decouple the report logic from the rule implementations.
Every rule will generate useful logs which will be used in the report so that they don't need to know about the report.
A customized log appender is used to collect the logs and publish them to the subscribers.
A subscriber is a report segment that filter and parse the logs, then aggregate the information and generate the report part.
Since this implementation is tied with log implementation, now it only supports slf4j-api and logback.
Name | Description |
---|---|
com.ebay.rtran:upgrader-report-api | the interface for customized subscribers |
com.ebay.rtran:upgrader-report | contains the log appender and report api to generate report around a function |