Initial commit of respository.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..107dbad --- /dev/null +++ b/CONTRIBUTING.md
@@ -0,0 +1,59 @@ +# Contributing to Jakarta Annotations + +Thanks for your interest in this project. + +## Project description + +**Jakarta Annotations** defines a collection of annotations representing common +semantic concepts that enable a declarative style of programming that applies +across a variety of Java technologies. + + * https://projects.eclipse.org/projects/ee4j.ca + +## Developer resources + +Information regarding source code management, builds, coding standards, and +more. + + * https://projects.eclipse.org/projects/ee4j.ca/developer + +The project maintains the following source code repositories + + * https://github.com/eclipse-ee4j/common-annotations-api + +## Eclipse Development Process + +This Eclipse Foundation open project is governed by the Eclipse Foundation +Development Process and operates under the terms of the Eclipse IP Policy. + +The Jakarta EE Specification Committee has adopted the Jakarta EE Specification +Process (JESP) in accordance with the Eclipse Foundation Specification Process +v1.2 (EFSP) to ensure that the specification process is complied with by all +Jakarta EE specification projects. + +* https://eclipse.org/projects/dev_process +* https://www.eclipse.org/org/documents/Eclipse_IP_Policy.pdf +* https://jakarta.ee/about/jesp/ +* https://www.eclipse.org/legal/efsp_non_assert.php + +## Eclipse Contributor Agreement + +Before your contribution can be accepted by the project team contributors must +electronically sign the Eclipse Contributor Agreement (ECA). + + * http://www.eclipse.org/legal/ECA.php + +Commits that are provided by non-committers must have a Signed-off-by field in +the footer indicating that the author is aware of the terms by which the +contribution has been provided to the project. The non-committer must +additionally have an Eclipse Foundation account and must have a signed Eclipse +Contributor Agreement (ECA) on file. + +For more information, please see the Eclipse Committer Handbook: +https://www.eclipse.org/projects/handbook/#resources-commit + +## Contact + +Contact the project developers via the project's "dev" list. + + * https://accounts.eclipse.org/mailing-list/ca-dev
diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..5de3d1b --- /dev/null +++ b/LICENSE.md
@@ -0,0 +1,637 @@ +# Eclipse Public License - v 2.0 + + THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE + PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION + OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. + + 1. DEFINITIONS + + "Contribution" means: + + a) in the case of the initial Contributor, the initial content + Distributed under this Agreement, and + + b) in the case of each subsequent Contributor: + i) changes to the Program, and + ii) additions to the Program; + where such changes and/or additions to the Program originate from + and are Distributed by that particular Contributor. A Contribution + "originates" from a Contributor if it was added to the Program by + such Contributor itself or anyone acting on such Contributor's behalf. + Contributions do not include changes or additions to the Program that + are not Modified Works. + + "Contributor" means any person or entity that Distributes the Program. + + "Licensed Patents" mean patent claims licensable by a Contributor which + are necessarily infringed by the use or sale of its Contribution alone + or when combined with the Program. + + "Program" means the Contributions Distributed in accordance with this + Agreement. + + "Recipient" means anyone who receives the Program under this Agreement + or any Secondary License (as applicable), including Contributors. + + "Derivative Works" shall mean any work, whether in Source Code or other + form, that is based on (or derived from) the Program and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. + + "Modified Works" shall mean any work in Source Code or other form that + results from an addition to, deletion from, or modification of the + contents of the Program, including, for purposes of clarity any new file + in Source Code form that contains any contents of the Program. Modified + Works shall not include works that contain only declarations, + interfaces, types, classes, structures, or files of the Program solely + in each case in order to link to, bind by name, or subclass the Program + or Modified Works thereof. + + "Distribute" means the acts of a) distributing or b) making available + in any manner that enables the transfer of a copy. + + "Source Code" means the form of a Program preferred for making + modifications, including but not limited to software source code, + documentation source, and configuration files. + + "Secondary License" means either the GNU General Public License, + Version 2.0, or any later versions of that license, including any + exceptions or additional permissions as identified by the initial + Contributor. + + 2. GRANT OF RIGHTS + + a) Subject to the terms of this Agreement, each Contributor hereby + grants Recipient a non-exclusive, worldwide, royalty-free copyright + license to reproduce, prepare Derivative Works of, publicly display, + publicly perform, Distribute and sublicense the Contribution of such + Contributor, if any, and such Derivative Works. + + b) Subject to the terms of this Agreement, each Contributor hereby + grants Recipient a non-exclusive, worldwide, royalty-free patent + license under Licensed Patents to make, use, sell, offer to sell, + import and otherwise transfer the Contribution of such Contributor, + if any, in Source Code or other form. This patent license shall + apply to the combination of the Contribution and the Program if, at + the time the Contribution is added by the Contributor, such addition + of the Contribution causes such combination to be covered by the + Licensed Patents. The patent license shall not apply to any other + combinations which include the Contribution. No hardware per se is + licensed hereunder. + + c) Recipient understands that although each Contributor grants the + licenses to its Contributions set forth herein, no assurances are + provided by any Contributor that the Program does not infringe the + patent or other intellectual property rights of any other entity. + Each Contributor disclaims any liability to Recipient for claims + brought by any other entity based on infringement of intellectual + property rights or otherwise. As a condition to exercising the + rights and licenses granted hereunder, each Recipient hereby + assumes sole responsibility to secure any other intellectual + property rights needed, if any. For example, if a third party + patent license is required to allow Recipient to Distribute the + Program, it is Recipient's responsibility to acquire that license + before distributing the Program. + + d) Each Contributor represents that to its knowledge it has + sufficient copyright rights in its Contribution, if any, to grant + the copyright license set forth in this Agreement. + + e) Notwithstanding the terms of any Secondary License, no + Contributor makes additional grants to any Recipient (other than + those set forth in this Agreement) as a result of such Recipient's + receipt of the Program under the terms of a Secondary License + (if permitted under the terms of Section 3). + + 3. REQUIREMENTS + + 3.1 If a Contributor Distributes the Program in any form, then: + + a) the Program must also be made available as Source Code, in + accordance with section 3.2, and the Contributor must accompany + the Program with a statement that the Source Code for the Program + is available under this Agreement, and informs Recipients how to + obtain it in a reasonable manner on or through a medium customarily + used for software exchange; and + + b) the Contributor may Distribute the Program under a license + different than this Agreement, provided that such license: + i) effectively disclaims on behalf of all other Contributors all + warranties and conditions, express and implied, including + warranties or conditions of title and non-infringement, and + implied warranties or conditions of merchantability and fitness + for a particular purpose; + + ii) effectively excludes on behalf of all other Contributors all + liability for damages, including direct, indirect, special, + incidental and consequential damages, such as lost profits; + + iii) does not attempt to limit or alter the recipients' rights + in the Source Code under section 3.2; and + + iv) requires any subsequent distribution of the Program by any + party to be under a license that satisfies the requirements + of this section 3. + + 3.2 When the Program is Distributed as Source Code: + + a) it must be made available under this Agreement, or if the + Program (i) is combined with other material in a separate file or + files made available under a Secondary License, and (ii) the initial + Contributor attached to the Source Code the notice described in + Exhibit A of this Agreement, then the Program may be made available + under the terms of such Secondary Licenses, and + + b) a copy of this Agreement must be included with each copy of + the Program. + + 3.3 Contributors may not remove or alter any copyright, patent, + trademark, attribution notices, disclaimers of warranty, or limitations + of liability ("notices") contained within the Program from any copy of + the Program which they Distribute, provided that Contributors may add + their own appropriate notices. + + 4. COMMERCIAL DISTRIBUTION + + Commercial distributors of software may accept certain responsibilities + with respect to end users, business partners and the like. While this + license is intended to facilitate the commercial use of the Program, + the Contributor who includes the Program in a commercial product + offering should do so in a manner which does not create potential + liability for other Contributors. Therefore, if a Contributor includes + the Program in a commercial product offering, such Contributor + ("Commercial Contributor") hereby agrees to defend and indemnify every + other Contributor ("Indemnified Contributor") against any losses, + damages and costs (collectively "Losses") arising from claims, lawsuits + and other legal actions brought by a third party against the Indemnified + Contributor to the extent caused by the acts or omissions of such + Commercial Contributor in connection with its distribution of the Program + in a commercial product offering. The obligations in this section do not + apply to any claims or Losses relating to any actual or alleged + intellectual property infringement. In order to qualify, an Indemnified + Contributor must: a) promptly notify the Commercial Contributor in + writing of such claim, and b) allow the Commercial Contributor to control, + and cooperate with the Commercial Contributor in, the defense and any + related settlement negotiations. The Indemnified Contributor may + participate in any such claim at its own expense. + + For example, a Contributor might include the Program in a commercial + product offering, Product X. That Contributor is then a Commercial + Contributor. If that Commercial Contributor then makes performance + claims, or offers warranties related to Product X, those performance + claims and warranties are such Commercial Contributor's responsibility + alone. Under this section, the Commercial Contributor would have to + defend claims against the other Contributors related to those performance + claims and warranties, and if a court requires any other Contributor to + pay any damages as a result, the Commercial Contributor must pay + those damages. + + 5. NO WARRANTY + + EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT + PERMITTED BY APPLICABLE LAW, THE PROGRAM IS PROVIDED ON AN "AS IS" + BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR + IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF + TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR + PURPOSE. Each Recipient is solely responsible for determining the + appropriateness of using and distributing the Program and assumes all + risks associated with its exercise of rights under this Agreement, + including but not limited to the risks and costs of program errors, + compliance with applicable laws, damage to or loss of data, programs + or equipment, and unavailability or interruption of operations. + + 6. DISCLAIMER OF LIABILITY + + EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT + PERMITTED BY APPLICABLE LAW, NEITHER RECIPIENT NOR ANY CONTRIBUTORS + SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST + PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE + EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGES. + + 7. GENERAL + + If any provision of this Agreement is invalid or unenforceable under + applicable law, it shall not affect the validity or enforceability of + the remainder of the terms of this Agreement, and without further + action by the parties hereto, such provision shall be reformed to the + minimum extent necessary to make such provision valid and enforceable. + + If Recipient institutes patent litigation against any entity + (including a cross-claim or counterclaim in a lawsuit) alleging that the + Program itself (excluding combinations of the Program with other software + or hardware) infringes such Recipient's patent(s), then such Recipient's + rights granted under Section 2(b) shall terminate as of the date such + litigation is filed. + + All Recipient's rights under this Agreement shall terminate if it + fails to comply with any of the material terms or conditions of this + Agreement and does not cure such failure in a reasonable period of + time after becoming aware of such noncompliance. If all Recipient's + rights under this Agreement terminate, Recipient agrees to cease use + and distribution of the Program as soon as reasonably practicable. + However, Recipient's obligations under this Agreement and any licenses + granted by Recipient relating to the Program shall continue and survive. + + Everyone is permitted to copy and distribute copies of this Agreement, + but in order to avoid inconsistency the Agreement is copyrighted and + may only be modified in the following manner. The Agreement Steward + reserves the right to publish new versions (including revisions) of + this Agreement from time to time. No one other than the Agreement + Steward has the right to modify this Agreement. The Eclipse Foundation + is the initial Agreement Steward. The Eclipse Foundation may assign the + responsibility to serve as the Agreement Steward to a suitable separate + entity. Each new version of the Agreement will be given a distinguishing + version number. The Program (including Contributions) may always be + Distributed subject to the version of the Agreement under which it was + received. In addition, after a new version of the Agreement is published, + Contributor may elect to Distribute the Program (including its + Contributions) under the new version. + + Except as expressly stated in Sections 2(a) and 2(b) above, Recipient + receives no rights or licenses to the intellectual property of any + Contributor under this Agreement, whether expressly, by implication, + estoppel or otherwise. All rights in the Program not expressly granted + under this Agreement are reserved. Nothing in this Agreement is intended + to be enforceable by any entity that is not a Contributor or Recipient. + No third-party beneficiary rights are created under this Agreement. + + Exhibit A - Form of Secondary Licenses Notice + + "This Source Code may also be made available under the following + Secondary Licenses when the conditions for such availability set forth + in the Eclipse Public License, v. 2.0 are satisfied: {name license(s), + version(s), and exceptions or additional permissions here}." + + Simply including a copy of this Agreement, including this Exhibit A + is not sufficient to license the Source Code under Secondary Licenses. + + If it is not possible or desirable to put the notice in a particular + file, then You may include the notice in a location (such as a LICENSE + file in a relevant directory) where a recipient would be likely to + look for such a notice. + + You may add additional accurate notices of copyright ownership. + +--- + +## The GNU General Public License (GPL) Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor + Boston, MA 02110-1335 + USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your freedom to + share and change it. By contrast, the GNU General Public License is + intended to guarantee your freedom to share and change free software--to + make sure the software is free for all its users. This General Public + License applies to most of the Free Software Foundation's software and + to any other program whose authors commit to using it. (Some other Free + Software Foundation software is covered by the GNU Library General + Public License instead.) You can apply it to your programs, too. + + When we speak of free software, we are referring to freedom, not price. + Our General Public Licenses are designed to make sure that you have the + freedom to distribute copies of free software (and charge for this + service if you wish), that you receive source code or can get it if you + want it, that you can change the software or use pieces of it in new + free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid anyone + to deny you these rights or to ask you to surrender the rights. These + restrictions translate to certain responsibilities for you if you + distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether gratis + or for a fee, you must give the recipients all the rights that you have. + You must make sure that they, too, receive or can get the source code. + And you must show them these terms so they know their rights. + + We protect your rights with two steps: (1) copyright the software, and + (2) offer you this license which gives you legal permission to copy, + distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain + that everyone understands that there is no warranty for this free + software. If the software is modified by someone else and passed on, we + want its recipients to know that what they have is not the original, so + that any problems introduced by others will not reflect on the original + authors' reputations. + + Finally, any free program is threatened constantly by software patents. + We wish to avoid the danger that redistributors of a free program will + individually obtain patent licenses, in effect making the program + proprietary. To prevent this, we have made it clear that any patent must + be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and + modification follow. + + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains a + notice placed by the copyright holder saying it may be distributed under + the terms of this General Public License. The "Program", below, refers + to any such program or work, and a "work based on the Program" means + either the Program or any derivative work under copyright law: that is + to say, a work containing the Program or a portion of it, either + verbatim or with modifications and/or translated into another language. + (Hereinafter, translation is included without limitation in the term + "modification".) Each licensee is addressed as "you". + + Activities other than copying, distribution and modification are not + covered by this License; they are outside its scope. The act of running + the Program is not restricted, and the output from the Program is + covered only if its contents constitute a work based on the Program + (independent of having been made by running the Program). Whether that + is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's source + code as you receive it, in any medium, provided that you conspicuously + and appropriately publish on each copy an appropriate copyright notice + and disclaimer of warranty; keep intact all the notices that refer to + this License and to the absence of any warranty; and give any other + recipients of the Program a copy of this License along with the Program. + + You may charge a fee for the physical act of transferring a copy, and + you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion of + it, thus forming a work based on the Program, and copy and distribute + such modifications or work under the terms of Section 1 above, provided + that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any part + thereof, to be licensed as a whole at no charge to all third parties + under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a notice + that there is no warranty (or else, saying that you provide a + warranty) and that users may redistribute the program under these + conditions, and telling the user how to view a copy of this License. + (Exception: if the Program itself is interactive but does not + normally print such an announcement, your work based on the Program + is not required to print an announcement.) + + These requirements apply to the modified work as a whole. If + identifiable sections of that work are not derived from the Program, and + can be reasonably considered independent and separate works in + themselves, then this License, and its terms, do not apply to those + sections when you distribute them as separate works. But when you + distribute the same sections as part of a whole which is a work based on + the Program, the distribution of the whole must be on the terms of this + License, whose permissions for other licensees extend to the entire + whole, and thus to each and every part regardless of who wrote it. + + Thus, it is not the intent of this section to claim rights or contest + your rights to work written entirely by you; rather, the intent is to + exercise the right to control the distribution of derivative or + collective works based on the Program. + + In addition, mere aggregation of another work not based on the Program + with the Program (or with a work based on the Program) on a volume of a + storage or distribution medium does not bring the other work under the + scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, + under Section 2) in object code or executable form under the terms of + Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections 1 + and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your cost + of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer to + distribute corresponding source code. (This alternative is allowed + only for noncommercial distribution and only if you received the + program in object code or executable form with such an offer, in + accord with Subsection b above.) + + The source code for a work means the preferred form of the work for + making modifications to it. For an executable work, complete source code + means all the source code for all modules it contains, plus any + associated interface definition files, plus the scripts used to control + compilation and installation of the executable. However, as a special + exception, the source code distributed need not include anything that is + normally distributed (in either source or binary form) with the major + components (compiler, kernel, and so on) of the operating system on + which the executable runs, unless that component itself accompanies the + executable. + + If distribution of executable or object code is made by offering access + to copy from a designated place, then offering equivalent access to copy + the source code from the same place counts as distribution of the source + code, even though third parties are not compelled to copy the source + along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program + except as expressly provided under this License. Any attempt otherwise + to copy, modify, sublicense or distribute the Program is void, and will + automatically terminate your rights under this License. However, parties + who have received copies, or rights, from you under this License will + not have their licenses terminated so long as such parties remain in + full compliance. + + 5. You are not required to accept this License, since you have not + signed it. However, nothing else grants you permission to modify or + distribute the Program or its derivative works. These actions are + prohibited by law if you do not accept this License. Therefore, by + modifying or distributing the Program (or any work based on the + Program), you indicate your acceptance of this License to do so, and all + its terms and conditions for copying, distributing or modifying the + Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the + Program), the recipient automatically receives a license from the + original licensor to copy, distribute or modify the Program subject to + these terms and conditions. You may not impose any further restrictions + on the recipients' exercise of the rights granted herein. You are not + responsible for enforcing compliance by third parties to this License. + + 7. If, as a consequence of a court judgment or allegation of patent + infringement or for any other reason (not limited to patent issues), + conditions are imposed on you (whether by court order, agreement or + otherwise) that contradict the conditions of this License, they do not + excuse you from the conditions of this License. If you cannot distribute + so as to satisfy simultaneously your obligations under this License and + any other pertinent obligations, then as a consequence you may not + distribute the Program at all. For example, if a patent license would + not permit royalty-free redistribution of the Program by all those who + receive copies directly or indirectly through you, then the only way you + could satisfy both it and this License would be to refrain entirely from + distribution of the Program. + + If any portion of this section is held invalid or unenforceable under + any particular circumstance, the balance of the section is intended to + apply and the section as a whole is intended to apply in other + circumstances. + + It is not the purpose of this section to induce you to infringe any + patents or other property right claims or to contest validity of any + such claims; this section has the sole purpose of protecting the + integrity of the free software distribution system, which is implemented + by public license practices. Many people have made generous + contributions to the wide range of software distributed through that + system in reliance on consistent application of that system; it is up to + the author/donor to decide if he or she is willing to distribute + software through any other system and a licensee cannot impose that choice. + + This section is intended to make thoroughly clear what is believed to be + a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in + certain countries either by patents or by copyrighted interfaces, the + original copyright holder who places the Program under this License may + add an explicit geographical distribution limitation excluding those + countries, so that distribution is permitted only in or among countries + not thus excluded. In such case, this License incorporates the + limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new + versions of the General Public License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the Program + specifies a version number of this License which applies to it and "any + later version", you have the option of following the terms and + conditions either of that version or of any later version published by + the Free Software Foundation. If the Program does not specify a version + number of this License, you may choose any version ever published by the + Free Software Foundation. + + 10. If you wish to incorporate parts of the Program into other free + programs whose distribution conditions are different, write to the + author to ask for permission. For software which is copyrighted by the + Free Software Foundation, write to the Free Software Foundation; we + sometimes make exceptions for this. Our decision will be guided by the + two goals of preserving the free status of all derivatives of our free + software and of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO + WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. + EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR + OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, + EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE + ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH + YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL + NECESSARY SERVICING, REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY + AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR + DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL + DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM + (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED + INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF + THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR + OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest + possible use to the public, the best way to achieve this is to make it + free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest to + attach them to the start of each source file to most effectively convey + the exclusion of warranty; and each file should have at least the + "copyright" line and a pointer to where the full notice is found. + + One line to give the program's name and a brief idea of what it does. + Copyright (C) <year> <name of author> + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335 USA + + Also add information on how to contact you by electronic and paper mail. + + If the program is interactive, make it output a short notice like this + when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type + `show w'. This is free software, and you are welcome to redistribute + it under certain conditions; type `show c' for details. + + The hypothetical commands `show w' and `show c' should show the + appropriate parts of the General Public License. Of course, the commands + you use may be called something other than `show w' and `show c'; they + could even be mouse-clicks or menu items--whatever suits your program. + + You should also get your employer (if you work as a programmer) or your + school, if any, to sign a "copyright disclaimer" for the program, if + necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the + program `Gnomovision' (which makes passes at compilers) written by + James Hacker. + + signature of Ty Coon, 1 April 1989 + Ty Coon, President of Vice + + This General Public License does not permit incorporating your program + into proprietary programs. If your program is a subroutine library, you + may consider it more useful to permit linking proprietary applications + with the library. If this is what you want to do, use the GNU Library + General Public License instead of this License. + +--- + +## CLASSPATH EXCEPTION + + Linking this library statically or dynamically with other modules is + making a combined work based on this library. Thus, the terms and + conditions of the GNU General Public License version 2 cover the whole + combination. + + As a special exception, the copyright holders of this library give you + permission to link this library with independent modules to produce an + executable, regardless of the license terms of these independent + modules, and to copy and distribute the resulting executable under + terms of your choice, provided that you also meet, for each linked + independent module, the terms and conditions of the license of that + module. An independent module is a module which is not derived from or + based on this library. If you modify this library, you may extend this + exception to your version of the library, but you are not obligated to + do so. If you do not wish to do so, delete this exception statement + from your version.
diff --git a/NOTICE.md b/NOTICE.md new file mode 100644 index 0000000..6e7560a --- /dev/null +++ b/NOTICE.md
@@ -0,0 +1,38 @@ +# Notices for Jakarta Annotations + +This content is produced and maintained by the Jakarta Annotations project. + + * Project home: https://projects.eclipse.org/projects/ee4j.ca + +## Trademarks + +Jakarta Annotations is a trademark of the Eclipse Foundation. + +## Declared Project Licenses + +This program and the accompanying materials are made available under the terms +of the Eclipse Public License v. 2.0 which is available at +http://www.eclipse.org/legal/epl-2.0. This Source Code may also be made +available under the following Secondary Licenses when the conditions for such +availability set forth in the Eclipse Public License v. 2.0 are satisfied: GNU +General Public License, version 2 with the GNU Classpath Exception which is +available at https://www.gnu.org/software/classpath/license.html. + +SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + +## Source Code + +The project maintains the following source code repositories: + + * https://github.com/eclipse-ee4j/common-annotations-api + +## Third-party Content + +## Cryptography + +Content may contain encryption software. The country in which you are currently +may have restrictions on the import, possession, and use, and/or re-export to +another country, of encryption software. BEFORE using any encryption software, +please check the country's laws, regulations and policies concerning the import, +possession, or use, and re-export of encryption software, to see if this is +permitted.
diff --git a/README.md b/README.md new file mode 100644 index 0000000..a9ba718 --- /dev/null +++ b/README.md
@@ -0,0 +1,8 @@ +# Jakarta Annotations [](https://travis-ci.org/eclipse-ee4j/common-annotations-api) + +**Jakarta Annotations** defines a collection of annotations representing common +semantic concepts that enable a declarative style of programming that applies +across a variety of Java technologies. + +Jakarta Annotations uses a [Java Platform Module System](http://openjdk.java.net/projects/jigsaw/spec/) +module name `jakarta.annotation`.
diff --git a/api/pom.xml b/api/pom.xml new file mode 100644 index 0000000..60e530a --- /dev/null +++ b/api/pom.xml
@@ -0,0 +1,362 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + + Copyright (c) 2012, 2020 Oracle and/or its affiliates. All rights reserved. + + This program and the accompanying materials are made available under the + terms of the Eclipse Public License v. 2.0, which is available at + http://www.eclipse.org/legal/epl-2.0. + + This Source Code may also be made available under the following Secondary + Licenses when the conditions for such availability set forth in the + Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + version 2 with the GNU Classpath Exception, which is available at + https://www.gnu.org/software/classpath/license.html. + + SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + +--> + +<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> + <modelVersion>4.0.0</modelVersion> + + <parent> + <groupId>org.eclipse.ee4j</groupId> + <artifactId>project</artifactId> + <version>1.0.6</version> + <relativePath/> + </parent> + + <groupId>jakarta.annotation</groupId> + <artifactId>jakarta.annotation-api</artifactId> + <version>2.0.0-SNAPSHOT</version> + + <name>Jakarta Annotations API</name> + <description>Jakarta Annotations API</description> + + <url>https://projects.eclipse.org/projects/ee4j.ca</url> + + <inceptionYear>2004</inceptionYear> + + <developers> + <developer> + <name>Linda De Michiel</name> + <organization>Oracle Corp.</organization> + </developer> + </developers> + + <licenses> + <license> + <name>EPL 2.0</name> + <url>http://www.eclipse.org/legal/epl-2.0</url> + <distribution>repo</distribution> + </license> + <license> + <name>GPL2 w/ CPE</name> + <url>https://www.gnu.org/software/classpath/license.html</url> + <distribution>repo</distribution> + </license> + </licenses> + + <scm> + <connection>scm:git:https://github.com/eclipse-ee4j/common-annotations-api.git</connection> + <developerConnection>scm:git:git@github.com:eclipse-ee4j/common-annotations-api.git</developerConnection> + <url>https://github.com/eclipse-ee4j/common-annotations-api</url> + <tag>HEAD</tag> + </scm> + + <issueManagement> + <system>github</system> + <url>https://github.com/eclipse-ee4j/common-annotations-api/issues</url> + </issueManagement> + + <mailingLists> + <mailingList> + <name>Jakarta Annotations mailing list</name> + <post>ca-dev@eclipse.org</post> + <subscribe>https://dev.eclipse.org/mailman/listinfo/ca-dev</subscribe> + <unsubscribe>https://dev.eclipse.org/mailman/listinfo/ca-dev</unsubscribe> + <archive>https://dev.eclipse.org/mhonarc/lists/ca-dev</archive> + </mailingList> + </mailingLists> + + <properties> + <copyright.ignoreyear>false</copyright.ignoreyear> + <copyright.scmonly>true</copyright.scmonly> + <copyright.update>false</copyright.update> + <spotbugs.skip>false</spotbugs.skip> + <spotbugs.threshold>Low</spotbugs.threshold> + <spotbugs.version>4.0.4</spotbugs.version> + + <non.final>false</non.final> + <spec.version>2.0</spec.version> + <extension.name>jakarta.annotation</extension.name> + <vendor.name>Eclipse Foundation</vendor.name> + <implementation.vendor.id>org.glassfish</implementation.vendor.id> + </properties> + + <build> + <pluginManagement> + <plugins> + <plugin> + <groupId>org.codehaus.mojo</groupId> + <artifactId>build-helper-maven-plugin</artifactId> + <version>3.2.0</version> + </plugin> + <plugin> + <artifactId>maven-compiler-plugin</artifactId> + <version>3.8.1</version> + </plugin> + <plugin> + <groupId>org.glassfish.copyright</groupId> + <artifactId>glassfish-copyright-maven-plugin</artifactId> + <version>2.3</version> + </plugin> + <plugin> + <groupId>org.glassfish.build</groupId> + <artifactId>spec-version-maven-plugin</artifactId> + <version>2.1</version> + </plugin> + <plugin> + <groupId>org.apache.felix</groupId> + <artifactId>maven-bundle-plugin</artifactId> + <version>5.1.1</version> + <configuration> + <instructions> + <_noextraheaders>true</_noextraheaders> + </instructions> + </configuration> + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-jar-plugin</artifactId> + <version>3.2.0</version> + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-source-plugin</artifactId> + <version>3.2.1</version> + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <version>3.2.0</version> + </plugin> + <plugin> + <groupId>com.github.spotbugs</groupId> + <artifactId>spotbugs-maven-plugin</artifactId> + <version>${spotbugs.version}</version> + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-enforcer-plugin</artifactId> + <version>3.0.0-M3</version> + </plugin> + </plugins> + </pluginManagement> + + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-enforcer-plugin</artifactId> + <executions> + <execution> + <id>enforce-maven</id> + <goals> + <goal>enforce</goal> + </goals> + <configuration> + <rules> + <requireJavaVersion> + <version>[11,)</version> + </requireJavaVersion> + <requireMavenVersion> + <version>[3.6.0,)</version> + </requireMavenVersion> + </rules> + </configuration> + </execution> + </executions> + </plugin> + <plugin> + <groupId>org.glassfish.copyright</groupId> + <artifactId>glassfish-copyright-maven-plugin</artifactId> + <configuration> + <!-- skip files not under SCM--> + <scmOnly>${copyright.scmonly}</scmOnly> + <!-- for use with repair --> + <update>${copyright.update}</update> + <!-- check that year is correct --> + <ignoreYear>${copyright.ignoreyear}</ignoreYear> + </configuration> + <executions> + <execution> + <phase>validate</phase> + <goals> + <goal>check</goal> + </goals> + </execution> + </executions> + </plugin> + <plugin> + <groupId>org.codehaus.mojo</groupId> + <artifactId>build-helper-maven-plugin</artifactId> + <executions> + <execution> + <id>add-resource</id> + <phase>generate-resources</phase> + <goals> + <goal>add-resource</goal> + </goals> + <configuration> + <resources> + <resource> + <directory>${basedir}/..</directory> + <targetPath>META-INF</targetPath> + <includes> + <include>LICENSE.md</include> + <include>NOTICE.md</include> + </includes> + </resource> + </resources> + </configuration> + </execution> + </executions> + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-compiler-plugin</artifactId> + <configuration> + <release>9</release> + <compilerArgs> + <arg>-Xlint:all</arg> + </compilerArgs> + </configuration> + <executions> + <execution> + <id>base-compile</id> + <goals> + <goal>compile</goal> + </goals> + <configuration> + <release>8</release> + <excludes> + <exclude>module-info.java</exclude> + </excludes> + </configuration> + </execution> + </executions> + </plugin> + <plugin> + <groupId>org.glassfish.build</groupId> + <artifactId>spec-version-maven-plugin</artifactId> + <configuration> + <specMode>jakarta</specMode> + <spec> + <nonFinal>${non.final}</nonFinal> + <jarType>api</jarType> + <specBuild>${spec.build}</specBuild> + <specVersion>${spec.version}</specVersion> + <newSpecVersion>${new.spec.version}</newSpecVersion> + <specImplVersion>${project.version}</specImplVersion> + <apiPackage>${extension.name}</apiPackage> + </spec> + </configuration> + <executions> + <execution> + <goals> + <goal>set-spec-properties</goal> + <!-- TODO: + glassfish-spec-version-maven-plugin needs to be updated + in order to check 'jakarta.' prefixed values in manifest entries + --> + <!--<goal>check-module</goal>--> + </goals> + </execution> + </executions> + </plugin> + <plugin> + <groupId>org.apache.felix</groupId> + <artifactId>maven-bundle-plugin</artifactId> + <configuration> + <instructions> + <Bundle-Version>${spec.bundle.version}</Bundle-Version> + <Bundle-SymbolicName>${spec.bundle.symbolic-name}</Bundle-SymbolicName> + <Extension-Name>${spec.extension.name}</Extension-Name> + <Implementation-Version>${spec.implementation.version}</Implementation-Version> + <Specification-Version>${spec.specification.version}</Specification-Version> + <Bundle-Description>${project.name}</Bundle-Description> + <Specification-Vendor>${vendor.name}</Specification-Vendor> + <Implementation-Vendor>${project.organization.name}</Implementation-Vendor> + <Implementation-Vendor-Id>${implementation.vendor.id}</Implementation-Vendor-Id> + </instructions> + </configuration> + <executions> + <execution> + <id>bundle-manifest</id> + <phase>process-classes</phase> + <goals> + <goal>manifest</goal> + </goals> + </execution> + </executions> + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-jar-plugin</artifactId> + <configuration> + <archive> + <manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile> + </archive> + </configuration> + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-source-plugin</artifactId> + <configuration> + <archive> + <manifest> + <addDefaultEntries>false</addDefaultEntries> + <addDefaultImplementationEntries>true</addDefaultImplementationEntries> + </manifest> + <manifestEntries> + <Implementation-Build-Id>${buildNumber}</Implementation-Build-Id> + </manifestEntries> + </archive> + </configuration> + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <configuration> + <archive> + <manifest> + <addDefaultEntries>false</addDefaultEntries> + </manifest> + </archive> + <release>11</release> + <additionalOptions>--add-modules java.sql</additionalOptions> + <notimestamp>true</notimestamp> + <nosince>true</nosince> + <docfilessubdirs>true</docfilessubdirs> + <doctitle>Jakarta Annotations ${project.version} API Specification</doctitle> + <header><![CDATA[<br>Jakarta Annotations API v${project.version}]]></header> + <bottom><![CDATA[ + Copyright © 2019, 2020 Eclipse Foundation. All rights reserved.<br> + Use is subject to <a href="{@docRoot}/doc-files/EFSL.html" target="_top">license terms</a>.]]> + </bottom> + </configuration> + </plugin> + <plugin> + <groupId>com.github.spotbugs</groupId> + <artifactId>spotbugs-maven-plugin</artifactId> + <configuration> + <skip>${spotbugs.skip}</skip> + <threshold>${spotbugs.threshold}</threshold> + <findbugsXmlWithMessages>true</findbugsXmlWithMessages> + <fork>true</fork> + </configuration> + </plugin> + </plugins> + </build> +</project>
diff --git a/api/src/main/java/jakarta/annotation/Generated.java b/api/src/main/java/jakarta/annotation/Generated.java new file mode 100644 index 0000000..8ccd0de --- /dev/null +++ b/api/src/main/java/jakarta/annotation/Generated.java
@@ -0,0 +1,67 @@ +/* + * Copyright (c) 2005, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation; +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * The <code>Generated</code> annotation is used to mark source code + * that has been generated. + * It can also be used to differentiate user written code from generated code + * in a single file. + * <p>The <code>value</code> element must have the name of the + * code generator. The recommended convention is to use the fully qualified + * name of the code generator in the value field, + * for example <code>com.company.package.classname</code>.</p> + * <p>The <code>date</code> element is used to indicate the date the + * source was generated. + * The <code>date</code> element must follow the ISO 8601 standard. + * For example, the <code>date</code> element could have the + * value <code>2001-07-04T12:08:56.235-0700</code>, + * which represents 2001-07-04 12:08:56 local time in the U.S. Pacific + * time zone.</p> + * <p>The <code>comment</code> element is a place holder for any comments + * that the code generator may want to include in the generated code.</p> + * + * @since 1.6, Common Annotations 1.0 + */ + +@Documented +@Retention(SOURCE) +@Target({PACKAGE, TYPE, ANNOTATION_TYPE, METHOD, CONSTRUCTOR, FIELD, + LOCAL_VARIABLE, PARAMETER}) +public @interface Generated { + /** + * The value element must have the name of the code generator. + * The recommended convention is to use the fully qualified name of the + * code generator. For example: <code>com.acme.generator.CodeGen</code>. + */ + String[] value(); + + /** + * Date when the source was generated. + */ + String date() default ""; + + /** + * A place holder for any comments that the code generator may want to + * include in the generated code. + */ + String comments() default ""; +} +
diff --git a/api/src/main/java/jakarta/annotation/ManagedBean.java b/api/src/main/java/jakarta/annotation/ManagedBean.java new file mode 100644 index 0000000..496ac9e --- /dev/null +++ b/api/src/main/java/jakarta/annotation/ManagedBean.java
@@ -0,0 +1,46 @@ +/* + * Copyright (c) 2009, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation; + +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * The <code>ManagedBean</code> annotation marks a POJO (Plain Old Java Object) + * as a ManagedBean. A ManagedBean supports a small set of basic services + * such as resource injection, lifecycle callbacks and interceptors. + * + * @since Common Annotations 1.1 + */ +@Target(TYPE) +@Retention(RUNTIME) +public @interface ManagedBean { + /** + * The name of the Jakarta Managed Bean. Jakarta Managed Bean names must be unique within a + * Jakarta EE module. For each named Jakarta Managed Bean, Jakarta EE containers must make + * available the following entries in JNDI, using the same naming scheme used + * for Jakarta Enterprise Beans components. + * <p> + * In the application namespace: <p> + * java:app/<module-name>/<bean-name> <p> + * In the module namespace of the module containing the Jakarta Managed Bean: + * <p> java:module/<bean-name> + * + */ + public String value() default ""; +}
diff --git a/api/src/main/java/jakarta/annotation/PostConstruct.java b/api/src/main/java/jakarta/annotation/PostConstruct.java new file mode 100644 index 0000000..29b156e --- /dev/null +++ b/api/src/main/java/jakarta/annotation/PostConstruct.java
@@ -0,0 +1,73 @@ +/* + * Copyright (c) 2005, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation; + +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * The <code>PostConstruct</code> annotation is used on a method that + * needs to be executed after dependency injection is done to perform + * any initialization. This method must be invoked before the class + * is put into service. This annotation must be supported on all classes + * that support dependency injection. The method annotated with + * <code>PostConstruct</code> must be invoked even if the class does + * not request any resources to be injected. Only one + * method in a given class can be annotated with this annotation. + * The method on which the <code>PostConstruct</code> annotation is + * applied must fulfill all of the following criteria: + * <ul> + * <li>The method must not have any parameters except in the case of + * interceptors in which case it takes an <code>InvocationContext</code> + * object as defined by the Jakarta Interceptors specification.</li> + * <li>The method defined on an interceptor class or superclass of an + * interceptor class must have one of the following signatures: + * <p> + * void <METHOD>(InvocationContext) + * <p> + * Object <METHOD>(InvocationContext) throws Exception + * <p> + * <i>Note: A PostConstruct interceptor method must not throw application + * exceptions, but it may be declared to throw checked exceptions including + * the java.lang.Exception if the same interceptor method interposes on + * business or timeout methods in addition to lifecycle events. If a + * PostConstruct interceptor method returns a value, it is ignored by + * the container.</i> + * </li> + * <li>The method defined on a non-interceptor class must have the + * following signature: + * <p> + * void <METHOD>() + * </li> + * <li>The method on which the <code>PostConstruct</code> annotation + * is applied may be public, protected, package private or private.</li> + * <li>The method must not be static except for the application client.</li> + * <li>The method should not be final.</li> + * <li>If the method throws an unchecked exception the class must not be put into + * service except in the case where the exception is handled by an + * interceptor.</li></ul> + * + * @see jakarta.annotation.PreDestroy + * @see jakarta.annotation.Resource + * @since 1.6, Common Annotations 1.0 + */ +@Documented +@Retention (RUNTIME) +@Target(METHOD) +public @interface PostConstruct { +}
diff --git a/api/src/main/java/jakarta/annotation/PreDestroy.java b/api/src/main/java/jakarta/annotation/PreDestroy.java new file mode 100644 index 0000000..ea93380 --- /dev/null +++ b/api/src/main/java/jakarta/annotation/PreDestroy.java
@@ -0,0 +1,73 @@ +/* + * Copyright (c) 2005, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation; + +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * The <code>PreDestroy</code> annotation is used on a method as a + * callback notification to signal that the instance is in the + * process of being removed by the container. The method annotated + * with <code>PreDestroy</code> is typically used to + * release resources that it has been holding. This annotation must be + * supported by all container-managed objects that support the use of + * the <code>PostConstruct</code> annotation except the Jakarta EE application + * client. The method on which the <code>PreDestroy</code> annotation + * is applied must fulfill all of the following criteria: + * <ul> + * <li>The method must not have any parameters except in the case of + * interceptors in which case it takes an <code>InvocationContext</code> + * object as defined by the Jakarta Interceptors specification.</li> + * <li>The method defined on an interceptor class or superclass of an + * interceptor class must have one of the following signatures: + * <p> + * void <METHOD>(InvocationContext) + * <p> + * Object <METHOD>(InvocationContext) throws Exception + * <p> + * <i>Note: A PreDestroy interceptor method must not throw application + * exceptions, but it may be declared to throw checked exceptions including + * the java.lang.Exception if the same interceptor method interposes on + * business or timeout methods in addition to lifecycle events. If a + * PreDestroy interceptor method returns a value, it is ignored by + * the container.</i> + * </li> + * <li>The method defined on a non-interceptor class must have the + * following signature: + * <p> + * void <METHOD>() + * </li> + * <li>The method on which PreDestroy is applied may be public, protected, + * package private or private.</li> + * <li>The method must not be static.</li> + * <li>The method should not be final.</li> + * <li>If the method throws an unchecked exception it is ignored by + * the container.</li> + * </ul> + * + * @see jakarta.annotation.PostConstruct + * @see jakarta.annotation.Resource + * @since 1.6, Common Annotations 1.0 + */ + +@Documented +@Retention (RUNTIME) +@Target(METHOD) +public @interface PreDestroy { +}
diff --git a/api/src/main/java/jakarta/annotation/Priority.java b/api/src/main/java/jakarta/annotation/Priority.java new file mode 100644 index 0000000..dfd7b1c --- /dev/null +++ b/api/src/main/java/jakarta/annotation/Priority.java
@@ -0,0 +1,50 @@ +/* + * Copyright (c) 2005, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation; + +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * The <code>Priority</code> annotation can be applied to classes + * or parameters to indicate in what order they should be used. + * The effect of using the <code>Priority</code> annotation in + * any particular instance is defined by other specifications that + * define the use of a specific class. + * <p> + * For example, the Jakarta Interceptors specification defines the use of + * priorities on interceptors to control the order in which + * interceptors are called.</p> + * <p> + * Priority values should generally be non-negative, with negative values + * reserved for special meanings such as "undefined" or "not specified". + * A specification that defines use of the <code>Priority</code> annotation may define + * the range of allowed priorities and any priority values with special + * meaning.</p> + * + * @since Common Annotations 1.2 + */ +@Target({TYPE,PARAMETER}) +@Retention(RUNTIME) +@Documented +public @interface Priority { + /** + * The priority value. + */ + int value(); +}
diff --git a/api/src/main/java/jakarta/annotation/Resource.java b/api/src/main/java/jakarta/annotation/Resource.java new file mode 100644 index 0000000..cb39804 --- /dev/null +++ b/api/src/main/java/jakarta/annotation/Resource.java
@@ -0,0 +1,119 @@ +/* + * Copyright (c) 2005, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation; + +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * The <code>Resource</code> annotation marks a resource that is needed + * by the application. This annotation may be applied to an + * application component class, or to fields or methods of the + * component class. When the annotation is applied to a + * field or method, the container will inject an instance + * of the requested resource into the application component + * when the component is initialized. If the annotation is + * applied to the component class, the annotation declares a + * resource that the application will look up at runtime. + * <p> + * Even though this annotation is not marked <code>Inherited</code>, deployment + * tools are required to examine all superclasses of any component + * class to discover all uses of this annotation in all superclasses. + * All such annotation instances specify resources that are needed + * by the application component. Note that this annotation may + * appear on private fields and methods of superclasses; the container + * is required to perform injection in these cases as well.</p> + * + * @since 1.6, Common Annotations 1.0 + */ +@Target({TYPE, FIELD, METHOD}) +@Retention(RUNTIME) +@Repeatable(Resources.class) +public @interface Resource { + /** + * The JNDI name of the resource. For field annotations, + * the default is the field name. For method annotations, + * the default is the JavaBeans property name corresponding + * to the method. For class annotations, there is no default + * and this must be specified. + */ + String name() default ""; + + /** + * The name of the resource that the reference points to. It can + * link to any compatible resource using the global JNDI names. + * + * @since 1.7, Common Annotations 1.1 + */ + + String lookup() default ""; + + /** + * The Java type of the resource. For field annotations, + * the default is the type of the field. For method annotations, + * the default is the type of the JavaBeans property. + * For class annotations, there is no default and this must be + * specified. + */ + Class<?> type() default java.lang.Object.class; + + /** + * The two possible authentication types for a resource. + */ + enum AuthenticationType { + CONTAINER, + APPLICATION + } + + /** + * The authentication type to use for this resource. + * This may be specified for resources representing a + * connection factory of any supported type, and must + * not be specified for resources of other types. + */ + AuthenticationType authenticationType() default AuthenticationType.CONTAINER; + + /** + * Indicates whether this resource can be shared between + * this component and other components. + * This may be specified for resources representing a + * connection factory of any supported type, and must + * not be specified for resources of other types. + */ + boolean shareable() default true; + + /** + * A product-specific name that this resource should be mapped to. + * The <code>mappedName</code> element provides for mapping the + * resource reference to the name of a resource known to the + * applicaiton server. The mapped name could be of any form. + * <p>Application servers are not required to support any particular + * form or type of mapped name, nor the ability to use mapped names. + * The mapped name is product-dependent and often installation-dependent. + * No use of a mapped name is portable.</p> + */ + String mappedName() default ""; + + /** + * Description of this resource. The description is expected + * to be in the default language of the system on which the + * application is deployed. The description can be presented + * to the Deployer to help in choosing the correct resource. + */ + String description() default ""; +}
diff --git a/api/src/main/java/jakarta/annotation/Resources.java b/api/src/main/java/jakarta/annotation/Resources.java new file mode 100644 index 0000000..eaa2d4c --- /dev/null +++ b/api/src/main/java/jakarta/annotation/Resources.java
@@ -0,0 +1,37 @@ +/* + * Copyright (c) 2005, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation; +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * This class is used to allow multiple resources declarations. + * + * @see jakarta.annotation.Resource + * @since 1.6, Common Annotations 1.0 + */ + +@Documented +@Retention(RUNTIME) +@Target(TYPE) +public @interface Resources { + /** + * Array used for multiple resource declarations. + */ + Resource[] value(); +}
diff --git a/api/src/main/java/jakarta/annotation/package-info.java b/api/src/main/java/jakarta/annotation/package-info.java new file mode 100644 index 0000000..f108b8c --- /dev/null +++ b/api/src/main/java/jakarta/annotation/package-info.java
@@ -0,0 +1,20 @@ +/* + * Copyright (c) 2018, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +/** + * This package defines the common annotations. + */ +package jakarta.annotation;
diff --git a/api/src/main/java/jakarta/annotation/security/DeclareRoles.java b/api/src/main/java/jakarta/annotation/security/DeclareRoles.java new file mode 100644 index 0000000..36c1ce8 --- /dev/null +++ b/api/src/main/java/jakarta/annotation/security/DeclareRoles.java
@@ -0,0 +1,37 @@ +/* + * Copyright (c) 2005, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation.security; +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * Used by application to declare security roles. It can be + * specified on a class. The value of the <code>DeclareRoles</code> + * annotation is a list of security role names. + * + * @since Common Annotations 1.0 + */ +@Documented +@Retention (RUNTIME) +@Target(TYPE) +public @interface DeclareRoles { + /** + * List of security role names. + */ + String[] value(); +}
diff --git a/api/src/main/java/jakarta/annotation/security/DenyAll.java b/api/src/main/java/jakarta/annotation/security/DenyAll.java new file mode 100644 index 0000000..e32a7e1 --- /dev/null +++ b/api/src/main/java/jakarta/annotation/security/DenyAll.java
@@ -0,0 +1,34 @@ +/* + * Copyright (c) 2005, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation.security; +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * Specifies that no security roles are allowed to invoke the specified + * method(s). + * + * @see jakarta.annotation.security.RolesAllowed + * @see jakarta.annotation.security.PermitAll + * @since Common Annotations 1.0 + */ +@Documented +@Retention (RUNTIME) +@Target({TYPE, METHOD}) +public @interface DenyAll { +}
diff --git a/api/src/main/java/jakarta/annotation/security/PermitAll.java b/api/src/main/java/jakarta/annotation/security/PermitAll.java new file mode 100644 index 0000000..256bee9 --- /dev/null +++ b/api/src/main/java/jakarta/annotation/security/PermitAll.java
@@ -0,0 +1,42 @@ +/* + * Copyright (c) 2005, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation.security; +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * Specifies that all security roles are allowed to invoke the specified + * method(s) — i.e., that the specified method(s) are "unchecked". + * It can be specified on a class or on methods. Specifying it on the class + * means that it applies to all methods of the class. If specified at the + * method level, it only affects that method. If the <code>RolesAllowed</code> + * annotation is specified at the class level and this annotation is + * applied at the method level, the <code>PermitAll</code> + * annotation overrides the <code>RolesAllowed</code> annotation for + * the specified method. + * + * @see jakarta.annotation.security.RolesAllowed + * @see jakarta.annotation.security.DenyAll + * + * @since Common Annotations 1.0 + */ +@Documented +@Retention (RUNTIME) +@Target({TYPE, METHOD}) +public @interface PermitAll { +}
diff --git a/api/src/main/java/jakarta/annotation/security/RolesAllowed.java b/api/src/main/java/jakarta/annotation/security/RolesAllowed.java new file mode 100644 index 0000000..9c717de --- /dev/null +++ b/api/src/main/java/jakarta/annotation/security/RolesAllowed.java
@@ -0,0 +1,42 @@ +/* + * Copyright (c) 2005, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation.security; +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * Specifies the list of security roles permitted to access method(s) in an + * application. The value of the <code>RolesAllowed</code> annotation + * is a list of security role names. + * This annotation can be specified on a class or on method(s). Specifying it + * at a class level means that it applies to all the methods in the class. + * Specifying it on a method means that it is applicable to that method only. + * If applied at both the class and methods level, the method value overrides + * the class value if the two conflict. + * + * @since Common Annotations 1.0 + */ +@Documented +@Retention (RUNTIME) +@Target({TYPE, METHOD}) +public @interface RolesAllowed { + /** + * List of roles that are permitted access. + */ + String[] value(); +}
diff --git a/api/src/main/java/jakarta/annotation/security/RunAs.java b/api/src/main/java/jakarta/annotation/security/RunAs.java new file mode 100644 index 0000000..5a744eb --- /dev/null +++ b/api/src/main/java/jakarta/annotation/security/RunAs.java
@@ -0,0 +1,38 @@ +/* + * Copyright (c) 2005, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation.security; +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * Defines the identity of the application during execution. + * This allows developers to execute an application under a particular role. + * The role must map to the user / group information in the container's + * security realm. Its value is the name of a security role. + * + * @since Common Annotations 1.0 + */ +@Documented +@Retention (RUNTIME) +@Target(TYPE) +public @interface RunAs { + /** + * Name of a security role. + */ + String value(); +}
diff --git a/api/src/main/java/jakarta/annotation/security/package-info.java b/api/src/main/java/jakarta/annotation/security/package-info.java new file mode 100644 index 0000000..7482fd3 --- /dev/null +++ b/api/src/main/java/jakarta/annotation/security/package-info.java
@@ -0,0 +1,20 @@ +/* + * Copyright (c) 2018, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +/** + * This package contains the security common annotations. + */ +package jakarta.annotation.security;
diff --git a/api/src/main/java/jakarta/annotation/sql/DataSourceDefinition.java b/api/src/main/java/jakarta/annotation/sql/DataSourceDefinition.java new file mode 100644 index 0000000..845e48c --- /dev/null +++ b/api/src/main/java/jakarta/annotation/sql/DataSourceDefinition.java
@@ -0,0 +1,313 @@ +/* + * Copyright (c) 2009, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation.sql; + +import java.lang.annotation.*; +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import java.lang.annotation.ElementType; +import java.lang.annotation.RetentionPolicy; + +/** + * Annotation used to define a container <code>DataSource</code> to + * be registered with JNDI. The <code>DataSource</code> may be configured by + * setting the annotation elements for commonly used <code>DataSource</code> + * properties. Additional standard and vendor-specific properties may be + * specified using the <code>properties</code> element. + * <p> + * + * The data source will be registered under the name specified in the + * <code>name</code> element. It may be defined to be in any valid + * Jakarta EE namespace, which will determine the accessibility of + * the data source from other components. + * <p> + * A JDBC driver implementation class of the appropriate type, either + * <code>DataSource</code>, <code>ConnectionPoolDataSource</code>, or + * <code>XADataSource</code>, must be indicated by the <code>className</code> + * element. The availability of the driver class will be assumed at runtime. + *<p> + * DataSource properties should not be specified more than once. If + * the url annotation element contains a DataSource property that was also + * specified using the corresponding annotation element or was specified in + * the properties annotation element, the precedence order is undefined + * and implementation specific: + * <p> + * <pre> + * @DataSourceDefinition(name="java:global/MyApp/MyDataSource", + * className="org.apache.derby.jdbc.ClientDataSource", + * url="jdbc:derby://localhost:1527/myDB;user=bill", + * user="lance", + * password="secret", + * databaseName="testDB", + * serverName="luckydog" + * )// DO NOT DO THIS!!! + * </pre> + * <p> + * In the above example, the <code>databaseName</code>, <code>user</code> + * and <code>serverName</code> properties were specified as part of the + * <code>url</code> property and using the corresponding + * annotation elements. This should be avoided. + * <p> + * If the <code>properties</code> annotation element is used and contains a + * DataSource property that was also specified using the corresponding + * annotation element, the annotation element value takes precedence. + * For example: + * <p> + * <pre> + * @DataSourceDefinition(name="java:global/MyApp/MyDataSource", + * className="org.apache.derby.jdbc.ClientDataSource", + * user="lance", + * password="secret", + * databaseName="testDB", + * serverName="luckydog", + * properties= {"databaseName=myDB", "databaseProp=doThis"} + * )// DO NOT DO THIS!!! + * </pre> + * <p> + * This would result in the following values being used when configuring + * the DataSource: + * <ul> + * <li>serverName=luckydog</li> + * <li>portNumber=1527</li> + * <li>databaseName=testDB</li> + * <li>user=lance</li> + * <li>password=secret</li> + * <li>databaseProp=doThis</li> + * </ul> + * <p> + * Vendors are not required to support properties that do not normally + * apply to a specific data source type. For example, specifying the + * <code>transactional</code> property to be <code>true</code> but supplying + * a value for <code>className</code> that implements a data source class + * other than <code>XADataSource</code> may not be supported. + * <p> + * Vendor-specific properties may be combined with or used to + * override standard data source properties defined using this annotation. + * <p> + * <code>DataSource</code> properties that are specified and are not supported + * in a given configuration or cannot be mapped to a vendor specific + * configuration property may be ignored. + * <p> + * Examples: + * <br> + * <pre> + * @DataSourceDefinition(name="java:global/MyApp/MyDataSource", + * className="com.foobar.MyDataSource", + * portNumber=6689, + * serverName="myserver.com", + * user="lance", + * password="secret" + * ) + * + * </pre> + * <p> + * Using a <code>URL</code>: + * <br> + * <pre> + * @DataSourceDefinition(name="java:global/MyApp/MyDataSource", + * className="org.apache.derby.jdbc.ClientDataSource", + * url="jdbc:derby://localhost:1527/myDB", + * user="lance", + * password="secret" + * ) + * </pre> + * <p> + * An example lookup of the DataSource from an Jakarta Enterprise Beans: + * <pre> + * @Stateless + * public class MyStatelessEJB { + * @Resource(lookup="java:global/MyApp/myDataSource") + * DataSource myDB; + * ... + * } + * </pre> + * <p> + * @see javax.sql.DataSource + * @see javax.sql.XADataSource + * @see javax.sql.ConnectionPoolDataSource + * @since Common Annotations 1.1 + */ +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +@Repeatable(DataSourceDefinitions.class) +public @interface DataSourceDefinition { + + /** + * JNDI name by which the data source will be registered. + * @since 1.1 + */ + String name(); + + /** + * Name of a DataSource class that implements + * <code>javax.sql.DataSource</code> or <code>javax.sql.XADataSource</code> + * or <code>javax.sql.ConnectionPoolDataSource</code>. + * @since 1.1 + */ + String className(); + + /** + * Description of this data source + * @since 1.1 + */ + String description() default ""; + + /** + * A JDBC URL. If the <code>url</code> annotation element contains a + * DataSource property that was also specified using the corresponding + * annotation element, the precedence order is undefined and + * implementation specific. + * @since 1.1 + */ + String url() default ""; + + /** + * User name to use for connection authentication. + * @since 1.1 + */ + String user() default ""; + + /** + * Password to use for connection authentication. + * @since 1.1 + */ + String password() default ""; + + /** + * Name of a database on a server. + * @since 1.1 + */ + String databaseName() default ""; + + /** + * Port number where a server is listening for requests. + * @since 1.1 + */ + int portNumber() default -1; + + /** + * Database server name. + * @since 1.1 + */ + String serverName() default "localhost"; + + /** + * Isolation level for connections. The Isolation level + * must be one of the following: + * <p> + * <ul> + * <li>Connection.TRANSACTION_NONE, + * <li>Connection.TRANSACTION_READ_ UNCOMMITTED, + * <li>Connection.TRANSACTION_READ_COMMITTED, + * <li>Connection.TRANSACTION_REPEATABLE_READ, + * <li>Connection.TRANSACTION_SERIALIZABLE + *</ul> + * <p> + * Default is vendor-specific. + * @since 1.1 + */ + int isolationLevel() default -1; + + /** + * Set to <code>false</code> if connections should not participate + * in transactions. + * <p> + * Default is to enlist in a transaction when one is active or becomes + * active. + * @since 1.1 + */ + boolean transactional() default true; + + /** + * Number of connections that should be created when a connection pool + * is initialized. + * <p> + * Default is vendor-specific + * @since 1.1 + */ + int initialPoolSize() default -1; + + /** + * Maximum number of connections that should be concurrently allocated for a + * connection pool. + * <p> + * Default is vendor-specific. + * @since 1.1 + */ + int maxPoolSize() default -1; + + /** + * Minimum number of connections that should be allocated for a + * connection pool. + * <p> + * Default is vendor-specific. + * @since 1.1 + */ + int minPoolSize() default -1; + + /** + * The number of seconds that a physical connection + * should remain unused in the pool before the + * connection is closed for a connection pool. + * <p> + * Default is vendor-specific + * @since 1.1 + */ + int maxIdleTime() default -1; + + /** + * The total number of statements that a connection pool should keep open. + * A value of 0 indicates that the caching of statements is disabled for + * a connection pool. + * <p> + * Default is vendor-specific + * @since 1.1 + */ + int maxStatements() default -1; + /** + * Used to specify vendor-specific properties and less commonly + * used <code>DataSource</code> properties such as: + * <p> + * <ul> + * <li>dataSourceName + * <li>networkProtocol + * <li>propertyCycle + * <li>roleName + * </ul> + * <p> + * Properties are specified using the format: + * <i>propertyName=propertyValue</i> with one property per array element. + * <p> + * If a DataSource property is specified in the <code>properties</code> + * element and the annotation element for the property is also + * specified, the annotation element value takes precedence. + * @since 1.1 + */ + String[] properties() default {}; + + + /** + * Sets the maximum time in seconds that this data source will wait while + * attempting to connect to a database. A value of zero specifies that + * the timeout is the default system timeout if there is one; otherwise, + * it specifies that there is no timeout. + * <p> + * Default is vendor-specific. + * @since 1.1 + */ + int loginTimeout() default 0; +}
diff --git a/api/src/main/java/jakarta/annotation/sql/DataSourceDefinitions.java b/api/src/main/java/jakarta/annotation/sql/DataSourceDefinitions.java new file mode 100644 index 0000000..cd9bfa9 --- /dev/null +++ b/api/src/main/java/jakarta/annotation/sql/DataSourceDefinitions.java
@@ -0,0 +1,35 @@ +/* + * Copyright (c) 2009, 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + +package jakarta.annotation.sql; + +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import java.lang.annotation.ElementType; +import java.lang.annotation.RetentionPolicy; + +/** + * Declares one or more <code>DataSourceDefinition</code> annotations. + * + * @see jakarta.annotation.sql.DataSourceDefinition + * @since Common Annotations 1.1 + */ +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +public @interface DataSourceDefinitions { + DataSourceDefinition[] value (); + +}
diff --git a/api/src/main/java/module-info.java b/api/src/main/java/module-info.java new file mode 100644 index 0000000..ce87894 --- /dev/null +++ b/api/src/main/java/module-info.java
@@ -0,0 +1,24 @@ +/* + * Copyright (c) 2020 Oracle and/or its affiliates. All rights reserved. + * + * This program and the accompanying materials are made available under the + * terms of the Eclipse Public License v. 2.0, which is available at + * http://www.eclipse.org/legal/epl-2.0. + * + * This Source Code may also be made available under the following Secondary + * Licenses when the conditions for such availability set forth in the + * Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + * version 2 with the GNU Classpath Exception, which is available at + * https://www.gnu.org/software/classpath/license.html. + * + * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + */ + + +module jakarta.annotation { + + exports jakarta.annotation; + exports jakarta.annotation.security; + exports jakarta.annotation.sql; + +}
diff --git a/api/src/main/javadoc/doc-files/EFSL.html b/api/src/main/javadoc/doc-files/EFSL.html new file mode 100644 index 0000000..4a2cd9b --- /dev/null +++ b/api/src/main/javadoc/doc-files/EFSL.html
@@ -0,0 +1,90 @@ +<html> +<head> +<!-- + + Copyright (c) 2020 Oracle and/or its affiliates. All rights reserved. + + This program and the accompanying materials are made available under the + terms of the Eclipse Public License v. 2.0, which is available at + http://www.eclipse.org/legal/epl-2.0. + + This Source Code may also be made available under the following Secondary + Licenses when the conditions for such availability set forth in the + Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + version 2 with the GNU Classpath Exception, which is available at + https://www.gnu.org/software/classpath/license.html. + + SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + +--> + +<title>Eclipse Foundation Specification License - v1.0</title> +</head> +<body> +<h1>Eclipse Foundation Specification License - v1.0</h1> +<p>By using and/or copying this document, or the Eclipse Foundation + document from which this statement is linked, you (the licensee) agree + that you have read, understood, and will comply with the following + terms and conditions:</p> + +<p>Permission to copy, and distribute the contents of this document, or + the Eclipse Foundation document from which this statement is linked, in + any medium for any purpose and without fee or royalty is hereby + granted, provided that you include the following on ALL copies of the + document, or portions thereof, that you use:</p> + +<ul> + <li> link or URL to the original Eclipse Foundation document.</li> + <li>All existing copyright notices, or if one does not exist, a notice + (hypertext is preferred, but a textual representation is permitted) + of the form: "Copyright © [$date-of-document] + “Eclipse Foundation, Inc. <<url to this license>> + " + </li> +</ul> + +<p>Inclusion of the full text of this NOTICE must be provided. We + request that authorship attribution be provided in any software, + documents, or other items or products that you create pursuant to the + implementation of the contents of this document, or any portion + thereof.</p> + +<p>No right to create modifications or derivatives of Eclipse Foundation + documents is granted pursuant to this license, except anyone may + prepare and distribute derivative works and portions of this document + in software that implements the specification, in supporting materials + accompanying such software, and in documentation of such software, + PROVIDED that all such works include the notice below. HOWEVER, the + publication of derivative works of this document for use as a technical + specification is expressly prohibited.</p> + +<p>The notice is:</p> + +<p>"Copyright © 2018 Eclipse Foundation. This software or + document includes material copied from or derived from [title and URI + of the Eclipse Foundation specification document]."</p> + +<h2>Disclaimers</h2> + +<p>THIS DOCUMENT IS PROVIDED "AS IS," AND THE COPYRIGHT + HOLDERS AND THE ECLIPSE FOUNDATION MAKE NO REPRESENTATIONS OR + WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, + NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE + SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS + WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR + OTHER RIGHTS.</p> + +<p>THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION WILL NOT BE LIABLE + FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT + OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE + CONTENTS THEREOF.</p> + +<p>The name and trademarks of the copyright holders or the Eclipse + Foundation may NOT be used in advertising or publicity pertaining to + this document or its contents without specific, written prior + permission. Title to copyright in this document will at all times + remain with copyright holders.</p> + +</body> +</html>
diff --git a/spec/README.md b/spec/README.md new file mode 100644 index 0000000..b42636f --- /dev/null +++ b/spec/README.md
@@ -0,0 +1,26 @@ +Jakarta Annotations Specification +============================ + +This project generates the Jakarta Annotations Specification. + +Building +-------- + +Prerequisites: + +* JDK8+ +* Maven 3.0.3+ + +Run the full build: + +`mvn install` + +Generate specification with given status (ex. "Final Release"): + +`mvn clean install -Dstatus="Final Release"` + +Locate the html files: +- `target/generated-docs/annotations-spec-<version>.html` + +Locate the PDF files: +- `target/generated-docs/annotations-spec-<version>.pdf`
diff --git a/spec/assembly.xml b/spec/assembly.xml new file mode 100644 index 0000000..3ab0450 --- /dev/null +++ b/spec/assembly.xml
@@ -0,0 +1,32 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- + + Copyright (c) 2019 Contributors to the Eclipse Foundation. + + This program and the accompanying materials are made available under the + terms of the Eclipse Public License v. 2.0, which is available at + http://www.eclipse.org/legal/epl-2.0. + + This Source Code may also be made available under the following Secondary + Licenses when the conditions for such availability set forth in the + Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + version 2 with the GNU Classpath Exception, which is available at + https://www.gnu.org/software/classpath/license.html. + + SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + +--> + +<assembly> + <id>spec</id> + <formats> + <format>zip</format> + </formats> + <baseDirectory>annotations-spec</baseDirectory> + <fileSets> + <fileSet> + <directory>target/generated-docs</directory> + <outputDirectory></outputDirectory> + </fileSet> + </fileSets> +</assembly>
diff --git a/spec/pom.xml b/spec/pom.xml new file mode 100644 index 0000000..15ef070 --- /dev/null +++ b/spec/pom.xml
@@ -0,0 +1,190 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + + Copyright (c) 2019, 2020 Contributors to the Eclipse Foundation. + + This program and the accompanying materials are made available under the + terms of the Eclipse Public License v. 2.0, which is available at + http://www.eclipse.org/legal/epl-2.0. + + This Source Code may also be made available under the following Secondary + Licenses when the conditions for such availability set forth in the + Eclipse Public License v. 2.0 are satisfied: GNU General Public License, + version 2 with the GNU Classpath Exception, which is available at + https://www.gnu.org/software/classpath/license.html. + + SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0 + +--> + +<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> + <parent> + <groupId>org.eclipse.ee4j</groupId> + <artifactId>project</artifactId> + <version>1.0.6</version> + <relativePath/> + </parent> + + <modelVersion>4.0.0</modelVersion> + <artifactId>annotations-spec</artifactId> + <version>2.0-SNAPSHOT</version> + <packaging>pom</packaging> + + <name>Jakarta Annotations Specification</name> + <description>Jakarta Annotations Specification</description> + + <url>https://projects.eclipse.org/projects/ee4j.ca</url> + + <properties> + <site.output.dir>${project.build.directory}/staging</site.output.dir> + <maven.site.skip>true</maven.site.skip> + <asciidoctor.maven.plugin.version>2.0.0</asciidoctor.maven.plugin.version> + <asciidoctorj.pdf.version>1.5.3</asciidoctorj.pdf.version> + <!-- status: DRAFT, BETA, etc., or blank for final --> + <status>DRAFT</status> + <maven.build.timestamp.format>MMMM dd, yyyy</maven.build.timestamp.format> + <revisiondate>${maven.build.timestamp}</revisiondate> + </properties> + + <build> + <defaultGoal>package</defaultGoal> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-enforcer-plugin</artifactId> + <version>3.0.0-M3</version> + <executions> + <execution> + <id>enforce-versions</id> + <goals> + <goal>enforce</goal> + </goals> + <configuration> + <rules> + <requireJavaVersion> + <version>[1.8.0,)</version> + <message>You need JDK8 or higher</message> + </requireJavaVersion> + </rules> + </configuration> + </execution> + </executions> + </plugin> + <plugin> + <groupId>org.asciidoctor</groupId> + <artifactId>asciidoctor-maven-plugin</artifactId> + <version>${asciidoctor.maven.plugin.version}</version> + <dependencies> + <dependency> + <groupId>org.asciidoctor</groupId> + <artifactId>asciidoctorj-pdf</artifactId> + <version>${asciidoctorj.pdf.version}</version> + </dependency> + </dependencies> + <executions> + <execution> + <id>asciidoc-to-html</id> + <phase>generate-resources</phase> + <goals> + <goal>process-asciidoc</goal> + </goals> + <configuration> + <backend>html5</backend> + <outputFile>${project.build.directory}/generated-docs/annotations-spec-${project.version}.html</outputFile> + <attributes> + <doctype>book</doctype> + <status>${status}</status> + <data-uri /> + <icons>font</icons> + <toc>left</toc> + <icons>font</icons> + <sectanchors>true</sectanchors> + <idprefix /> + <idseparator>-</idseparator> + <docinfo1>true</docinfo1> + </attributes> + </configuration> + </execution> + <execution> + <id>asciidoc-to-pdf</id> + <phase>generate-resources</phase> + <goals> + <goal>process-asciidoc</goal> + </goals> + <configuration> + <backend>pdf</backend> + <outputFile>${project.build.directory}/generated-docs/annotations-spec-${project.version}.pdf</outputFile> + <attributes> + <pdf-stylesdir>${project.basedir}/src/main/theme</pdf-stylesdir> + <pdf-style>jakartaee</pdf-style> + <doctype>book</doctype> + <status>${status}</status> + <data-uri /> + <icons>font</icons> + <pagenums /> + <toc /> + <icons>font</icons> + <sectanchors>true</sectanchors> + <idprefix /> + <idseparator>-</idseparator> + <docinfo1>true</docinfo1> + <embedAssets>true</embedAssets> + </attributes> + </configuration> + </execution> + </executions> + <configuration> + <sourceDocumentName>annotations-spec.adoc</sourceDocumentName> + <sourceHighlighter>coderay</sourceHighlighter> + <attributes> + <revnumber>${project.version}</revnumber> + <revremark>${status}</revremark> + <revdate>${revisiondate}</revdate> + </attributes> + </configuration> + + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-release-plugin</artifactId> + <version>2.5.2</version> + <configuration> + <mavenExecutorId>forked-path</mavenExecutorId> + <useReleaseProfile>false</useReleaseProfile> + <arguments>${release.arguments}</arguments> + </configuration> + <dependencies> + <dependency> + <groupId>org.apache.maven.scm</groupId> + <artifactId>maven-scm-provider-gitexe</artifactId> + <version>1.9.4</version> + </dependency> + </dependencies> + </plugin> + + <!-- + This is the rule that builds the zip file for download. + --> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-assembly-plugin</artifactId> + <version>3.3.0</version> + <inherited>false</inherited> + <executions> + <execution> + <phase>package</phase> + <goals> + <goal>single</goal> + </goals> + <configuration> + <appendAssemblyId>false</appendAssemblyId> + <descriptors> + <descriptor>assembly.xml</descriptor> + </descriptors> + </configuration> + </execution> + </executions> + </plugin> + </plugins> + </build> +</project>
diff --git a/spec/src/main/asciidoc/annotations-spec.adoc b/spec/src/main/asciidoc/annotations-spec.adoc new file mode 100644 index 0000000..5a46c65 --- /dev/null +++ b/spec/src/main/asciidoc/annotations-spec.adoc
@@ -0,0 +1,32 @@ +// +// Copyright (c) 2017, 2020 Contributors to the Eclipse Foundation +// + += Jakarta Annotations +:authors: Jakarta Annotations Team, https://projects.eclipse.org/projects/ee4j.ca +:email: https://dev.eclipse.org/mailman/listinfo/ca-dev +:version-label!: +:doctype: book +:license: Eclipse Foundation Specification License v1.0 +:source-highlighter: coderay +:toc: left +:toclevels: 4 +:sectnumlevels: 4 +:sectanchors: +ifdef::backend-pdf[] +:pagenums: +:numbered: +:title-logo-image: image:images/jakarta_ee_logo_schooner_color_stacked_default.png[pdfwidth=4.25in,align=right] +endif::[] + +// == License +:sectnums!: +include::license-efsl.adoc[] + +// == Scope +:sectnums: +include::scope.adoc[] + +// == Spec +:sectnums: +include::spec.adoc[]
diff --git a/spec/src/main/asciidoc/images/annotations-10.png b/spec/src/main/asciidoc/images/annotations-10.png new file mode 100644 index 0000000..191893b --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-10.png Binary files differ
diff --git a/spec/src/main/asciidoc/images/annotations-3.png b/spec/src/main/asciidoc/images/annotations-3.png new file mode 100644 index 0000000..ae10fab --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-3.png Binary files differ
diff --git a/spec/src/main/asciidoc/images/annotations-4.png b/spec/src/main/asciidoc/images/annotations-4.png new file mode 100644 index 0000000..191893b --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-4.png Binary files differ
diff --git a/spec/src/main/asciidoc/images/annotations-5.png b/spec/src/main/asciidoc/images/annotations-5.png new file mode 100644 index 0000000..ef59b76 --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-5.png Binary files differ
diff --git a/spec/src/main/asciidoc/images/annotations-6.png b/spec/src/main/asciidoc/images/annotations-6.png new file mode 100644 index 0000000..ae10fab --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-6.png Binary files differ
diff --git a/spec/src/main/asciidoc/images/annotations-7.png b/spec/src/main/asciidoc/images/annotations-7.png new file mode 100644 index 0000000..191893b --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-7.png Binary files differ
diff --git a/spec/src/main/asciidoc/images/annotations-8.png b/spec/src/main/asciidoc/images/annotations-8.png new file mode 100644 index 0000000..ef59b76 --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-8.png Binary files differ
diff --git a/spec/src/main/asciidoc/images/annotations-9.png b/spec/src/main/asciidoc/images/annotations-9.png new file mode 100644 index 0000000..ae10fab --- /dev/null +++ b/spec/src/main/asciidoc/images/annotations-9.png Binary files differ
diff --git a/spec/src/main/asciidoc/images/jakarta_ee_logo_schooner_color_stacked_default.png b/spec/src/main/asciidoc/images/jakarta_ee_logo_schooner_color_stacked_default.png new file mode 100644 index 0000000..97b46ce --- /dev/null +++ b/spec/src/main/asciidoc/images/jakarta_ee_logo_schooner_color_stacked_default.png Binary files differ
diff --git a/spec/src/main/asciidoc/license-efsl.adoc b/spec/src/main/asciidoc/license-efsl.adoc new file mode 100644 index 0000000..2aa72e0 --- /dev/null +++ b/spec/src/main/asciidoc/license-efsl.adoc
@@ -0,0 +1,78 @@ +[subs="normal"] +.... +Specification: {doctitle} + +Version: {revnumber} + +ifeval::["{revremark}" != ""] +Status: {revremark} +endif::[] +ifeval::["{revremark}" == ""] +Status: Final Release +endif::[] + +Release: {revdate} +.... +Copyright (c) 2020 Eclipse Foundation. + +=== Eclipse Foundation Specification License + +By using and/or copying this document, or the Eclipse Foundation +document from which this statement is linked, you (the licensee) agree +that you have read, understood, and will comply with the following +terms and conditions: + +Permission to copy, and distribute the contents of this document, or +the Eclipse Foundation document from which this statement is linked, in +any medium for any purpose and without fee or royalty is hereby +granted, provided that you include the following on ALL copies of the +document, or portions thereof, that you use: + +* link or URL to the original Eclipse Foundation document. +* All existing copyright notices, or if one does not exist, a notice + (hypertext is preferred, but a textual representation is permitted) + of the form: "Copyright (c) [$date-of-document] + Eclipse Foundation, Inc. <<url to this license>>" + +Inclusion of the full text of this NOTICE must be provided. We +request that authorship attribution be provided in any software, +documents, or other items or products that you create pursuant to the +implementation of the contents of this document, or any portion +thereof. + +No right to create modifications or derivatives of Eclipse Foundation +documents is granted pursuant to this license, except anyone may +prepare and distribute derivative works and portions of this document +in software that implements the specification, in supporting materials +accompanying such software, and in documentation of such software, +PROVIDED that all such works include the notice below. HOWEVER, the +publication of derivative works of this document for use as a technical +specification is expressly prohibited. + +The notice is: + +"Copyright (c) 2018 Eclipse Foundation. This software or +document includes material copied from or derived from [title and URI +of the Eclipse Foundation specification document]." + +==== Disclaimers + +THIS DOCUMENT IS PROVIDED "AS IS," AND THE COPYRIGHT +HOLDERS AND THE ECLIPSE FOUNDATION MAKE NO REPRESENTATIONS OR +WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, +NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE +SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS +WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR +OTHER RIGHTS. + +THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION WILL NOT BE LIABLE +FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT +OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE +CONTENTS THEREOF. + +The name and trademarks of the copyright holders or the Eclipse +Foundation may NOT be used in advertising or publicity pertaining to +this document or its contents without specific, written prior +permission. Title to copyright in this document will at all times +remain with copyright holders.
diff --git a/spec/src/main/asciidoc/scope.adoc b/spec/src/main/asciidoc/scope.adoc new file mode 100644 index 0000000..6675b31 --- /dev/null +++ b/spec/src/main/asciidoc/scope.adoc
@@ -0,0 +1,3 @@ +== Specification Scope + +Jakarta Annotations defines a collection of annotations representing common semantic concepts that enable a declarative style of programming that applies across a variety of Java technologies.
diff --git a/spec/src/main/asciidoc/spec.adoc b/spec/src/main/asciidoc/spec.adoc new file mode 100644 index 0000000..07a5f8f --- /dev/null +++ b/spec/src/main/asciidoc/spec.adoc
@@ -0,0 +1,1196 @@ +== Introduction + +With the addition of JSR 175 (A Metadata +Facility for the JavaTM Programming Language) in the Java platform we +envision that various technologies will use annotations to enable a +declarative style of programming. It would be unfortunate if these +technologies each independently defined their own annotations for common +concepts. It would be valuable to have consistency within the Jakarta EE +and Java SE component technologies, but it will also be valuable to +allow consistency between Jakarta EE and Java SE. + +It is the intention of this specification to +define a small set of common annotations that will be available for use +within other specifications. It is hoped that this will help to avoid +unnecessary redundancy or duplication between annotations defined in +different Jakarta EE specifications. This would allow us to have +the common annotations all in one place and let the technologies refer +to this specification rather than have them specified in multiple +specifications. This way all technologies can use the same version of +the annotations and there will be consistency in the annotations used +across the platforms. + +=== Goals + +Define annotations for use in Jakarta EE: This +spec will define annotations for use within component technologies in +Jakarta EE as well as the platform as a whole. + +=== Non-Goals + +Support for Java versions prior to J2SE 5.0 + +Annotations were introduced in J2SE 5.0. It +is not possible to do annotation processing in versions prior to J2SE +5.0. It is not a goal of this specification to define a way of doing +annotation processing of any kind for versions prior to J2SE 5.0. + +=== Compatibility + +The annotations defined in this specification +may be included individually as needed in products that make use of +them. Other Java specifications will require support for subsets of +these annotations. Products that support these Java specifications must +include the required annotations. + +=== Conventions + +The keywords ‘MUST’, ‘MUST NOT’, ‘REQUIRED’, +‘SHALL’, ‘SHALL NOT’, ‘SHOULD’, ‘SHOULD NOT’, ‘RECOMMENDED’, ‘MAY’ AND +‘OPTIONAL’ in this document are to be interpreted as described in RFC +2119. + +Java code is formatted as shown below: + +[source,java] +---- +package com.wombat.hello; + +public class Hello { + public static void main(String[] args) { + System.out.println("Hello world"); + } +} +---- + +=== Expert Group Members + +The following expert group members +participated in JSR 250: + +- Cedric Beust (individual) +- Bill Burke (JBoss) +- Wayne Carr (Intel) +- Robert Clevenger (Oracle) +- Evan Ireland (Sybase) +- Woo Jin Kim (Tmax Soft) +- Gavin King (JBoss) +- Rajiv Mordani (Oracle Corporation, Specification lead) +- Ted Neward (individual) +- Anurag Parashar (Pramati technologies) +- Michael Santos (individual) +- Hani Suleiman (Ironflare AB) +- Seth White (BEA) + +=== Acknowledgements + +In addition to the expert group listed above, +Linda DeMichiel, Ron Monzillo, Lance Andersen and Bill Shannon all of +whom work at Oracle Corporation have provided input to this +specification. + +== Annotations + +This chapter describes the standard +annotations, some guidelines for annotation inheritance and the usage of +these annotations where possible. + +=== General Guidelines for Inheritance of Annotations + +The interplay of annotations and inheritance +in the Java language is potentially a source of complexity for +developers. Developers will rely on some implicit assumptions when +figuring out how annotations compose with other language features. At +the same time, annotation semantics are defined by individual +specifications, hence the potential for inconsistencies to arise. For +instance, consider the following example: + +[source,java] +---- +public class Base { + @TransactionAttribute(REQUIRES_NEW) + public void foo {...} +} + +@Stateless +public class Derived extends Base { + @TransactionAttribute(NEVER) + public void foo {...} +} +---- + +In keeping with the concept of method +overriding, most developers will assume that in the _Derived_ class, the +effective _TransactionAttribute_ annotation for method _foo_ is +_TransactionAttribute(NEVER)_ . On the other hand, it might have been +possible for the specification governing the semantics of the +_TransactionAttribute_ annotations type to require that the effective +_TransactionAttribute_ to be the most restrictive one in the whole +inheritance tree, that is, in the example above +_TransactionAttribute(REQUIRES_NEW)_ . A motivation for these semantics +might have been that the _foo_ method in the _Derived_ class may call +_super.foo()_ , resulting in the execution of some code that needs a +transaction to be in place. Such a choice on the part of the +specification for _TransactionAttribute_ would have contradicted a +developer’s intuition on how method overriding works. + +In order to keep the resulting complexity in +control, below are some guidelines recommended for how annotations +defined in the different specifications should interact with +inheritance: + +. Class-level annotations only affect the +class they annotate and its members, that is, its methods and fields. +They never affect a member declared by a superclass, even if it is not +hidden or overridden by the class in question. + +. In addition to affecting the annotated class, +class-level annotations may act as a shorthand for member-level +annotations. If a member carries a specific member-level annotation, any +annotations of the same type implied by a class-level annotation are +ignored. In other words, explicit member-level annotations have priority +over member-level annotations implied by a class-level annotation. For +example, a _TransactionAttribute(REQUIRED)_ annotation on a class +implies that all the public methods in the class that it is applied on +are annotated with _TransactionAttribute(REQUIRED)_ . However if there +is a _TransactionAttribute(NEVER)_ annotation on a particular method, +then the _TransactionAttribute(NEVER)_ applies for that particular +method and not _TransactionAttribute(REQUIRED)_ . + +. The interfaces implemented by a class never +contribute annotations to the class itself or any of its members. + +. Members inherited from a superclass and which +are not hidden or overridden maintain the annotations they had in the +class that declared them, including member-level annotations implied by +class-level ones. + +. Member-level annotations on a hidden or overridden member are always ignored. + +This set of guidelines guarantees that the +effects of an annotation are local to the class on, or inside, which it +appears. In order to find the effective annotation for a class member, a +developer has to track down its last non-hidden and non-overridden +declaration and examine it. If the sought-for annotation is not found +there, then (s)he will have to examine the enclosing class declaration. +If even this step fails to provide an annotation, no other source file +will be consulted. + +Below are some examples that explain how the +guidelines defined above will be applied to the _TransactionAttribute_ +annotation. + +[source,java] +---- +@TransactionAttribute(REQUIRED) +class Base { + @TransactionAttribute(NEVER) + public void foo() {...} + + public void bar() {...} +} + +@Stateless +class ABean extends Base { + public void foo() {...} +} + +@Stateless +public class BBean extends Base { + @TransactionAttribute(REQUIRES_NEW) + public void foo() {...} +} + +@Stateless +@TransactionAttribute(REQUIRES_NEW) +public class CBean extends Base { + public void foo() {...} + public void bar() {...} +} + +@Stateless +@TransactionAttribute(REQUIRES_NEW) +public class DBean extends Base { + public void bar() {...} +} + +@Stateless +@TransactionAttribute(REQUIRES_NEW) +public class EBean extends Base { + // ... +} +---- + +The table below shows the effective +_TransactionAttribute_ annotation in each of the cases above by applying +the guidelines specified for annotations and inheritance: + +|=== +|Methods in derived classes |Effective TransactionAttribute value +|foo() in ABean +|TransactionAttribute(REQUIRED). (Default TransactionAttribute as defined by the Jakarta Enterprise Beans specification). +|bar() in ABean +|TransactionAttribute(REQUIRED) +|foo() in BBean +|TransactionAttribute(REQUIRES_NEW) +|bar() in BBean +|TransactionAttribute(REQUIRED) +|foo() in CBean +|TransactionAttribute(REQUIRES_NEW) +|bar() in CBean +|TransactionAttribute(REQUIRES_NEW) +|foo() in DBean +|TransactionAttribute(NEVER) (from Base class) +|bar() in DBean +|TransactionAttribute(REQUIRES_NEW) +|foo() in EBean +|TransactionAttribute(NEVER) (from Base class) +|bar() in EBean +|TransactionAttribute(REQUIRED) (from Base class) +|=== + +For more details about the _TransactionAttribute_ annotation, see the _Jakarta Enterprise Beans Core Contracts_ +specification. + +All annotations defined in this specification +follow the guidelines defined above unless explicitly stated otherwise. + +=== jakarta.annotation.Generated + +The _Generated_ annotation is used to mark +source code that has been generated. It can be specified on a class, +method, or field. It can also be used to differentiate user-written code +from generated code in a single file. + +The _value_ element MUST have the name of the +code generator. The recommended convention is to use the fully qualified +name of the code generator. For example: _com.company.package.classname_ +. + +The _date_ element is used to indicate the +date the source was generated. The _date_ element MUST follow the ISO +8601 standard. For example the _date_ element could have the following +value: + + 2001-07-04T12:08:56.235-0700 + +which represents 2001-07-04 12:08:56 local +time in the U.S. Pacific time zone. + +The _comments_ element is a place holder for +any comments that the code generator may want to include in the +generated code. + +[source,java] +---- +package jakarta.annotation; + +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +@Target({ANNOTATION_TYPE, CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE}) +@Retention(SOURCE) +public @interface Generated { + String[] value(); + String date() default ""; + String comments() default ""; +} +---- + +|=== +|Element |Description |Default +|value |Name of the code generator | +|date |Date source was generated. MUST follow ISO 8601 standard |"" +|comments |placeholder for comments that the generator may want to include in the generated code |"" +|=== + +The following example shows the usage of the annotation defined above: + +[source,java] +---- +@Generated("com.sun.xml.rpc.AProcessor") +public interface StockQuoteService extends java.rmi.Remote { + this.context = context; +} +---- + +=== jakarta.annotation.Resource + +The _Resource_ annotation is used to declare +a reference to a resource. It can be specified on a class, method, or +field. When the annotation is applied on a field or method, the +container will inject an instance of the requested resource into the +application when the application is initialized. If the annotation is +applied to a class, the annotation declares a resource that the +application will look up at runtime. Even though this annotation is not +marked _Inherited_ , all superclasses MUST be examined to discover all +uses of this annotation. All such annotation instances specify resources +that are needed by the application. Note that this annotation may appear +on private fields and methods of superclasses. Injection of the declared +resources needs to happen in these cases as well, even if a method with +such an annotation is overridden by a subclass. + +The _name_ element is the JNDI name of the +resource. When the _Resource_ annotation is applied on a field, the +default value of the _name_ element is the field name qualified by the +class name. When applied on a method, the default is the JavaBeans +property name corresponding to the method qualified by the class name. +When applied on a class, there is no default and the name MUST be +specified. + +The _type_ element defines the Java type of +the resource. When the _Resource_ annotation is applied on a field, the +default value of the _type_ element is the type of the field. When +applied on a method, the default is the type of the JavaBeans property. +When applied on a class, there is no default and the type MUST be +specified. When used, the type MUST be assignment compatible. + +The _authenticationType_ element is used to +indicate the authentication type to use for the resource. It can take +one of two values defined as an _Enum_ : _CONTAINER_ or _APPLICATION_ . +This element may be specified for resources representing a connection +factory of any supported type and MUST NOT be specified for resources of +other types. + +The _shareable_ element is used to indicate +whether a resource can be shared between this component and other +components. This element may be specified for resources representing a +connection factory of any supported type or ORB object instances and +MUST NOT be specified for resources of other types. + +The _mappedName_ element is a +product-specific name that this resource should be mapped to. The +_mappedName_ element provides for mapping the resource reference +specified by the _Resource_ annotation to the name of a resource known +to the application server. The mapped name could be of any form. +Application servers are not required to support any particular form or +type of mapped name, nor the ability to use mapped names. The mapped +name is product dependent and often installation dependent. No use of +mapped name is portable. + +The _description_ element is the description +of the resource. The description is expected to be in the default +language of the system on which the application is deployed. The +description can be presented to help in choosing the correct resource. + +The _lookup_ element specifies the JNDI name +of a resource that the resource being defined will be bound to. The type +of the referenced resource must be compatible with that of the resource +being defined. + +[source,java] +---- +package jakarta.annotation; + +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +@Target({TYPE, METHOD, FIELD}) +@Retention(RUNTIME) +@Repeatable(Resources.class) +public @interface Resource { + public enum AuthenticationType { + CONTAINER, + APPLICATION + } + + String name() default ""; + + Class<?> type() default Object.class; + + AuthenticationType authenticationType() default AuthenticationType.CONTAINER; + + boolean shareable() default true; + + String mappedName() default ""; + + String description() default ""; + + String lookup() default ""; +} +---- + + +|=== +|Element |Description |Default +|name |The JNDI name of the resource |"" +|type |The Java type of the resource |Object.class +|authenticationType |The authentication type to use for the resource |CONTAINER +|shareable |Indicates whether the resource can be shared. |true +|mappedName |A product-specific name that the resource should map to. |"" +|description |Description of the resource. |"" +|lookup |the JNDI name of a resource that the resource being defined will be bound to |"" +|=== + +==== Field based injection + +To access a resource a developer declares a +field and annotates it as being a resource reference. If the name and +type elements are missing from the annotation they will be inferred by +looking at the field declaration itself. It is an error if the type +specified by the _Resource_ annotation and the type of the field are +incompatible. + +For example: + +[source,java] +---- +@Resource +private DataSource myDB; +---- + +In the example above the effective name is +_com.example.class/myDB_ and the effective type is +_javax.sql.DataSource.class_ . + +[source,java] +---- +@Resource(name="customerDB") +private DataSource myDB; +---- + +In the example above the name is _customerDB_ +and the effective type is _javax.sql.DataSource.class_ . + +==== Setter based injection + +To access a resource a developer declares a +setter method and annotates it as being a resource reference. The name +and type of resource may be inferred by inspecting the method +declaration if necessary. The name of the resource, if not declared, is +the name of the JavaBeans property as determined from the name of the +setter method. The setter method MUST follow the standard JavaBeans +convention—the name starts with “ _set_ ”; the return type is _void_ ; +and there is only one parameter. Additionally, the type of the parameter +MUST be compatible with the _type_ element of the _Resource_ annotation, +if specified. + +For example: + +[source,java] +---- +@Resource +private void setMyDB(DataSource ds) { + myDB = ds; +} + +private DataSource myDB; +---- + +In the example above the effective name is +_com.example.class/myDB_ and the type is _javax.sql.DataSource.class_ . + +[source,java] +---- +@Resource(name="customerDB") +private void setMyDB(DataSource ds) { + myDB = ds; +} + +private DataSource myDB; +---- + +In the example above the name is _customerDB_ +and the type is _javax.sql.DataSource.class_ . + +The table below shows the mapping from Java +type to the equivalent resource type in the Jakarta EE 9 (and later) +deployment descriptors: + +[options="header"] +|=== +|Java Type |Equivalent Resource type +|java.lang.String |env-entry +|java.lang.Character |env-entry +|java.lang.Integer |env-entry +|java.lang.Boolean |env-entry +|java.lang.Double |env-entry +|java.lang.Byte |env-entry +|java.lang.Short |env-entry +|java.lang.Long |env-entry +|java.lang.Float |env-entry +|jakarta.xml.ws.Service |service-ref +|jakarta.jws.WebService |service-ref +|javax.sql.DataSource |resource-ref +|jakarta.jms.ConnectionFactory |resource-ref +|jakarta.jms.QueueConnectionFactory |resource-ref +|jakarta.jms.TopicConnectionFactory |resource-ref +|jakarta.mail.Session |resource-ref +|java.net.URL |resource-ref +|jakarta.resource.cci.ConnectionFactory |resource-ref +|any other connection factory defined by a resource adapter |resource-ref +|jakarta.jms.Queue |message-destination-ref +|jakarta.jms.Topic |message-destination-ref +|jakarta.resource.cci.InteractionSpec |resource-env-ref +|jakarta.transaction.UserTransaction |resource-env-ref +|Everything else |resource-env-ref +|=== + +=== jakarta.annotation.Resources + +The _Resource_ annotation is used to declare +a reference to a resource. The _Resources_ annotation acts as a +container for multiple resource declarations. + +[source,java] +---- +package jakarta.annotation; + +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +@Target({TYPE}) +@Retention(RUNTIME) +public @interface Resources { + Resource[] value; +} +---- + +|=== +|Element |Description |Default +|value |Container for defining multiple resources. | +|=== + +The following example shows the usage of the annotation defined above: + +[source,java] +---- +@Resources ({ + @Resource(name="myDB", type=javax.sql.DataSource), + @Resource(name="myMQ", type=jakarta.jms.ConnectionFactory) +}) + +public class CalculatorBean { + // ... +} +---- + +=== jakarta.annotation.PostConstruct + +The _PostConstruct_ annotation is used on a +method that needs to be executed after dependency injection is done to +perform any initialization. This method MUST be invoked before the class +is put into service. This annotation MUST be supported on all classes +that support dependency injection. The method annotated with +_PostConstruct_ MUST be invoked even if the class does not request any +resources to be injected. Only one method in a given class can be +annotated with this annotation. The method on which the _PostConstruct_ +annotation is applied MUST fulfill all of the following requirements, +except in cases where these requirements have been relaxed by another +specification. See in particular the _Jakarta Interceptors_ specification. + +- The method MUST NOT have any para meters. + +- The return type of the method MUST be _void_ . + +- The method MUST NOT throw a checked exception. + +- The method on which _PostConstruct_ is +applied MAY be _public_ , _protected_ , package private or _private_ . + +- The method MUST NOT be static except for the application client. + +- In general, the method MUST NOT be final. +However, other specifications are permitted to relax this requirement on +a per-component basis. + +- If the method throws an unchecked exception the class MUST NOT be put into service. + +[source,java] +---- +package jakarta.annotation; + +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +@Target(METHOD) +@Retention(RUNTIME) +public @interface PostConstruct { + +} +---- + +The following example shows the usage of the annotation defined above: + +[source,java] +---- +@Resource +private void setMyDB(DataSource ds) { + myDB = ds; +} + +@PostConstruct +private void initialize() { + // Initialize the connection object from the DataSource + connection = myDB.getConnection(); +} + +private DataSource myDB; +private Connection connection; +---- + + +=== jakarta.annotation.PreDestroy + +The _PreDestroy_ annotation is used on a +method as a callback notification to signal that the instance is in the +process of being removed by the container. The method annotated with +_PreDestroy_ is typically used to release resources that the instance +has been holding. This annotation MUST be supported by all container +managed objects that support _PostConstruct_ except the application +client. The method on which the _PreDestroy_ annotation is applied MUST +fulfill all of the following requirements, except in cases where these +requirements have been relaxed by another specification. See in +particular the _Jakarta Interceptors_ specification. + +- The method MUST NOT have any para meters. + +- The return type of the method MUST be _void_ . + +- The method MUST NOT throw a checked exception. + +- The method on which _PreDestroy_ is applied +MAY be _public_ , _protected_ , package private or _private_ . + +- The method MUST NOT be static. + +- In general, the method MUST NOT be final. +However, other specifications are permitted to relax this requirement on +a per-component basis. + +- If the method throws an unchecked exception it is ignored. + +[source,java] +---- +package jakarta.annotation; + +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +@Target(METHOD) +@Retention(RUNTIME) +public @interface PreDestroy { + +} +---- + +The following example shows the usage of the annotation defined above: + +[source,java] +---- +@Resource +private void setMyDB(DataSource ds) { + myDB = ds; +} + +@PostConstruct +private void initialize() { + // Initialize the connection object from the DataSource + connection = myDB.getConnection(); +} + +@PreDestroy +private void cleanup() { + // Close the connection to the DataSource. + connection.close(); +} + +private DataSource myDB; +private Connection connection; +---- + +=== jakarta.annotation.Priority + +The _Priority_ annotation can be applied to +classes or parameters to indicate in what order they should be used. The +effect of using the _Priority_ annotation in any particular instance is +defined by other specifications that define the use of a specific class. + +For example, the _Jakarta Interceptors_ specification +defines the use of priorities on interceptors to control the order in +which interceptors are called. + +Priority values should generally be +non-negative, with negative values reserved for special meanings such as +“undefined” or “not specified”. A specification that defines use of the +_Priority_ annotation may define the range of allowed priorities and any +priority values with special meaning. + +[source,java] +---- +package jakarta.annotation; + +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +@Target({TYPE, PARAMETER}) +@Retention(RUNTIME) +@Documented +public @interface Priority { + // The priority value. + int value(); +} +---- + +=== jakarta.annotation.security.RunAs + +The _RunAs_ annotation defines the security +role of the application during execution in a Jakarta EE container. It can +be specified on a class. This allows developers to execute an +application under a particular role. The role MUST map to the user / +group information in the container’s security realm. The _value_ element +in the annotation is the name of a security role. + +[source,java] +---- +package jakarta.annotation.security; + +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +@Target(TYPE) +@Retention(RUNTIME) +public @interface RunAs { + String value(); +} +---- + +|=== +|Element |Description |Default +|value |Security role of the application during execution in a Jakarta EE container | +|=== + +The following example shows the usage of the annotation defined above: + +[source,java] +---- +@RunAs("Admin") +public class Calculator { + // ... +} +---- + +=== jakarta.annotation.security.RolesAllowed + +The _RolesAllowed_ annotation specifies the +security roles permitted to access method(s) in an application. The +value element of the _RolesAllowed_ annotation is a list of security +role names. + +The _RolesAllowed_ annotation can be +specified on a class or on method(s). Specifying it at a class level +means that it applies to all the methods in the class. Specifying it on +a method means that it is applicable to that method only. If applied at +both the class and method level, the method value overrides the class +value. + +[source,java] +---- +package jakarta.annotation.security; + +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +@Target({TYPE,METHOD}) +@Retention(RUNTIME) +public @interface RolesAllowed { + String[] value(); +} +---- + +|=== +|Element |Description |Default +|value |List of roles permitted to access methods in the application | +|=== + +The following example shows the usage of the annotation defined above: + +[source,java] +---- +@RolesAllowed("Users") +public class Calculator { + @RolesAllowed("Administrator") + public void setNewRate(int rate) { + // ... + } +} +---- + +=== jakarta.annotation.security.PermitAll + +The _PermitAll_ annotation specifies that all +security roles are allowed to invoke the specified method(s), that is, +that the specified method(s) are “unchecked”. It can be specified on a +class or on methods. Specifying it on the class means that it applies to +all methods of the class. If specified at the method level, it only +affects that method. + +[source,java] +---- +package jakarta.annotation.security; + +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +@Target({TYPE,METHOD}) +@Retention(RUNTIME) +public @interface PermitAll { + +} +---- + +The following example shows the usage of the annotation defined above: + +[source,java] +---- +import jakarta.annotation.security.*; + +@RolesAllowed("Users") +public class Calculator { + @RolesAllowed("Administrator") + public void setNewRate(int rate) { + // ... + } + + @PermitAll + public long convertCurrency(long amount) { + // ... + } +} +---- + +=== jakarta.annotation.security.DenyAll + +The _DenyAll_ annotation specifies that no +security roles are allowed to invoke the specified method(s), that is, +that the method(s) are to be excluded from execution in the Jakarta EE +container. + +[source,java] +---- +package jakarta.annotation.security; + +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +@Target({TYPE, METHOD}) +@Retention(RUNTIME) +public @interface DenyAll { + +} +---- + +The following example shows the usage of the annotation defined above: + +[source,java] +---- +import jakarta.annotation.security.*; + +@RolesAllowed("Users") +public class Calculator { + @RolesAllowed("Administrator") + public void setNewRate(int rate) { + // ... + } + + @DenyAll + public long convertCurrency(long amount) { + // ... + } +} +---- + +=== PermitAll, DenyAll and RolesAllowed interactions + +The _PermitAll_ , _DenyAll_ and +_RolesAllowed_ annotations all define which security roles are allowed +to access the methods on which they are applied. This section describes +how these annotations interact and which usages of these annotations are +valid. + +If the _PermitAll_ , _DenyAll_ and +_RolesAllowed_ annotations are applied on methods of a class, then the +method level annotations take precedence (at the corresponding methods) +over any class level annotations of type _PermitAll_ , _DenyAll_ and +_RolesAllowed_ . + +=== jakarta.annotation.security.DeclareRoles + +The _DeclareRoles_ annotation is used to +specify security roles used by the application. It can be specified on a +class. It typically would be used to define roles that could be tested +(i.e., by calling _isUserInRole_ ) from within the methods of the +annotated class. It could also be used to declare roles that are not +implicitly declared as the result of their use in a _RolesAllowed_ +annotation on the class or a method of the class. + +[source,java] +---- +package jakarta.annotation.security; + +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +@Target(TYPE) +@Retention(RUNTIME) +public @interface DeclareRoles { + String[] value(); +} +---- + +|=== +|Element |Description |Default +|value |List of security roles specified by the application | +|=== + +The following example shows the usage of the annotation defined above: + +[source,java] +---- +@DeclareRoles("BusinessAdmin") +public class Calculator { + public void convertCurrency() { + if (x.isUserInRole("BusinessAdmin")) { + // ... + } + } + + // ... +} +---- + +=== jakarta.annotation.sql.DataSourceDefinition + +The _DataSourceDefinition_ annotation is used +to define a container _DataSource_ to be registered with JNDI. The +_DataSource_ may be configured by setting the annotation elements for +commonly-used _DataSource_ properties. Additional standard and +vendor-specific properties may be specified using the _properties_ +element. The data source will be registered under the name specified in +the _name_ element. It may be defined to be in any valid Jakarta EE +namespace, which will determine the accessibility of the data source +from other components. A JDBC driver implementation class of the +appropriate type, either _DataSource_ , _ConnectionPoolDataSource_ , or +_XADataSource_ , must be indicated by the _className_ element. The +driver class is not required to be available at deployment but must be +available at runtime prior to any attempt to access the _DataSource_ . + + _DataSource_ properties should not be +specified more than once. If the _url_ annotation element contains a +_DataSource_ property that was also specified using the corresponding +annotation element or was specified in the _properties_ annotation +element, the precedence order is undefined and implementation specific. + +Vendors are not required to support +_properties_ that do not normally apply to a specific data source type. +For example, specifying the _transactional_ property to be _true_ but +supplying a value for _className_ that implements a data source class +other than _XADataSource_ may not be supported. + +Vendor-specific properties may be combined +with or used to override standard data source properties defined using +this annotation. + +_DataSource_ properties that are specified +and are not supported in a given configuration or cannot be mapped to a +vendor-specific configuration property may be ignored. + +Although the annotation allows you to specify +a password, it is recommended not to embed passwords in production code. +The _password_ element in the annotation is provided as a convenience +for ease of development. + +[source,java] +---- +package jakarta.annotation.sql; + +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import java.lang.annotation.ElementType; +import java.lang.annotation.RetentionPolicy; + +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +@Repeatable(DataSourceDefinitions.class) +public @interface DataSourceDefinition { + String name(); + String className(); + String description() default ""; + String url() default ""; + String user() default ""; + String password() default ""; + String databaseName() default ""; + int portNumber() default -1; + String serverName() default "localhost"; + int isolationLevel() default -1; + boolean transactional() default true; + int initialPoolSize() default -1; + int maxPoolSize() default -1; + int minPoolSize() default -1; + int maxIdleTime() default -1; + int maxStatements() default -1; + String[] properties() default \{}; + int loginTimeout() default 0; +} +---- + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Element |Description |Default +| _name_ |JNDI name by which the data source will be registered | +| _className_ |DataSource implementation class name | +| _description_ |Description of the data source |"" +| _url_ |A JDBC URL. If the url annotation element contains a DataSource property that was also specified using the corresponding annotation element, the precedence order is undefined and implementation specific. |"" +| _user_ |User name for connection authentications |"" +| _password_ |Password for connection authentications |"" +| _databaseName_ |Name of a database on a server |"" +| _portNumber_ |Port number where a server is listening for requests |"" +| _serverName_ |Database server name |"localhost" +| _isolationLevel_ |Isolation level for connections. |-1 (vendor specific) +| _transactional_ |Indicates whether a connection is transactional or not |true +| _initialPoolSize_ |Number of connections that should be created when a connection pool is initialized |-1 (vendor specific) +| _maxPoolSize_ |Maximum number of connections that should be concurrently allocated for a connection pool |-1 (vendor specific) +| _minPoolSize_ |Minimum number of connections that should be allocated for a connection pool |-1 (vendor specific) +| _maxIdleTime_ |The number of seconds that a physical connection should remain unused in the pool before the connection is closed for a connection pool |-1 (vendor specific) +| _maxStatements_ |The total number of statements that a connection pool should keep open. A value of 0 indicates that the caching of statements is disabled for a connection pool |-1 (vendor specific) +| _properties_ |Used to specify vendor-specific properties and less commonly used _DataSource_ properties. If a _DataSource_ property is specified in the properties element and the annotation element for the property is also specified, the annotation element value takes precedence. |\{} +| _loginTimeout_ |The maximum time in seconds that this data source will wait while attempting to connect to a database. A value of 0 specifies that the timeout is the default system timeout if there is one, otherwise it specifies that there is no timeout |0 +|=== + +Examples: + +[source,java] +---- +@DataSourceDefinition( + name="java:global/MyApp/MyDataSource", + className="com.foobar.MyDataSource", + portNumber=6689, + serverName="myserver.com", + user="lance", + password="secret") + +---- + +Using a URL: + +[source,java] +---- +@DataSourceDefinition( + name="java:global/MyApp/MyDataSource", + className="org.apache.derby.jdbc.ClientDataSource", + url="jdbc:derby://localhost:1527/myDB", + user="lance", + password="secret") +---- + +=== jakarta.annotation.sql.DataSourceDefinitions + +The _DataSourceDefinition_ annotation is used +to declare a container _DataSource_ . The _DataSourceDefinitions_ +annotation acts as a container for multiple data source declarations. + +[source,java] +---- +package jakarta.annotation.sql; + +import java.lang.annotation.Target; +import java.lang.annotation.Retention; +import java.lang.annotation.ElementType; +import java.lang.annotation.RetentionPolicy; + +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +public @interface DataSourceDefinitions { + DataSourceDefinition[] value (); +} +---- + +|=== +|Element |Description |Default +|value |Container for defining multiple data sources. | +|=== + +The following example shows the usage of the annotation defined above: + +[source,java] +---- +@DataSourceDefinitions ({ + @DataSourceDefinition(name="java:global/MyApp/MyDataSource", + className="com.foobar.MyDataSource", + portNumber=6689, + serverName="myserver.com", + user="lance", + password="secret"), + + @DataSourceDefinition(name="java:global/MyApp/MyDataSource", + className="org.apache.derby.jdbc.ClientDataSource", + url="jdbc:derby://localhost:1527/myDB", + user="lance", + password="secret") +}) +public class CalculatorBean { + // ... +} +---- + +=== jakarta.annotation.ManagedBean + +The _ManagedBean_ annotation is used to +declare a Jakarta Managed Bean as specified in the _Jakarta Managed Beans_ +specification. Jakarta Managed Beans are container-managed objects that support +a small set of basic services such as resource injection, lifecycle +callbacks and interceptors. A Jakarta Managed Bean may optionally have a name, a +_String_ specified via the _value_ element. + +[source,java] +---- +package jakarta.annotation; + +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +@Target(TYPE) +@Retention(RUNTIME) +public @interface ManagedBean { + boolean value() default ""; +} +---- + +|=== +|Element |Description |Default +|value |Name of the Jakarta Managed Bean |"" +|=== + +Examples: + +[source,java] +---- +@ManagedBean("cart") +public class ShoppingCart { + // ... +} +---- + +== References + +JSR 175: A Metadata Facility for the Java +Programming Language. http://jcp.org/en/jsr/detail?id=175 + +Jakarta EE Platform 9 (Jakarta EE). +https://jakarta.ee/specifications/platform/9/ + +Java 2 Platform, Standard Edition, v5.0 +(J2SE). https://www.oracle.com/java/technologies/javase/j2se-v50.html + +Jakarta Enterprise Beans, v4.0. +https://jakarta.ee/specifications/enterprise-beans/4.0 + +Jakarta Interceptors, 2.0. +https://jakarta.ee/specifications/interceptors/2.0/ + +Jakarta Managed Beans. +https://jakarta.ee/specifications/managedbeans/2.0/ + +RFC 2119. +http://www.faqs.org/rfcs/rfc2119.html
diff --git a/spec/src/main/theme/jakartaee-theme.yml b/spec/src/main/theme/jakartaee-theme.yml new file mode 100644 index 0000000..6092a2f --- /dev/null +++ b/spec/src/main/theme/jakartaee-theme.yml
@@ -0,0 +1,299 @@ +# +# Following is the asciidoctor-pdf default theme [1], with small +# customizations, mostly for header and footer, marked "EE". +# +# [1] https://github.com/asciidoctor/asciidoctor-pdf/blob/master/data/themes/default-theme.yml +# +font: + catalog: + # Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols + Noto Serif: + normal: notoserif-regular-subset.ttf + bold: notoserif-bold-subset.ttf + italic: notoserif-italic-subset.ttf + bold_italic: notoserif-bold_italic-subset.ttf + # M+ 1mn supports ASCII and the circled numbers used for conums + M+ 1mn: + normal: mplus1mn-regular-ascii-conums.ttf + bold: mplus1mn-bold-ascii.ttf + italic: mplus1mn-italic-ascii.ttf + bold_italic: mplus1mn-bold_italic-ascii.ttf + # M+ 1p supports Latin, Latin-1 Supplement, Latin Extended, Greek, Cyrillic, Vietnamese, Japanese & an assortment of symbols + # It also provides arrows for ->, <-, => and <= replacements in case these glyphs are missing from font + M+ 1p Fallback: + normal: mplus1p-regular-fallback.ttf + bold: mplus1p-regular-fallback.ttf + italic: mplus1p-regular-fallback.ttf + bold_italic: mplus1p-regular-fallback.ttf + fallbacks: + - M+ 1p Fallback +page: + background_color: ffffff + layout: portrait + margin: [0.5in, 0.67in, 0.67in, 0.67in] + # margin_inner and margin_outer keys are used for recto/verso print margins when media=prepress + margin_inner: 0.75in + margin_outer: 0.59in + #size: A4 # EE + size: Letter # EE +base: + align: justify + # color as hex string (leading # is optional) + font_color: 333333 + # color as RGB array + #font_color: [51, 51, 51] + # color as CMYK array (approximated) + #font_color: [0, 0, 0, 0.92] + #font_color: [0, 0, 0, 92%] + font_family: Noto Serif + # choose one of these font_size/line_height_length combinations + #font_size: 14 + #line_height_length: 20 + #font_size: 11.25 + #line_height_length: 18 + #font_size: 11.2 + #line_height_length: 16 + font_size: 10.5 + #line_height_length: 15 + # correct line height for Noto Serif metrics + line_height_length: 12 + #font_size: 11.25 + #line_height_length: 18 + line_height: $base_line_height_length / $base_font_size + font_size_large: round($base_font_size * 1.25) + font_size_small: round($base_font_size * 0.85) + font_size_min: $base_font_size * 0.75 + font_style: normal + border_color: eeeeee + border_radius: 4 + border_width: 0.5 +# FIXME vertical_rhythm is weird; we should think in terms of ems +#vertical_rhythm: $base_line_height_length * 2 / 3 +# correct line height for Noto Serif metrics (comes with built-in line height) +vertical_rhythm: $base_line_height_length +horizontal_rhythm: $base_line_height_length +# QUESTION should vertical_spacing be block_spacing instead? +vertical_spacing: $vertical_rhythm +link: + font_color: 428bca +# literal is currently used for inline monospaced in prose and table cells +literal: + font_color: b12146 + font_family: M+ 1mn +menu_caret_content: " <font size=\"1.15em\"><color rgb=\"b12146\">\u203a</color></font> " +heading: + align: left + #font_color: 181818 + font_color: $base_font_color + font_family: $base_font_family + font_style: bold + # h1 is used for part titles (book doctype) or the doctitle (article doctype) + #h1_font_size: floor($base_font_size * 2.6) # EE + h1_font_size: floor($base_font_size * 2.5) # EE, squeeze title onto one line + # h2 is used for chapter titles (book doctype only) + h2_font_size: floor($base_font_size * 2.15) + h3_font_size: round($base_font_size * 1.7) + h4_font_size: $base_font_size_large + h5_font_size: $base_font_size + h6_font_size: $base_font_size_small + #line_height: 1.4 + # correct line height for Noto Serif metrics (comes with built-in line height) + line_height: 1 + margin_top: $vertical_rhythm * 0.4 + margin_bottom: $vertical_rhythm * 0.9 +title_page: + align: right + logo: + top: 10% + title: + top: 55% + font_size: $heading_h1_font_size + font_color: 999999 + line_height: 0.9 + subtitle: + font_size: $heading_h3_font_size + font_style: bold_italic + line_height: 1 + authors: + margin_top: $base_font_size * 1.25 + font_size: $base_font_size_large + font_color: 181818 + revision: + margin_top: $base_font_size * 1.25 +block: + margin_top: 0 + margin_bottom: $vertical_rhythm +caption: + align: left + font_size: $base_font_size * 0.95 + font_style: italic + # FIXME perhaps set line_height instead of / in addition to margins? + margin_inside: $vertical_rhythm / 3 + #margin_inside: $vertical_rhythm / 4 + margin_outside: 0 +lead: + font_size: $base_font_size_large + line_height: 1.4 +abstract: + font_color: 5c6266 + font_size: $lead_font_size + line_height: $lead_line_height + font_style: italic + first_line_font_style: bold + title: + align: center + font_color: $heading_font_color + font_family: $heading_font_family + font_size: $heading_h4_font_size + font_style: $heading_font_style +admonition: + column_rule_color: $base_border_color + column_rule_width: $base_border_width + padding: [0, $horizontal_rhythm, 0, $horizontal_rhythm] + #icon: + # tip: + # name: fa-lightbulb-o + # stroke_color: 111111 + # size: 24 + label: + text_transform: uppercase + font_style: bold +blockquote: + font_color: $base_font_color + font_size: $base_font_size_large + border_color: $base_border_color + border_width: 5 + # FIXME disable negative padding bottom once margin collapsing is implemented + padding: [0, $horizontal_rhythm, $block_margin_bottom * -0.75, $horizontal_rhythm + $blockquote_border_width / 2] + cite_font_size: $base_font_size_small + cite_font_color: 999999 +# code is used for source blocks (perhaps change to source or listing?) +code: + font_color: $base_font_color + font_family: $literal_font_family + font_size: ceil($base_font_size) + padding: $code_font_size + line_height: 1.25 + # line_gap is an experimental property to control how a background color is applied to an inline block element + line_gap: 3.8 + background_color: f5f5f5 + border_color: cccccc + border_radius: $base_border_radius + border_width: 0.75 +conum: + font_family: M+ 1mn + font_color: $literal_font_color + font_size: $base_font_size + line_height: 4 / 3 +example: + border_color: $base_border_color + border_radius: $base_border_radius + border_width: 0.75 + background_color: ffffff + # FIXME reenable padding bottom once margin collapsing is implemented + padding: [$vertical_rhythm, $horizontal_rhythm, 0, $horizontal_rhythm] +image: + align: left +prose: + margin_top: $block_margin_top + margin_bottom: $block_margin_bottom +sidebar: + background_color: eeeeee + border_color: e1e1e1 + border_radius: $base_border_radius + border_width: $base_border_width + # FIXME reenable padding bottom once margin collapsing is implemented + padding: [$vertical_rhythm, $vertical_rhythm * 1.25, 0, $vertical_rhythm * 1.25] + title: + align: center + font_color: $heading_font_color + font_family: $heading_font_family + font_size: $heading_h4_font_size + font_style: $heading_font_style +thematic_break: + border_color: $base_border_color + border_style: solid + border_width: $base_border_width + margin_top: $vertical_rhythm * 0.5 + margin_bottom: $vertical_rhythm * 1.5 +description_list: + term_font_style: bold + term_spacing: $vertical_rhythm / 4 + description_indent: $horizontal_rhythm * 1.25 +outline_list: + indent: $horizontal_rhythm * 1.5 + #marker_font_color: 404040 + # NOTE outline_list_item_spacing applies to list items that do not have complex content + item_spacing: $vertical_rhythm / 2 +table: + background_color: $page_background_color + #head_background_color: <hex value> + #head_font_color: $base_font_color + head_font_style: bold + #body_background_color: <hex value> + body_stripe_background_color: f9f9f9 + foot_background_color: f0f0f0 + border_color: dddddd + border_width: $base_border_width + cell_padding: 3 +toc: + indent: $horizontal_rhythm + line_height: 1.4 + dot_leader: + #content: ". " + font_color: a9a9a9 + #levels: 2 3 +# NOTE in addition to footer, header is also supported +footer: + font_size: $base_font_size_small + # NOTE if background_color is set, background and border will span width of page + #border_color: dddddd # EE + #border_width: 0.25 # EE + height: $base_line_height_length * 2.5 + line_height: 1 + padding: [$base_line_height_length / 2, 1, 0, 1] + vertical_align: top + #image_vertical_align: <alignment> or <number> + # additional attributes for content: + # * {page-count} + # * {page-number} + # * {document-title} + # * {document-subtitle} + # * {chapter-title} + # * {section-title} + # * {section-or-chapter-title} + recto: + #columns: "<50% =0% >50%" + right: + #content: '{page-number}' # EE + #content: '{section-or-chapter-title} | {page-number}' + #content: '{document-title} | {page-number}' + content: '{document-title}{nbsp}{nbsp}{nbsp} *{page-number}*' # EE + #center: + # content: '{page-number}' + left: # EE + content: '{status}' # EE + verso: + #columns: $footer_recto_columns + left: + #content: $footer_recto_right_content # EE + #content: '{page-number} | {chapter-title}' + content: '*{page-number}* {nbsp}{nbsp}{nbsp}{document-title}' # EE + #center: + # content: '{page-number}' + right: # EE + content: '{status}' # EE +header: # EE + font_size: $base_font_size_small # EE + border_color: dddddd # EE + border_width: 0.25 # EE + height: $base_line_height_length * 2.5 # EE + line_height: 1 # EE + padding: [$base_line_height_length / 2, 1, 0, 1] # EE + vertical_align: top # EE + recto: # EE + right: # EE + content: '{section-or-chapter-title}' # EE + verso: # EE + left: # EE + content: '{section-or-chapter-title}' # EE
