You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tomee.apache.org by jg...@apache.org on 2020/04/17 16:08:46 UTC
[tomee] branch master updated: Add docs and rename rules
This is an automated email from the ASF dual-hosted git repository.
jgallimore pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tomee.git
The following commit(s) were added to refs/heads/master by this push:
new 21d05cc Add docs and rename rules
21d05cc is described below
commit 21d05cc4e1a80fb91ac10691ee7a221dc60936d4
Author: Jonathan Gallimore <jo...@jrg.me.uk>
AuthorDate: Fri Apr 17 17:07:50 2020 +0100
Add docs and rename rules
---
docs/jakartaee-9/eclipse-transformer.adoc | 122 ++++++++++++++++++++++++
docs/jakartaee-9/index.adoc | 38 ++++++++
transformer/jakarta-renames.properties | 148 ++++++++++++++++++++++++++++++
3 files changed, 308 insertions(+)
diff --git a/docs/jakartaee-9/eclipse-transformer.adoc b/docs/jakartaee-9/eclipse-transformer.adoc
new file mode 100644
index 0000000..7000998
--- /dev/null
+++ b/docs/jakartaee-9/eclipse-transformer.adoc
@@ -0,0 +1,122 @@
+:index-group: Jakarta EE 9 Work
+:jbake-date: 2020-04-17
+:jbake-type: page
+:jbake-status: published
+
+
+= Eclipse Transformer
+
+The Eclipse Transformer provides translation from javax to jakarta on various artifacts, including Java source source, compiled Java classes, along with jar, war and ear files.
+
+== Building
+
+The Transformer is a project at the Eclipse Foundation, and is built using Gradle. To checkout and build from source, do the following:
+
+[source,bash]
+----
+git clone https://github.com/tbitonti/jakartaee-prototype
+cd jakartaee-prototype
+./gradlew assembleDist
+----
+
+This will produce a tar and a zip in the `transformer/build/distributions` directory.
+
+== Running
+
+Unzip the resulting zip file, and add the `bin` directory to your `PATH` variable, and you should be able to run the transformer using the `transformer` script.
+
+Running `transformer -u` will provide the usage information:
+
+[source,bash]
+----
+usage: org.eclipse.transformer.Transformer input [ output ] [ options ]
+Options:
+ -d,--dryrun Dry run
+ -h,--help Display help
+ -i,--invert Invert transformation rules
+ -lf,--logFile <arg> Logging file
+ -ll,--logLevel <arg> Logging level
+ -ln,--logName <arg> Logger name
+ -lp,--logProperty <arg> Logging property
+ -lpf,--logPropertyFile <arg> Logging properties file
+ -o,--overwrite Overwrite
+ -q,--quiet Display quiet output
+ -t,--type <arg> Input file type
+ -tb,--bundles <arg> Transformation bundle updates URL
+ -td,--direct <arg> Transformation direct string replacements
+ -tf,--xml <arg> Map of XML filenames to property files
+ -tr,--renames <arg> Transformation package renames URL
+ -ts,--selection <arg> Transformation selections URL
+ -tv,--versions <arg> Transformation package versions URL
+ -u,--usage Display usage
+ -v,--verbose Display verbose output
+Actions:
+ [ NULL ]
+ [ CLASS ]
+ [ MANIFEST ]
+ [ FEATURE ]
+ [ SERVICE_LOADER_CONFIG ]
+ [ XML ]
+ [ ZIP ]
+ [ JAR ]
+ [ WAR ]
+ [ RAR ]
+ [ EAR ]
+ [ JAVA ]
+ [ DIRECTORY ]
+Logging Properties:
+ [ org.slf4j.simpleLogger.logFile ]
+ [ org.slf4j.simpleLogger.cacheOutputStream ]
+ [ org.slf4j.simpleLogger.defaultLogLevel ]
+ [ org.slf4j.simpleLogger.log.a.b.c ]
+ [ org.slf4j.simpleLogger.levelInBrackets ]
+ [ org.slf4j.simpleLogger.showDateTime ]
+ [ org.slf4j.simpleLogger.dateTimeFormat ]
+ [ org.slf4j.simpleLogger.showThreadName ]
+ [ org.slf4j.simpleLogger.showLogName ]
+ [ org.slf4j.simpleLogger.showShortLogName ]
+ [ org.slf4j.simpleLogger.warnLevelString ]
+
+----
+
+With an already built and extracted TomEE server, we can do some experimentation.
+
+Rename the lib folder:
+
+[source,bash]
+----
+mv lib javaee-lib
+----
+
+Create a Jakarta EE lib folder:
+
+[source,bash]
+----
+mkdir jakartee-lib
+----
+
+Translate each of the jars in the javaee-lib folder:
+
+[source,bash]
+----
+cd javaee-lib
+
+for f in *; do transformer $f ../jakartaee-lib/$f -tr <path/to/rules/file>; done
+----
+
+See the rules section below for the rules file.
+
+Symlink jakartaee-lib folder to lib:
+
+[source,bash]
+----
+cd ..
+ln -s jakartaee-lib lib
+----
+
+You should now be able to start a Jakarta-ized version of TomEE. (Expect errors - these can be discussed on the list)
+
+
+== Rules
+
+The current rules for package renames are in the `transformer/jakarta-renames.properties` file in the main TomEE source repository.
diff --git a/docs/jakartaee-9/index.adoc b/docs/jakartaee-9/index.adoc
new file mode 100644
index 0000000..a274912
--- /dev/null
+++ b/docs/jakartaee-9/index.adoc
@@ -0,0 +1,38 @@
+:index-group: Jakarta EE 9 Work
+:jbake-date: 2020-04-17
+:jbake-type: page
+:jbake-status: published
+
+
+= Jakarta EE 9 Work
+
+This page is something of a work-in-progress, but attempts to serve as an entrypoint for anyone looking to get involved with this work.
+
+== Challenge
+
+Jakarta EE 9 removes a very small number of specifications, and doesn't introduce functional changes to the specifications. It does, however, introduce a package
+rename, which will have a very wide impact. Not only do the specification jars and implementations in the server need to change their namespaces, user applications
+will need to change any references as well.
+
+== Goals
+
+* Try and maintain a single codebase for javax and jakarta. It's tempting to fork master and embark on a massive renaming exercise. That's complex as we'd need to do that for various dependencies as well, who may also have other branches and timelines. Having two code-bases also means that any changes need to be applied twice, and with renamed packages, its unlikely the git merging or cherry-picking will work.
+
+* Be backwards compatible - One goal I had in my mined, is that if you have an application that uses javax, you'd probably like to be able to run it on a new Jakarta EE server. There are some options here - I quite like the idea of running the Transformer as a javaagent, so any applications deployed using the old namespaces are converted on the fly at the bytecode level.
+
+* Tooling - I wonder what tooling we could potentially provide? One thought I had was a Maven plugin that can transform a war/ear file for you as part of a build.
+
+
+== Approaches
+
+* Eclipse Transformer
+
+Investigate the use of the Eclipse Transformer (link:https://projects.eclipse.org/projects/technology.transformer[https://projects.eclipse.org/projects/technology.transformer]) to translate the server, and the example applications to the Jakarta namespace.
+
+link:eclipse-transformer.html[Building and running the Eclipse Transformer]
+
+* ???
+
+== Tasks Tracker
+
+TBD: something will appear here soon
diff --git a/transformer/jakarta-renames.properties b/transformer/jakarta-renames.properties
new file mode 100644
index 0000000..2c59c11
--- /dev/null
+++ b/transformer/jakarta-renames.properties
@@ -0,0 +1,148 @@
+# Configuration file to specify package names which are to be renamed.
+#
+# Format:
+# currentPackageName=newPackageName
+#
+# The current package name can contain a ".*" suffix which indicates
+# that sub-packages are to be matched. For example:
+#
+# javax.servlet.*=jakartax.servlet
+#
+# This will cause sub-packages like javax.servlet.annotation
+# to be replaced with jakartax.servlet.annotation
+#
+javax.inject=jakarta.inject
+javax.servlet=jakarta.servlet
+javax.servlet.annotation=jakarta.servlet.annotation
+javax.servlet.descriptor=jakarta.servlet.descriptor
+javax.servlet.http=jakarta.servlet.http
+javax.servlet.resources=jakarta.servlet.resources
+javax.servlet.jsp=jakarta.servlet.jsp
+javax.el=jakarta.el
+javax.servlet.jsp.el=jakarta.servlet.jsp.el
+javax.servlet.jsp.resources=jakarta.servlet.jsp.resources
+javax.servlet.jsp.tagext=jakarta.servlet.jsp.tagext
+
+javax.servlet.jsp.jstl.core=jakarta.servlet.jsp.jstl.core
+javax.servlet.jsp.jstl.fmt=jakarta.servlet.jsp.jstl.fmt
+javax.servlet.jsp.jstl.sql=jakarta.servlet.jsp.jstl.sql
+javax.servlet.jsp.jstl.tlv=jakarta.servlet.jsp.jstl.tlv
+
+#Feature Manifests
+# com.ibm.websphere.javaee.jsp.2.3=jakarta.servlet.jsp-api
+
+com.ibm.websphere.javaee.servlet.4.0=jakarta.servlet-api.5.0
+
+javax.activation=jakarta.activation
+javax.annotation=jakarta.annotation
+javax.annotation.security=jakarta.annotation.security
+javax.annotation.sql=jakarta.annotation.sql
+javax.batch.api=jakarta.batch.api
+javax.batch.api.chunk=jakarta.batch.api.chunk
+javax.batch.api.chunk.listener=jakarta.batch.api.chunk.listener
+javax.batch.api.listener=jakarta.batch.api.listener
+javax.batch.api.partition=jakarta.batch.api.partition
+javax.batch.operations=jakarta.batch.operations
+javax.batch.runtime=jakarta.batch.runtime
+javax.batch.runtime.context=jakarta.batch.runtime.context
+javax.decorator=jakarta.decorator
+javax.ejb=jakarta.ejb
+javax.ejb.embeddable=jakarta.ejb.embeddable
+javax.ejb.spi=jakarta.ejb.spi
+javax.enterprise.concurrent=jakarta.enterprise.concurrent
+javax.enterprise.context=jakarta.enterprise.context
+javax.enterprise.context.control=jakarta.enterprise.context.control
+javax.enterprise.context.spi=jakarta.enterprise.context.spi
+javax.enterprise.event=jakarta.enterprise.event
+javax.enterprise.inject=jakarta.enterprise.inject
+javax.enterprise.inject.literal=jakarta.enterprise.inject.literal
+javax.enterprise.inject.se=jakarta.enterprise.inject.se
+javax.enterprise.inject.spi=jakarta.enterprise.inject.spi
+javax.enterprise.inject.spi.configurator=jakarta.enterprise.inject.spi.configurator
+javax.enterprise.util=jakarta.enterprise.util
+javax.faces=jakarta.faces
+javax.faces.annotation=jakarta.faces.annotation
+javax.faces.application=jakarta.faces.application
+javax.faces.bean=jakarta.faces.bean
+javax.faces.component=jakarta.faces.component
+javax.faces.component.behavior=jakarta.faces.component.behavior
+javax.faces.component.html=jakarta.faces.component.html
+javax.faces.component.search=jakarta.faces.component.search
+javax.faces.component.visit=jakarta.faces.component.visit
+javax.faces.context=jakarta.faces.context
+javax.faces.convert=jakarta.faces.convert
+javax.faces.el=jakarta.faces.el
+javax.faces.event=jakarta.faces.event
+javax.faces.flow=jakarta.faces.flow
+javax.faces.flow.builder=jakarta.faces.flow.builder
+javax.faces.lifecycle=jakarta.faces.lifecycle
+javax.faces.model=jakarta.faces.model
+javax.faces.push=jakarta.faces.push
+javax.faces.render=jakarta.faces.render
+javax.faces.validator=jakarta.faces.validator
+javax.faces.view=jakarta.faces.view
+javax.faces.view.facelets=jakarta.faces.view.facelets
+javax.faces.webapp=jakarta.faces.webapp
+javax.interceptor=jakarta.interceptor
+javax.jms=jakarta.jms
+javax.json=jakarta.json
+javax.json.bind=jakarta.json.bind
+javax.json.bind.adapter=jakarta.json.bind.adapter
+javax.json.bind.annotation=jakarta.json.bind.annotation
+javax.json.bind.config=jakarta.json.bind.config
+javax.json.bind.serializer=jakarta.json.bind.serializer
+javax.json.bind.spi=jakarta.json.bind.spi
+javax.json.spi=jakarta.json.spi
+javax.json.stream=jakarta.json.stream
+javax.mail=jakarta.mail
+javax.mail.event=jakarta.mail.event
+javax.mail.internet=jakarta.mail.internet
+javax.mail.search=jakarta.mail.search
+javax.mail.util=jakarta.mail.util
+javax.management.j2ee=jakarta.management.j2ee
+javax.management.j2ee.statistics=jakarta.management.j2ee.statistics
+javax.persistence=jakarta.persistence
+javax.persistence.criteria=jakarta.persistence.criteria
+javax.persistence.metamodel=jakarta.persistence.metamodel
+javax.persistence.spi=jakarta.persistence.spi
+javax.resource=jakarta.resource
+javax.resource.cci=jakarta.resource.cci
+javax.resource.spi=jakarta.resource.spi
+javax.resource.spi.endpoint=jakarta.resource.spi.endpoint
+javax.resource.spi.security=jakarta.resource.spi.security
+javax.resource.spi.work=jakarta.resource.spi.work
+javax.security.auth.message=jakarta.security.auth.message
+javax.security.auth.message.callback=jakarta.security.auth.message.callback
+javax.security.auth.message.config=jakarta.security.auth.message.config
+javax.security.auth.message.module=jakarta.security.auth.message.module
+javax.security.enterprise=jakarta.security.enterprise
+javax.security.enterprise.authentication.mechanism.http=jakarta.security.enterprise.authentication.mechanism.http
+javax.security.enterprise.credential=jakarta.security.enterprise.credential
+javax.security.enterprise.identitystore=jakarta.security.enterprise.identitystore
+javax.security.jacc=jakarta.security.jacc
+javax.transaction=jakarta.transaction
+javax.validation=jakarta.validation
+javax.validation.bootstrap=jakarta.validation.bootstrap
+javax.validation.constraints=jakarta.validation.constraints
+javax.validation.constraintvalidation=jakarta.validation.constraintvalidation
+javax.validation.executable=jakarta.validation.executable
+javax.validation.groups=jakarta.validation.groups
+javax.validation.metadata=jakarta.validation.metadata
+javax.validation.spi=jakarta.validation.spi
+javax.validation.valueextraction=jakarta.validation.valueextraction
+javax.websocket=jakarta.websocket
+javax.websocket.server=jakarta.websocket.server
+javax.ws.rs=jakarta.ws.rs
+javax.ws.rs.client=jakarta.ws.rs.client
+javax.ws.rs.container=jakarta.ws.rs.container
+javax.ws.rs.core=jakarta.ws.rs.core
+javax.ws.rs.ext=jakarta.ws.rs.ext
+javax.ws.rs.sse=jakarta.ws.rs.sse
+javax.xml.bind=jakarta.xml.bind
+javax.xml.bind.annotation=jakarta.xml.bind.annotation
+javax.xml.bind.annotation.adapters=jakarta.xml.bind.annotation.adapters
+javax.xml.bind.attachment=jakarta.xml.bind.attachment
+javax.xml.bind.helpers=jakarta.xml.bind.helpers
+javax.xml.bind.util=jakarta.xml.bind.util
+
+