Bug 1086733 - [Doc Change] Changes in PicketLink API between versions 2.1 and 2.5
Summary: [Doc Change] Changes in PicketLink API between versions 2.1 and 2.5
Alias: None
Product: JBoss Enterprise Application Platform 6
Classification: JBoss
Component: Documentation
Version: 6.3.0
Hardware: Unspecified
OS: Unspecified
Target Milestone: GA
: EAP 6.3.0
Assignee: Scott Mumford
QA Contact: Ondrej Lukas
Depends On:
TreeView+ depends on / blocked
Reported: 2014-04-11 11:53 UTC by Ondrej Lukas
Modified: 2014-08-14 15:18 UTC (History)
10 users (show)

Fixed In Version:
Doc Type: Known Issue
Doc Text:
PicketLink 2.5 has brought some API changes from PicketLink 2.1, which was included in previous JBoss EAP 6.x releases. These changes include several classes being which affects backwards compatibility. PicketLink 2.1 applications will need to be updated with the changes. The full list of changes is provided at the end of this document.
Clone Of:
Last Closed: 2014-08-06 14:35:03 UTC
Type: Bug

Attachments (Terms of Use)

Description Ondrej Lukas 2014-04-11 11:53:52 UTC
Public API of PicketLink 2.5 contained in EAP 6.3.0 has changed since PicketLink 2.1 included in previous EAP 6.x versions. Release Notes needs to document these changes or provide a reference to document describing migration from PicketLink 2.1 to 2.5.
According to [1], org.picketlink is treated as public API, hence customers are allowed to use this API and full support is provided. The changes in the API can render customer applications uncompilable and defunct after EAP upgrade to 6.3.0. Hence this change needs to be documented in sufficient detail.
_Non-exhaustive_ example of the API changes:
* Classes from org.picketlink.identity.federation.core.config package were moved to org.picketlink.config.federation
* Classes from org.picketlink.identity.federation.core.exceptions package were moved to org.picketlink.common.exceptions
* Classes from org.picketlink.identity.federation.core.handler.package config were moved to org.picketlink.config.federation.handler
* Classes Base64 and PBEUtils from org.picketlink.identity.federation.core.util package were moved to org.picketlink.common.util
There might have been other changes as well. Consult the respective developers to check and document all the changes in API that could have impact on customers.
[1] https://mojo.redhat.com/docs/DOC-137409

Comment 2 Russell Dickenson 2014-05-14 01:12:19 UTC
Attention: Anil

In this BZ ticket's description, Ondrej notes "_Non-exhaustive_ example of the API changes". Is there an authoritative reference of differences between PL 2.1 and 2.5 which I can include in the EAP 6.3.0 Release Notes? We particularly need to highlight any instances where changes may break compatibility.

Comment 3 Anil Saldhana 2014-05-14 21:31:21 UTC
Russell - Ondrej is correct.

We need move a bunch of internal classes around.  The list of packages that were moved is correct.

You can document the packages moved.  

They do not affect user applications.

Comment 4 Russell Dickenson 2014-05-15 02:54:34 UTC
I was not sure of the meaning of Anil's feedback in comment 3, so I asked for clarification via IRC:

<rdickens> asaldhan: do i understand correctly that the list of modules mentioned by Ondrej is the *complete* list of modules which were moved between PL 2.1 and 2.5?
<rdickens> asaldhan: thank you

Comment 5 Russell Dickenson 2014-05-15 03:51:51 UTC
I have changed the release notes flag as Anil Saldhana has confirmed that these API changes will not affect customer applications already using PicketLink 2.5.

Comment 6 Hynek Mlnarik 2014-05-15 06:57:44 UTC
The changes do affect backwards compatibility. Applications using PL 2.1 API do not even compile with 2.5 and their source (at least the imports, maybe more?) needs to be changed. All of these changes need to be documented as PL API is a part of the EAP public API. 

Anil, Russell, please provide full list of changes to the Release Notes or note to Rel Notes and full list into more appropriate guide. 

Russell, please change the RN text accordingly. It must be stated that the changes are _not_ backwards compatible.

Comment 13 Scott Mumford 2014-06-10 01:01:48 UTC
Topic 35798 has been created to contain the API changes and has been added to the content spec for the 6.3.0 Release Notes.

Comment 14 Scott Mumford 2014-06-10 03:48:11 UTC
Moving ticket to MODIFIED pending document rebuild.

Comment 15 Scott Mumford 2014-06-16 04:49:35 UTC
Moving to POST pending rebuild of the Release Notes.

Update will be available at the below URL (Info will be in an appendix at the end of the document).


Comment 17 FIlip Bogyai 2014-07-01 13:10:28 UTC
In EAP 6.3 Release Notes section 8. API changes between PicketLink versions 2.1 and 2.5, there is wrong package name in the beggining. Change the first package name from "org.picketlink.identity.federation.core.configliteral>" to "org.picketlink.identity.federation.core.config"

Comment 18 Scott Mumford 2014-07-08 21:02:44 UTC
Nice catch Filip. Markup goof. I've fixed it now.

Comment 19 Scott Mumford 2014-07-15 04:39:43 UTC
A new build of the 6.3.0 Release Notes is available for review at:

When verifying bugs, please ensure you're viewing the latest version of the document (6.3.0-14 or later).

Build details:

Comment 20 FIlip Bogyai 2014-07-15 09:29:29 UTC
Verified in Revision 6.3.0-14

Comment 21 Scott Mumford 2014-07-17 01:19:31 UTC
Moving back to assigned as a tracker (so I don't forget to add this content in the final GA build).

Comment 22 Scott Mumford 2014-07-25 05:47:47 UTC
A new version of the Release Notes is available for review at:
(ensure you're reviewing version 6.3.0-17)

Brew task:

Comment 23 Hynek Mlnarik 2014-07-25 08:20:21 UTC
Verified in Revision 6.3.0-17

Note You need to log in before you can comment on or make changes to this bug.