diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2bfebb6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,44 @@ +# Contributing to Eclipse Project for Common Annotations + +Thanks for your interest in this project. + +## Project description + +Annotations for common semantic concepts in the J2SE and J2EE platforms that +apply across a variety of individual 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 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. + + * + 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) + + 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..0279259 --- /dev/null +++ b/NOTICE.md @@ -0,0 +1,39 @@ +# Notices for Eclipse Project for Common Annotations + +This content is produced and maintained by the Eclipse Project for Common +Annotations project. + + * Project home: https://projects.eclipse.org/projects/ee4j.ca + +## Trademarks + +Eclipse Project for Common 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..d4398fa --- /dev/null +++ b/README.md @@ -0,0 +1,12 @@ +# Java(TM) Common Annotations + +The intention of Java(TM) Common Annotations is to develop annotations for common semantic +concepts in the Java SE and Java EE platforms that apply across a variety of individual +technologies. It was envisioned that various JSRs would use annotations to enable a declarative +style of programming. It would be especially valuable to have consistency within the Java EE +component JSRs, but it is also valuable to allow consistency between Java EE and Java SE. + +This standalone release of Java(TM) Common Annotations uses a +[Java Platform Module System](http://openjdk.java.net/projects/jigsaw/spec/) +"automatic" module name of `java.annotation`, to match the module name +used in JDK 9. A future version will include full module metadata. diff --git a/pom.xml b/pom.xml new file mode 100644 index 0000000..7d52921 --- /dev/null +++ b/pom.xml @@ -0,0 +1,309 @@ + + + + + 4.0.0 + + net.java + jvnet-parent + 3 + + + javax.annotation + javax.annotation-api + 1.3.3-SNAPSHOT + + + false + 1.3 + javax.annotation + javax.annotation-api + Oracle Corporation + org.glassfish + 2.3.1 + exclude.xml + Low + + ${extension.name} API + Common Annotations for the JavaTM Platform API + + http://jcp.org/en/jsr/detail?id=250 + + + + ldemichiel + Linda De Michiel + Oracle Corp. + + lead + + + + + + GlassFish Community + https://javaee.github.io/glassfish + + + + EPL 2.0 + http://www.eclipse.org/legal/epl-2.0 + repo + + + GPL2 w/ CPE + https://www.gnu.org/software/classpath/license.html + repo + + + + + scm:git:https://github.com/eclipse-ee4j/common-annotations-api.git + scm:git:git@github.com:eclipse-ee4j/common-annotations-api.git + https://github.com/eclipse-ee4j/common-annotations-api + HEAD + + + + + + src/main/java + + **/*.properties + **/*.html + + + + src/main/resources + + META-INF/README + + + + + + maven-compiler-plugin + 2.5.1 + + 1.8 + 1.8 + -Xlint:unchecked + + + + org.glassfish.build + spec-version-maven-plugin + 1.2 + + + ${non.final} + api + ${spec.build} + ${spec.version} + ${new.spec.version} + ${project.version} + ${extension.name} + + + + + + set-spec-properties + check-module + + + + + + org.apache.felix + maven-bundle-plugin + 1.4.3 + + + jar + + + ${spec.bundle.version} + ${spec.bundle.symbolic-name} + ${spec.extension.name} + ${spec.implementation.version} + ${spec.specification.version} + + Java(TM) Common Annotations ${spec.version} API Design Specification + + ${vendor.name} + ${project.organization.name} + ${implementation.vendor.id} + + + + + bundle-manifest + process-classes + + manifest + + + + + + org.apache.maven.plugins + maven-jar-plugin + 2.4 + + + ${project.build.outputDirectory}/META-INF/MANIFEST.MF + + + + java.annotation + + + + + **/*.java + + + + + org.apache.maven.plugins + maven-remote-resources-plugin + 1.2.1 + + + + process + + + + org.glassfish:legal:1.1 + + + + + + + org.apache.maven.plugins + maven-source-plugin + 2.1 + + true + + + + attach-sources + + jar-no-fork + + + + + + org.apache.maven.plugins + maven-javadoc-plugin + 2.8 + + + attach-javadocs + + jar + + + + javadoc + + javadoc + + + + + Common Annotations API Documentation + javax.annotation + + + +Oracle + and/or its affiliates. All Rights Reserved. + Use is subject to + license terms. +]]> + + + + + + + org.codehaus.mojo + findbugs-maven-plugin + ${findbugs.version} + + ${findbugs.threshold} + ${findbugs.exclude} + true + true + + + + org.apache.maven.plugins + maven-release-plugin + 2.5.3 + + forked-path + false + ${release.arguments} + @{project.version} + + + + org.apache.maven.plugins + maven-site-plugin + 3.1 + + + + + org.codehaus.mojo + findbugs-maven-plugin + ${findbugs.version} + + ${findbugs.threshold} + ${findbugs.exclude} + + + + + + + + org.apache.maven.plugins + maven-gpg-plugin + + + sign-artifacts + verify + + sign + + + + + + + diff --git a/src/main/java/javax/annotation/Generated.java b/src/main/java/javax/annotation/Generated.java new file mode 100644 index 0000000..e24f632 --- /dev/null +++ b/src/main/java/javax/annotation/Generated.java @@ -0,0 +1,67 @@ +/* + * Copyright (c) 2005, 2018 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 javax.annotation; +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * The Generated 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. + *

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 in the value field, + * 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 + * 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 comment element is a place holder for any comments + * that the code generator may want to include in the generated code.

+ * + * @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: com.acme.generator.CodeGen. + */ + 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/src/main/java/javax/annotation/ManagedBean.java b/src/main/java/javax/annotation/ManagedBean.java new file mode 100644 index 0000000..4fce3fa --- /dev/null +++ b/src/main/java/javax/annotation/ManagedBean.java @@ -0,0 +1,46 @@ +/* + * Copyright (c) 2009, 2018 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 javax.annotation; + +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * The ManagedBean 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 Managed Bean. Managed Bean names must be unique within a + * Java EE module. For each named Managed Bean, Java EE containers must make + * available the following entries in JNDI, using the same naming scheme used + * for EJB components. + *

+ * In the application namespace:

+ * java:app/<module-name>/<bean-name>

+ * In the module namespace of the module containing the Managed Bean: + *

java:module/<bean-name> + * + */ + public String value() default ""; +} diff --git a/src/main/java/javax/annotation/PostConstruct.java b/src/main/java/javax/annotation/PostConstruct.java new file mode 100644 index 0000000..de53c0b --- /dev/null +++ b/src/main/java/javax/annotation/PostConstruct.java @@ -0,0 +1,73 @@ +/* + * Copyright (c) 2005, 2018 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 javax.annotation; + +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * 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 criteria: + *

+ * + * @see javax.annotation.PreDestroy + * @see javax.annotation.Resource + * @since 1.6, Common Annotations 1.0 + */ +@Documented +@Retention (RUNTIME) +@Target(METHOD) +public @interface PostConstruct { +} diff --git a/src/main/java/javax/annotation/PreDestroy.java b/src/main/java/javax/annotation/PreDestroy.java new file mode 100644 index 0000000..2d2d842 --- /dev/null +++ b/src/main/java/javax/annotation/PreDestroy.java @@ -0,0 +1,73 @@ +/* + * Copyright (c) 2005, 2018 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 javax.annotation; + +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * 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 it has been holding. This annotation must be + * supported by all container-managed objects that support the use of + * the PostConstruct annotation except the Java EE application + * client. The method on which the PreDestroy annotation + * is applied must fulfill all of the following criteria: + * + * + * @see javax.annotation.PostConstruct + * @see javax.annotation.Resource + * @since 1.6, Common Annotations 1.0 + */ + +@Documented +@Retention (RUNTIME) +@Target(METHOD) +public @interface PreDestroy { +} diff --git a/src/main/java/javax/annotation/Priority.java b/src/main/java/javax/annotation/Priority.java new file mode 100644 index 0000000..ae10049 --- /dev/null +++ b/src/main/java/javax/annotation/Priority.java @@ -0,0 +1,50 @@ +/* + * Copyright (c) 2005, 2018 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 javax.annotation; + +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * 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 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.

+ * + * @since Common Annotations 1.2 + */ +@Target({TYPE,PARAMETER}) +@Retention(RUNTIME) +@Documented +public @interface Priority { + /** + * The priority value. + */ + int value(); +} diff --git a/src/main/java/javax/annotation/Resource.java b/src/main/java/javax/annotation/Resource.java new file mode 100644 index 0000000..da75267 --- /dev/null +++ b/src/main/java/javax/annotation/Resource.java @@ -0,0 +1,119 @@ +/* + * Copyright (c) 2005, 2018 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 javax.annotation; + +import java.lang.annotation.*; +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +/** + * The Resource 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. + *

+ * Even though this annotation is not marked Inherited, 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.

+ * + * @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 mappedName 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. + *

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.

+ */ + 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/src/main/java/javax/annotation/Resources.java b/src/main/java/javax/annotation/Resources.java new file mode 100644 index 0000000..d603b5a --- /dev/null +++ b/src/main/java/javax/annotation/Resources.java @@ -0,0 +1,37 @@ +/* + * Copyright (c) 2005, 2018 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 javax.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 javax.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/src/main/java/javax/annotation/package.html b/src/main/java/javax/annotation/package.html new file mode 100644 index 0000000..4e01dd2 --- /dev/null +++ b/src/main/java/javax/annotation/package.html @@ -0,0 +1,23 @@ + + + + + This package defines the common annotations. + + diff --git a/src/main/java/javax/annotation/security/DeclareRoles.java b/src/main/java/javax/annotation/security/DeclareRoles.java new file mode 100644 index 0000000..44a4ce1 --- /dev/null +++ b/src/main/java/javax/annotation/security/DeclareRoles.java @@ -0,0 +1,37 @@ +/* + * Copyright (c) 2005, 2018 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 javax.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 DeclareRoles + * 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/src/main/java/javax/annotation/security/DenyAll.java b/src/main/java/javax/annotation/security/DenyAll.java new file mode 100644 index 0000000..388a512 --- /dev/null +++ b/src/main/java/javax/annotation/security/DenyAll.java @@ -0,0 +1,34 @@ +/* + * Copyright (c) 2005, 2018 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 javax.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 javax.annotation.security.RolesAllowed + * @see javax.annotation.security.PermitAll + * @since Common Annotations 1.0 + */ +@Documented +@Retention (RUNTIME) +@Target({TYPE, METHOD}) +public @interface DenyAll { +} diff --git a/src/main/java/javax/annotation/security/PermitAll.java b/src/main/java/javax/annotation/security/PermitAll.java new file mode 100644 index 0000000..2d94427 --- /dev/null +++ b/src/main/java/javax/annotation/security/PermitAll.java @@ -0,0 +1,42 @@ +/* + * Copyright (c) 2005, 2018 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 javax.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 RolesAllowed + * annotation is specified at the class level and this annotation is + * applied at the method level, the PermitAll + * annotation overrides the RolesAllowed annotation for + * the specified method. + * + * @see javax.annotation.security.RolesAllowed + * @see javax.annotation.security.DenyAll + * + * @since Common Annotations 1.0 + */ +@Documented +@Retention (RUNTIME) +@Target({TYPE, METHOD}) +public @interface PermitAll { +} diff --git a/src/main/java/javax/annotation/security/RolesAllowed.java b/src/main/java/javax/annotation/security/RolesAllowed.java new file mode 100644 index 0000000..30978d3 --- /dev/null +++ b/src/main/java/javax/annotation/security/RolesAllowed.java @@ -0,0 +1,42 @@ +/* + * Copyright (c) 2005, 2018 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 javax.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 RolesAllowed 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/src/main/java/javax/annotation/security/RunAs.java b/src/main/java/javax/annotation/security/RunAs.java new file mode 100644 index 0000000..05bacff --- /dev/null +++ b/src/main/java/javax/annotation/security/RunAs.java @@ -0,0 +1,38 @@ +/* + * Copyright (c) 2005, 2018 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 javax.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/src/main/java/javax/annotation/security/package.html b/src/main/java/javax/annotation/security/package.html new file mode 100644 index 0000000..f3b4a0d --- /dev/null +++ b/src/main/java/javax/annotation/security/package.html @@ -0,0 +1,23 @@ + + + + + This package contains the security common annotations. + + diff --git a/src/main/java/javax/annotation/sql/DataSourceDefinition.java b/src/main/java/javax/annotation/sql/DataSourceDefinition.java new file mode 100644 index 0000000..ab919fd --- /dev/null +++ b/src/main/java/javax/annotation/sql/DataSourceDefinition.java @@ -0,0 +1,313 @@ +/* + * Copyright (c) 2009, 2018 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 javax.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 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 + * Java 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 availability of the driver class will be assumed at runtime. + *

+ * 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: + *

+ * 

+ *   @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!!!
+ *
+ *

+ * In the above example, the databaseName, user + * and serverName properties were specified as part of the + * url property and using the corresponding + * annotation elements. This should be avoided. + *

+ * If the properties 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: + *

+ * 

+ *   @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!!!
+ *
+ *

+ * This would result in the following values being used when configuring + * the DataSource: + *

+ *

+ * 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. + *

+ * Examples: + *
+ * 

+ *   @DataSourceDefinition(name="java:global/MyApp/MyDataSource",
+ *      className="com.foobar.MyDataSource",
+ *      portNumber=6689,
+ *      serverName="myserver.com",
+ *      user="lance",
+ *      password="secret"
+ *   )
+ * 
+ *
+ *

+ * Using a URL: + *
+ * 

+ *  @DataSourceDefinition(name="java:global/MyApp/MyDataSource",
+ *    className="org.apache.derby.jdbc.ClientDataSource",
+ *    url="jdbc:derby://localhost:1527/myDB",
+ *    user="lance",
+ *    password="secret"
+ * )
+ *
+ *

+ * An example lookup of the DataSource from an EJB: + * 

+ * @Stateless
+ * public class MyStatelessEJB {
+ *   @Resource(lookup="java:global/MyApp/myDataSource")
+ *    DataSource myDB;
+ *      ...
+ * }
+ *
+ *

+ * @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 + * javax.sql.DataSource or javax.sql.XADataSource + * or javax.sql.ConnectionPoolDataSource. + * @since 1.1 + */ + String className(); + + /** + * Description of this data source + * @since 1.1 + */ + String description() default ""; + + /** + * 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. + * @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: + *

+ *

+ *

+ * Default is vendor-specific. + * @since 1.1 + */ + int isolationLevel() default -1; + + /** + * Set to false if connections should not participate + * in transactions. + *

+ * 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. + *

+ * Default is vendor-specific + * @since 1.1 + */ + int initialPoolSize() default -1; + + /** + * Maximum number of connections that should be concurrently allocated for a + * connection pool. + *

+ * Default is vendor-specific. + * @since 1.1 + */ + int maxPoolSize() default -1; + + /** + * Minimum number of connections that should be allocated for a + * connection pool. + *

+ * 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. + *

+ * 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. + *

+ * Default is vendor-specific + * @since 1.1 + */ + int maxStatements() default -1; + /** + * Used to specify vendor-specific properties and less commonly + * used DataSource properties such as: + *

+ *

+ *

+ * Properties are specified using the format: + * propertyName=propertyValue with one property per array element. + *

+ * 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. + * @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. + *

+ * Default is vendor-specific. + * @since 1.1 + */ + int loginTimeout() default 0; +} diff --git a/src/main/java/javax/annotation/sql/DataSourceDefinitions.java b/src/main/java/javax/annotation/sql/DataSourceDefinitions.java new file mode 100644 index 0000000..a4b914b --- /dev/null +++ b/src/main/java/javax/annotation/sql/DataSourceDefinitions.java @@ -0,0 +1,35 @@ +/* + * Copyright (c) 2009, 2018 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 javax.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 DataSourceDefinition annotations. + * + * @see javax.annotation.sql.DataSourceDefinition + * @since Common Annotations 1.1 + */ +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +public @interface DataSourceDefinitions { + DataSourceDefinition[] value (); + +}