[jira] [Commented] (LOG4J2-2234) Clarify which classes in core are internal vs exported

["Remko Popma (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/LOG4J2-2234?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16366553#comment-16366553 ] 

Remko Popma commented on LOG4J2-2234:
-------------------------------------

Some text I wrote to update announcements.vm. Now that we decided to do this work in 3.0, it will likely need to be rewritten by the time we do the actual release. Parts of it may still be useful, so sharing it here.

{quote}
//announcement.vm

Potential breaking changes:

While the Log4j 2 community is committed to preserving binary compatibility for the Log4j API
jar, the Log4j Core jar was intended as "private" and subject to change. It turned out that
in order to extend Log4j with custom plugins, users often found it necessary or very convenient
to depend on classes in the Log4j Core jar. The need to preserve binary compatibility for the
Log4j Core jar made it difficult for the Log4j Core module to evolve.

This release intends to create clarity as to which packages can be safely depended on. Packages
with "internal" in the name contain classes and interface that should be considered private and
cannot be depended on. Such packages will not be exported when Log4j Core becomes a
full-fledged Java 9 module.

To create this clarity, existing classes in Log4j Core have been moved to new modules and new
packages. A list of potential breaking changes follows below:

* Moved time-related classes from `org.apache.logging.log4j.core.util` to
  `org.apache.logging.log4j.core.time.internal`
* Renamed package `org.apache.logging.log4j.core.util.datetime` to
  `org.apache.logging.log4j.core.time.internal.format`

* The XML, JSON and YAML formats changed in the 2.11.0 release: they no longer have the
  "timeMillis" attribute and instead have an "Instant" element with "epochSecond" and
  "nanoOfSecond" attributes.

Packages moved out of Log4j Core:
* (log4j-cvs) `org.apache.logging.log4j.core.layout` became `org.apache.logging.log4j.csv.layout`
* (log4j-jeromq) `org.apache.logging.log4j.core.appender.mom.jeromq` became `org.apache.logging.log4j.jeromq.appender`
* (log4j-jpa) `org.apache.logging.log4j.core.appender.db.jpa` became `org.apache.logging.log4j.jpa.appender`
* (log4j-jpa) `org.apache.logging.log4j.core.appender.db.jpa.converter` became `org.apache.logging.log4j.jpa.converter`
* (log4j-kafka) `org.apache.logging.log4j.core.appender.mom.kafka` became `org.apache.logging.log4j.kafka.appender`
* (log4j-mongodb2) `org.apache.logging.log4j.mongodb` became `org.apache.logging.log4j.mongodb2`
* (log4j-mongodb3) `org.apache.logging.log4j.mongodb` became `org.apache.logging.log4j.mongodb3`
* (log4j-smtp) `org.apache.logging.log4j.core.appender` became `org.apache.logging.log4j.smtp.appender`
{quote}


> Clarify which classes in core are internal vs exported
> ------------------------------------------------------
>
>                 Key: LOG4J2-2234
>                 URL: https://issues.apache.org/jira/browse/LOG4J2-2234
>             Project: Log4j 2
>          Issue Type: Epic
>          Components: Core
>            Reporter: Remko Popma
>            Priority: Major
>             Fix For: 3.0.0
>
>
> While the Log4j 2 community is committed to preserving binary compatibility for the Log4j API jar, the Log4j Core jar was intended as "private" and subject to change. It turned out that in order to extend Log4j with custom plugins, users often found it necessary or very convenient to depend on classes in the Log4j Core jar. The need to preserve binary compatibility for the Log4j Core jar made it difficult for the Log4j Core module to evolve.
> This epic intends to create clarity as to which packages can be safely depended on.  Existing classes in Log4j Core that should be considered private and cannot be depended on need to be moved to new packages with "internal" in the name. Such packages will not be exported when Log4j Core becomes a full-fledged Java 9 module.



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)