{"id":22873005,"url":"https://github.com/eclipse-transformer/transformer","last_synced_at":"2025-04-04T12:09:16.883Z","repository":{"id":37095441,"uuid":"267118495","full_name":"eclipse-transformer/transformer","owner":"eclipse-transformer","description":"Eclipse Transformer provides tools and runtime components that transform Java binaries, such as individual class files and complete JARs and WARs, mapping changes to Java packages, type names, and related resource names.","archived":false,"fork":false,"pushed_at":"2025-01-06T00:28:55.000Z","size":2297,"stargazers_count":122,"open_issues_count":8,"forks_count":59,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-01-06T05:47:56.915Z","etag":null,"topics":["eclipse-transformer","jakarta","java","renaming-rules"],"latest_commit_sha":null,"homepage":"https://projects.eclipse.org/projects/technology.transformer","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eclipse-transformer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-26T18:17:05.000Z","updated_at":"2025-01-02T12:11:04.000Z","dependencies_parsed_at":"2023-02-10T19:01:41.381Z","dependency_job_id":"b6bffee8-97cb-456d-bb08-987951e50f71","html_url":"https://github.com/eclipse-transformer/transformer","commit_stats":{"total_commits":396,"total_committers":13,"mean_commits":30.46153846153846,"dds":0.3964646464646465,"last_synced_commit":"b59c8113cb9f8fa8027da1824906e7de4e68a6a8"},"previous_names":["eclipse-transformer/transformer","eclipse/transformer"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-transformer%2Ftransformer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-transformer%2Ftransformer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-transformer%2Ftransformer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-transformer%2Ftransformer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eclipse-transformer","download_url":"https://codeload.github.com/eclipse-transformer/transformer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247174453,"owners_count":20896078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eclipse-transformer","jakarta","java","renaming-rules"],"created_at":"2024-12-13T14:03:54.895Z","updated_at":"2025-04-04T12:09:16.866Z","avatar_url":"https://github.com/eclipse-transformer.png","language":"Java","readme":"# Eclipse Transformer\n\nThe [Eclipse Transformer project](https://projects.eclipse.org/projects/technology.transformer) is part of the [Eclipse Technology top-level project](https://projects.eclipse.org/projects/technology).\n\nEclipse Transformer provides tools and runtime components that transform Java binaries, such as individual class files and complete JARs and WARs, mapping changes to Java packages, type names, and related resource names.\n\nWhile the initial impetus for the project was the Jakarta EE package renaming issue, the scope of the project is broader to support other renaming scenarios. For example, shading.\n\nWe operate under the [Eclipse Code of Conduct](https://eclipse.org/org/documents/Community_Code_of_Conduct.php) to promote fairness, openness, and inclusion.\n\n## Build Status\n\n[![CI Build](https://github.com/eclipse-transformer/transformer/actions/workflows/cibuild.yml/badge.svg)](https://github.com/eclipse-transformer/transformer/actions/workflows/cibuild.yml)\n\n## Latest release\n\n[![Maven Central](https://img.shields.io/maven-central/v/org.eclipse.transformer/org.eclipse.transformer.parent.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22org.eclipse.transformer%22)\n\n## Project licence\n\n[![License](https://img.shields.io/badge/License-EPL%202.0-green.svg)](https://opensource.org/licenses/EPL-2.0)\n[![License](https://img.shields.io/badge/License-APL%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)\n\nAll Eclipse Transformer project materials are made available under the Eclipse Public\nLicense 2.0 or the Apache 2.0 license. You can choose which license you wish\nto follow.  Please see our [LICENSE](LICENSE) file for more details.\n\n## Summary\n\nThe Eclipse Transformer is a generic framework for transforming resources (files and archive) based on updates specified by property files.\n\nThe Eclipse Transformer is provided with two specific built-in capabilities:\n\n* To update the target resources according to user specified rules data, which includes Jakarta package renaming rules.  The target resource is an JavaEE version of an implementation jar, or is a JavaEE version of an OSGi implementation jar, or is a JavaEE version of an application archive.\n\n* To shade a target resource according to user specified rules, including, in particular, package renaming rules.  The target resource is an implementation jar.\n\nIn addition to the specific built-in capabilities, other transformations may be performed by changing the rules data, or by adding new types of update action.\n\nThe Eclipse Transformer is provided with Command Line and with Java APIs:\n\n* Transformer classes may be used directly within java code.\n\n* Transformation function is accessible through two Command Line APIs.  A generic command line API, which requires user specified update data, may be used.  A Jakarta command line API, which has built-in Jakarta rules data, may also be used.\n\n## Scope\n\nThe Eclipse Transformer operates on resources, including but not limited to the following:\n\nSimple resources:\n\n* Java class files\n* OSGi feature manifest files\n* Properties files\n* Service loader configuration files\n* Text files (of several types: java source, XML, TLD, HTML, and JSP)\n\nContainer resources:\n\n* Directories\n* Java archives (JAR, WAR, RAR, and EAR files)\n* ZIP archives\n\n## APIs\n\nThe Eclipse Transformer provides three core APIs: A java entry point and two command line entry points:\n\n* Class **org.eclipse.transformer.Transformer** provides for direct invocation from java.\n\n* Class **org.eclipse.transformer.cli.TransformerCLI** provides a standard **main** command line entry point.\n\n* Class **org.eclipse.transformer.cli.JakartaTransformerCLI** provides an addition **main** command line entry point.  **JakartaTransformerCLI** uses **JakartaTransform** which is packaged with default update properties files and supplies these as default property files for the several update properties files.\n\n## Use Cases\n\nPrimary use cases are as follows:\n\n* **Simple resource case**: A target simple file is specified to be transformed.  The command line interface is used to create a transformed copy of the file.  Particular transformations are selected for the file based on the type of the file.  Particular updates made by the transformation are based on property files which are specified to the transformer.\n\n* **Archive case**: A target archive is specified to be transformed.  The command line interface is used to create a transformed copy of the archive.  All contents of the target archive, including nested archives, are transformed.  Particular transformations are selected for the archive based on the type of the file.  Particular updates made by the transformation are based on property files which are specified to the transformer.\n\n* **Directory case**: A target directory is specified to be transformed.  The command line interface is used to create a transformed copy of all the resources within the directory, and within all subdirectories of the specified directory.  Transformation of each file within the target directory is according the simple resource case and the archive case.\n\nPossible secondary use cases are as follows:\n\n* **Classloading case**: A java class action is created and initialized, and is wired into a custom class loader.  When loading resources, in particular, when loading a class resource, the java class action is used to transform the contents of the resource before making them available to the class loader.\n\n## Usage\n\nThe transformer CLI can be invoked by using `java -jar org.eclipse.transformer.cli-\u003cversion\u003e.jar` from now on referred as `TransformerCLI`. This file can be found in the `org.eclipse.transformer.cli/target` folder when you build this project by yourself, or you can download and extract the `org.eclipse.transformer.cli-\u003cversion\u003e-distribution.jar` into a directory of your choice and start it from there.\n\nThe primary use of the Eclipse Transformer is to create an updated copy an input file or directory.  Generally:\n\n    TransformerCLI input [ output ] [ options ... ]\n\nTo get more information on available options use:\n\n    TransformerCLI --help\n\nFor simplicity, the transformer does not perform any \"in-place\" updates.  Replacement of an input file with an output file must be performed as an operation external to the transformer.\n\nThe input file is expected to be either a specific type of file (for example, a java class file), or a container type file; usually, a zip, java, or JavaEE  archive, or a directory.\n\nIn addition to the output file, the transformer produces a change report.  The change report tells if any updates were made to the target file, and provides details on what changes were made.  What details are provided depends on the type of file which is transformer.\n\nWhen the input file is a container type file, the transformer is applied to all the elements of the container.\n\nThe transformer recursively processes nested archives.  For example, Web Application Archives (WAR files) located within Enterprise Application Archives (EAR files) are processed.\n\n## Updates\n\nA core function of the Eclipse Transformer is to locate java package references within resources and to update these references using package rename data.\n\nAdditional functions are to update OSGi bundle metadata, for example, to change the bundle metadata, or to change package versions for renamed package references.\n\nFor class shading, usual target resources are java class files or a java archives.\n\nFor Jakarta related updates, usual target resources are implementation jar files and JavaEE application archives.\n\n## Rules Data Files\n\nUpdate data is specified using property files.  A set of default property files are included in the packaging of the Jakarta command line interface.  User specified property files must be provided when using the generic command line interface.  Property files are specified using command line options:\n\n| Command Line Option | Description                 | Jakarta Example              |\n|---------------------|-----------------------------|------------------------------|\n| -ts --selection     | Target selections           | jakarta-selection.properties |\n| -tr --renames       | Package renames             | jakarta-renames.properties   |\n| -tv --versions      | Package version assignments | jakarta-versions.properties  |\n| -tb --bundles       | Bundle identity data        | jakarta-bundles.properties   |\n| -td --direct        | Java class direct updates   | jakarta-direct.properties    |\n\nAll property options may be specified zero, one, or multiple times.\n\nWhen the same property option is specified multiple times, the property file data for that option is read first to last, where later data overwrites earlier data. Overwriting occurs on individual property values.\n\nAn additional core property file is used as a master table for text updates:\n\n| Command Line Option | Description      | Jakarta Example                |\n|---------------------|------------------|--------------------------------|\n| -tf --text          | Text master data | jakarta-text-master.properties |\n\nThe master text properties file maps file selection patterns (for example, \"\\*.xml\", or \"\\*.html\") to specific text properties files.\n\nA special \"immediate\" option exists that allows the specification of rules data directly on the command line:\n\n| Command Line Option | Description    | Jakarta Example |\n|---------------------|----------------|-----------------|\n| -ti --immediate     | Immediate data | None            |\n\nThe immediate option has the format:\n\n    -ti ( tr | tv | tb | td | tf ) key value\n\nThe first parameter is the tag for one of the usual property options, specified without the '-' prefix.\n\nThe \"key\" and \"value\" values are composed to create a property definition, the equivalent of specifying \"key=value\" in a properties file.  The property value is taken as new property data according to the tag which was used.\n\nImmediate options are processed after property file options are processed.  Individual property definitions obtained as immediate data are overlaid onto and replace individual property definitions obtained from property files.\n\nImmediate options may be used with or without specifying a corresponding properties file.\n\n## Artifacts\n\nThe Eclipse Transformer artifacts are released to Maven Central.\n\nSnapshot artifacts are released to the Sonatype OSS repository: [https://oss.sonatype.org/content/repositories/snapshots/](https://oss.sonatype.org/content/repositories/snapshots/org/eclipse/transformer/).\n\nTo use the snapshot artifacts in your Maven build, you can configure the Sonatype OSS snapshot repository.\n\n```xml\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003eossrh\u003c/id\u003e\n        \u003curl\u003ehttps://oss.sonatype.org/content/repositories/snapshots/\u003c/url\u003e\n        \u003clayout\u003edefault\u003c/layout\u003e\n        \u003creleases\u003e\n            \u003cenabled\u003efalse\u003c/enabled\u003e\n        \u003c/releases\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n```\n\nTo use the snapshot transformer maven plugin in your Maven build, you can configure the Sonatype OSS snapshot repository.\n\n```xml\n\u003cpluginRepositories\u003e\n    \u003cpluginRepository\u003e\n        \u003cid\u003eossrh\u003c/id\u003e\n        \u003curl\u003ehttps://oss.sonatype.org/content/repositories/snapshots/\u003c/url\u003e\n        \u003clayout\u003edefault\u003c/layout\u003e\n        \u003creleases\u003e\n            \u003cenabled\u003efalse\u003c/enabled\u003e\n        \u003c/releases\u003e\n    \u003c/pluginRepository\u003e\n\u003c/pluginRepositories\u003e\n```\n\n## Contributing\n\nIf you would like to contribute to Transformer, check out the [contributing guide](CONTRIBUTING.md) for more information.\n\n## Additional documentation\n\nSee the following files for more detailed information:\n\n* [INFRA.md](INFRA.md)      Project infrastructure and build notes\n* [DEV.md](DEV.md)        Developer overview\n* [RULES.md](RULES.md)      Transformer actions and rules details\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-transformer%2Ftransformer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feclipse-transformer%2Ftransformer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-transformer%2Ftransformer/lists"}