diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..afe8075 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,161 @@ +# Guidance for AI agents, bots, and humans contributing to Chronicle Software's OpenHFT projects. + +LLM-based agents can accelerate development only if they respect our house rules. This file tells you: + +* how to run and verify the build; +* what *not* to comment; +* when to open pull requests. + +## Language & character-set policy + +| Requirement | Rationale | +|--------------|-----------| +| **British English** spelling (`organisation`, `licence`, *not* `organization`, `license`) except technical US spellings like `synchronized` | Keeps wording consistent with Chronicle's London HQ and existing docs. See the University of Oxford style guide for reference. | +| **ASCII-7 only** (code-points 0-127). Avoid smart quotes, non-breaking spaces and accented characters. | ASCII-7 survives every toolchain Chronicle uses, incl. low-latency binary wire formats that expect the 8th bit to be 0. | +| If a symbol is not available in ASCII-7, use a textual form such as `micro-second`, `>=`, `:alpha:`, `:yes:`. This is the preferred approach and Unicode must not be inserted. | Extended or '8-bit ASCII' variants are *not* portable and are therefore disallowed. | + +## Javadoc guidelines + +**Goal:** Every Javadoc block should add information you cannot glean from the method signature alone. Anything else is +noise and slows readers down. + +| Do | Don’t | +|----|-------| +| State *behavioural contracts*, edge-cases, thread-safety guarantees, units, performance characteristics and checked exceptions. | Restate the obvious ("Gets the value", "Sets the name"). | +| Keep the first sentence short; it becomes the summary line in aggregated docs. | Duplicate parameter names/ types unless more explanation is needed. | +| Prefer `@param` for *constraints* and `@throws` for *conditions*, following Oracle’s style guide. | Pad comments to reach a line-length target. | +| Remove or rewrite autogenerated Javadoc for trivial getters/setters. | Leave stale comments that now contradict the code. | + +The principle that Javadoc should only explain what is *not* manifest from the signature is well-established in the +wider Java community. + +## Build & test commands + +Agents must verify that the project still compiles and all unit tests pass before opening a PR: + +```bash +# From repo root +mvn -q verify +``` + +## Commit-message & PR etiquette + +1. **Subject line <= 72 chars**, imperative mood: "Fix roll-cycle offset in `ExcerptAppender`". +2. Reference the JIRA/GitHub issue if it exists. +3. In *body*: *root cause -> fix -> measurable impact* (latency, allocation, etc.). Use ASCII bullet points. +4. **Run `mvn verify`** again after rebasing. + +## What to ask the reviewers + +* *Is this AsciiDoc documentation precise enough for a clean-room re-implementation?* +* Does the Javadoc explain the code's *why* and *how* that a junior developer would not be expected to work out? +* Are the documentation, tests and code updated together so the change is clear? +* Does the commit point back to the relevant requirement or decision tag? +* Would an example or small diagram help future maintainers? + +## Project requirements + +See the [Decision Log](src/main/adoc/decision-log.adoc) for the latest project decisions. +See the [Project Requirements](src/main/adoc/project-requirements.adoc) for details on project requirements. + +## Elevating the Workflow with Real-Time Documentation + +Building upon our existing Iterative Workflow, the newest recommendation is to emphasise *real-time updates* to documentation. +Ensure the relevant `.adoc` files are updated when features, requirements, implementation details, or tests change. +This tight loop informs the AI accurately and creates immediate clarity for all team members. + +### Benefits of Real-Time Documentation + +* **Confidence in documentation**: Accurate docs prevent miscommunications that derail real-world outcomes. +* **Reduced drift**: Real-time updates keep requirements, tests and code aligned. +* **Faster feedback**: AI can quickly highlight inconsistencies when everything is in sync. +* **Better quality**: Frequent checks align the implementation with the specified behaviour. +* **Smoother onboarding**: Up-to-date AsciiDoc clarifies the system for new developers. +* **Incremental changes**: AIDE flags newly updated files so you can keep the documentation synchronised. + +### Best Practices + +* **Maintain Sync**: Keep documentation (AsciiDoc), tests, and code synchronised in version control. Changes in one area should prompt reviews and potential updates in the others. +* **Doc-First for New Work**: For *new* features or requirements, aim to update documentation first, then use AI to help produce or refine corresponding code and tests. For refactoring or initial bootstrapping, updates might flow from code/tests back to documentation, which should then be reviewed and finalised. +* **Small Commits**: Each commit should ideally relate to a single requirement or coherent change, making reviews easier for humans and AI analysis tools. +- **Team Buy-In**: Encourage everyone to review AI outputs critically and contribute to maintaining the synchronicity of all artefacts. + +## AI Agent Guidelines + +When using AI agents to assist with development, please adhere to the following guidelines: + +* **Respect the Language & Character-set Policy**: Ensure all AI-generated content follows the British English and ASCII-7 guidelines outlined above. +Focus on Clarity: AI-generated documentation should be clear and concise and add value beyond what is already present in the code or existing documentation. +* **Avoid Redundancy**: Do not generate content that duplicates existing documentation or code comments unless it provides additional context or clarification. +* **Review AI Outputs**: Always review AI-generated content for accuracy, relevance, and adherence to the project's documentation standards before committing it to the repository. + +## Company-Wide Tagging + +This section records **company-wide** decisions that apply to *all* Chronicle projects. All identifiers use the --xxx prefix. The `xxx` are unique across in the same Scope even if the tags are different. Component-specific decisions live in their xxx-decision-log.adoc files. + +### Tag Taxonomy (Nine-Box Framework) + +To improve traceability, we adopt the Nine-Box taxonomy for requirement and decision identifiers. These tags are used in addition to the existing ALL prefix, which remains reserved for global decisions across every project. + +.Adopt a Nine-Box Requirement Taxonomy + +|Tag | Scope | Typical examples | +|----|-------|------------------| +|FN |Functional user-visible behaviour | Message routing, business rules | +|NF-P |Non-functional - Performance | Latency budgets, throughput targets | +|NF-S |Non-functional - Security | Authentication method, TLS version | +|NF-O |Non-functional - Operability | Logging, monitoring, health checks | +|TEST |Test / QA obligations | Chaos scenarios, benchmarking rigs | +|DOC |Documentation obligations | Sequence diagrams, user guides | +|OPS |Operational / DevOps concerns | Helm values, deployment checklist | +|UX |Operator or end-user experience | CLI ergonomics, dashboard layouts | +|RISK |Compliance / risk controls | GDPR retention, audit trail | + +`ALL-*` stays global, case-exact tags. Pick one primary tag if multiple apply. + +### Decision Record Template + +```asciidoc +=== [Identifier] Title of Decision + +- Date: YYYY-MM-DD +- Context: +* What is the issue that this decision addresses? +* What are the driving forces, constraints, and requirements? +- Decision Statement: +* What is the change that is being proposed or was decided? +- **Alternatives Considered:** +* [Alternative 1 Name/Type]: +** *Description:* Brief description of the alternative. +** *Pros:* ... +** *Cons:* ... +* [Alternative 2 Name/Type]: +** *Description:* Brief description of the alternative. +** *Pros:* ... +** *Cons:* ... +- **Rationale for Decision:** +* Why was the chosen decision selected? +* How does it address the context and outweigh the cons of alternatives? +- **Impact & Consequences:** +* What are the positive and negative consequences of this decision? +* How does this decision affect the system, developers, users, or operations? +- What are the trade-offs made? +- **Notes/Links:** +** (Optional: Links to relevant issues, discussions, documentation, proof-of-concepts) +``` + +## Asciidoc formatting guidelines + +### List Indentation + +Do not rely on indentation for list items in AsciiDoc documents. Use the following pattern instead: + +```asciidoc +- top level +* second level + ** third level +``` + +### Emphasis and Bold Text + +In AsciiDoc, an underscore `_` is _emphasis_; `*text*` is *bold*. \ No newline at end of file diff --git a/LICENSE.adoc b/LICENSE.adoc index 572ae09..eb12fcc 100644 --- a/LICENSE.adoc +++ b/LICENSE.adoc @@ -1,547 +1,14 @@ -== Copyright 2016 higherfrequencytrading.com +== Copyright 2016-2025 chronicle.software ----- - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ +Licensed under the *Apache License, Version 2.0* (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + http://www.apache.org/licenses/LICENSE-2.0 - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) 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. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - -APACHE HTTP SERVER SUBCOMPONENTS: - -The Apache HTTP Server includes a number of subcomponents with -separate copyright notices and license terms. Your use of the source -code for the these subcomponents is subject to the terms and -conditions of the following licenses. - -For the mod_mime_magic component: - -/* - * mod_mime_magic: MIME type lookup via file magic numbers - * Copyright (c) 1996-1997 Cisco Systems, Inc. - * - * This software was submitted by Cisco Systems to the Apache Group in July - * 1997. Future revisions and derivatives of this source code must - * acknowledge Cisco Systems as the original contributor of this module. - * All other licensing and usage conditions are those of the Apache Group. - * - * Some of this code is derived from the free version of the file command - * originally posted to comp.sources.unix. Copyright info for that program - * is included below as required. - * --------------------------------------------------------------------------- - * - Copyright (c) Ian F. Darwin, 1987. Written by Ian F. Darwin. - * - * This software is not subject to any license of the American Telephone and - * Telegraph Company or of the Regents of the University of California. - * - * Permission is granted to anyone to use this software for any purpose on any - * computer system, and to alter it and redistribute it freely, subject to - * the following restrictions: - * - * 1. The author is not responsible for the consequences of use of this - * software, no matter how awful, even if they arise from flaws in it. - * - * 2. The origin of this software must not be misrepresented, either by - * explicit claim or by omission. Since few users ever read sources, credits - * must appear in the documentation. - * - * 3. Altered versions must be plainly marked as such, and must not be - * misrepresented as being the original software. Since few users ever read - * sources, credits must appear in the documentation. - * - * 4. This notice may not be removed or altered. - * ------------------------------------------------------------------------- - * - */ - -For the modules\mappers\mod_imagemap.c component: - - "macmartinized" polygon code copyright 1992 by Eric Haines, erich@eye.com - -For the server\util_md5.c component: - -/************************************************************************ - * NCSA HTTPd Server - * Software Development Group - * National Center for Supercomputing Applications - * University of Illinois at Urbana-Champaign - * 605 E. Springfield, Champaign, IL 61820 - * httpd@ncsa.uiuc.edu - * - * Copyright (C) 1995, Board of Trustees of the University of Illinois - * - ************************************************************************ - * - * md5.c: NCSA HTTPd code which uses the md5c.c RSA Code - * - * Original Code Copyright (C) 1994, Jeff Hostetler, Spyglass, Inc. - * Portions of Content-MD5 code Copyright (C) 1993, 1994 by Carnegie Mellon - * University (see Copyright below). - * Portions of Content-MD5 code Copyright (C) 1991 Bell Communications - * Research, Inc. (Bellcore) (see Copyright below). - * Portions extracted from mpack, John G. Myers - jgm+@cmu.edu - * Content-MD5 Code contributed by Martin Hamilton (martin@net.lut.ac.uk) - * - */ - -/* these portions extracted from mpack, John G. Myers - jgm+@cmu.edu */ -/* (C) Copyright 1993,1994 by Carnegie Mellon University - * All Rights Reserved. - * - * Permission to use, copy, modify, distribute, and sell this software - * and its documentation for any purpose is hereby granted without - * fee, provided that the above copyright notice appear in all copies - * and that both that copyright notice and this permission notice - * appear in supporting documentation, and that the name of Carnegie - * Mellon University not be used in advertising or publicity - * pertaining to distribution of the software without specific, - * written prior permission. Carnegie Mellon University makes no - * representations about the suitability of this software for any - * purpose. It is provided "as is" without express or implied - * warranty. - * - * CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO - * THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY - * AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE - * FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN - * AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING - * OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS - * SOFTWARE. - */ - -/* - * Copyright (c) 1991 Bell Communications Research, Inc. (Bellcore) - * - * Permission to use, copy, modify, and distribute this material - * for any purpose and without fee is hereby granted, provided - * that the above copyright notice and this permission notice - * appear in all copies, and that the name of Bellcore not be - * used in advertising or publicity pertaining to this - * material without the specific, prior written permission - * of an authorized representative of Bellcore. BELLCORE - * MAKES NO REPRESENTATIONS ABOUT THE ACCURACY OR SUITABILITY - * OF THIS MATERIAL FOR ANY PURPOSE. IT IS PROVIDED "AS IS", - * WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. - */ - -For the srclib\apr\include\apr_md5.h component: -/* - * This is work is derived from material Copyright RSA Data Security, Inc. - * - * The RSA copyright statement and Licence for that original material is - * included below. This is followed by the Apache copyright statement and - * licence for the modifications made to that material. - */ - -/* Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All - rights reserved. - - License to copy and use this software is granted provided that it - is identified as the "RSA Data Security, Inc. MD5 Message-Digest - Algorithm" in all material mentioning or referencing this software - or this function. - - License is also granted to make and use derivative works provided - that such works are identified as "derived from the RSA Data - Security, Inc. MD5 Message-Digest Algorithm" in all material - mentioning or referencing the derived work. - - RSA Data Security, Inc. makes no representations concerning either - the merchantability of this software or the suitability of this - software for any particular purpose. It is provided "as is" - without express or implied warranty of any kind. - - These notices must be retained in any copies of any part of this - documentation and/or software. - */ - -For the srclib\apr\passwd\apr_md5.c component: - -/* - * This is work is derived from material Copyright RSA Data Security, Inc. - * - * The RSA copyright statement and Licence for that original material is - * included below. This is followed by the Apache copyright statement and - * licence for the modifications made to that material. - */ - -/* MD5C.C - RSA Data Security, Inc., MD5 message-digest algorithm - */ - -/* Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All - rights reserved. - - License to copy and use this software is granted provided that it - is identified as the "RSA Data Security, Inc. MD5 Message-Digest - Algorithm" in all material mentioning or referencing this software - or this function. - - License is also granted to make and use derivative works provided - that such works are identified as "derived from the RSA Data - Security, Inc. MD5 Message-Digest Algorithm" in all material - mentioning or referencing the derived work. - - RSA Data Security, Inc. makes no representations concerning either - the merchantability of this software or the suitability of this - software for any particular purpose. It is provided "as is" - without express or implied warranty of any kind. - - These notices must be retained in any copies of any part of this - documentation and/or software. - */ -/* - * The apr_md5_encode() routine uses much code obtained from the FreeBSD 3.0 - * MD5 crypt() function, which is licenced as follows: - * ---------------------------------------------------------------------------- - * "THE BEER-WARE LICENSE" (Revision 42): - * wrote this file. As long as you retain this notice you - * can do whatever you want with this stuff. If we meet some day, and you think - * this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp - * ---------------------------------------------------------------------------- - */ - -For the srclib\apr-util\crypto\apr_md4.c component: - - * This is derived from material copyright RSA Data Security, Inc. - * Their notice is reproduced below in its entirety. - * - * Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All - * rights reserved. - * - * License to copy and use this software is granted provided that it - * is identified as the "RSA Data Security, Inc. MD4 Message-Digest - * Algorithm" in all material mentioning or referencing this software - * or this function. - * - * License is also granted to make and use derivative works provided - * that such works are identified as "derived from the RSA Data - * Security, Inc. MD4 Message-Digest Algorithm" in all material - * mentioning or referencing the derived work. - * - * RSA Data Security, Inc. makes no representations concerning either - * the merchantability of this software or the suitability of this - * software for any particular purpose. It is provided "as is" - * without express or implied warranty of any kind. - * - * These notices must be retained in any copies of any part of this - * documentation and/or software. - */ - -For the srclib\apr-util\include\apr_md4.h component: - - * - * This is derived from material copyright RSA Data Security, Inc. - * Their notice is reproduced below in its entirety. - * - * Copyright (C) 1991-2, RSA Data Security, Inc. Created 1991. All - * rights reserved. - * - * License to copy and use this software is granted provided that it - * is identified as the "RSA Data Security, Inc. MD4 Message-Digest - * Algorithm" in all material mentioning or referencing this software - * or this function. - * - * License is also granted to make and use derivative works provided - * that such works are identified as "derived from the RSA Data - * Security, Inc. MD4 Message-Digest Algorithm" in all material - * mentioning or referencing the derived work. - * - * RSA Data Security, Inc. makes no representations concerning either - * the merchantability of this software or the suitability of this - * software for any particular purpose. It is provided "as is" - * without express or implied warranty of any kind. - * - * These notices must be retained in any copies of any part of this - * documentation and/or software. - */ - -For the srclib\apr-util\test\testmd4.c component: - - * - * This is derived from material copyright RSA Data Security, Inc. - * Their notice is reproduced below in its entirety. - * - * Copyright (C) 1990-2, RSA Data Security, Inc. Created 1990. All - * rights reserved. - * - * RSA Data Security, Inc. makes no representations concerning either - * the merchantability of this software or the suitability of this - * software for any particular purpose. It is provided "as is" - * without express or implied warranty of any kind. - * - * These notices must be retained in any copies of any part of this - * documentation and/or software. - */ - -For the srclib\apr-util\xml\expat\conftools\install-sh component: - -# -# install - install a program, script, or datafile -# This comes from X11R5 (mit/util/scripts/install.sh). -# -# Copyright 1991 by the Massachusetts Institute of Technology -# -# Permission to use, copy, modify, distribute, and sell this software and its -# documentation for any purpose is hereby granted without fee, provided that -# the above copyright notice appear in all copies and that both that -# copyright notice and this permission notice appear in supporting -# documentation, and that the name of M.I.T. not be used in advertising or -# publicity pertaining to distribution of the software without specific, -# written prior permission. M.I.T. makes no representations about the -# suitability of this software for any purpose. It is provided "as is" -# without express or implied warranty. -# - -For the test\zb.c component: - -/* ZeusBench V1.01 - =============== - -This program is Copyright (C) Zeus Technology Limited 1996. - -This program may be used and copied freely providing this copyright notice -is not removed. - -This software is provided "as is" and any express or implied waranties, -including but not limited to, the implied warranties of merchantability and -fitness for a particular purpose are disclaimed. In no event shall -Zeus Technology Ltd. be liable for any direct, indirect, incidental, special, -exemplary, or consequential damaged (including, but not limited to, -procurement of substitute good or services; loss of use, data, or profits; -or business interruption) however caused and on theory of liability. Whether -in contract, strict liability or tort (including negligence or otherwise) -arising in any way out of the use of this software, even if advised of the -possibility of such damage. - - Written by Adam Twiss (adam@zeus.co.uk). March 1996 - -Thanks to the following people for their input: - Mike Belshe (mbelshe@netscape.com) - Michael Campanella (campanella@stevms.enet.dec.com) - -*/ - -For the expat xml parser component: - -Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd - and Clark Cooper - -Permission is hereby granted, free of charge, to any person obtaining -a copy of this software and associated documentation files (the -"Software"), to deal in the Software without restriction, including -without limitation the rights to use, copy, modify, merge, publish, -distribute, sublicense, and/or sell copies of the Software, and to -permit persons to whom the Software is furnished to do so, subject to -the following conditions: - -The above copyright notice and this permission notice shall be included -in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY -CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, -TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE -SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -==================================================================== ----- \ No newline at end of file +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/README.adoc b/README.adoc index 638ebdc..b687746 100644 --- a/README.adoc +++ b/README.adoc @@ -2,66 +2,125 @@ Chronicle Software :css-signature: demo :toc: macro -:toclevels: 2 -:icons: font +:source-highlighter: rouge -image:https://maven-badges.herokuapp.com/maven-central/net.openhft/compiler/badge.svg[caption="",link=https://maven-badges.herokuapp.com/maven-central/net.openhft/compiler] -image:https://javadoc.io/badge2/net.openhft/compiler/javadoc.svg[link="https://www.javadoc.io/doc/net.openhft/compiler/latest/index.html"] -//image:https://javadoc-badge.appspot.com/net.openhft/compiler.svg?label=javadoc[JavaDoc, link=https://www.javadoc.io/doc/net.openhft/compiler] -image:https://img.shields.io/github/license/OpenHFT/Java-Runtime-Compiler[GitHub] +image:https://maven-badges.herokuapp.com/maven-central/net.openhft/compiler/badge.svg[] +image:https://javadoc.io/badge2/net.openhft/compiler/javadoc.svg[] image:https://img.shields.io/badge/release%20notes-subscribe-brightgreen[link="https://chronicle.software/release-notes/"] -image:https://sonarcloud.io/api/project_badges/measure?project=OpenHFT_Java-Runtime-Compiler&metric=alert_status[link="https://sonarcloud.io/dashboard?id=OpenHFT_Java-Runtime-Compiler"] +image:https://sonarcloud.io/api/project_badges/measure?project=OpenHFT_Java-Runtime-Compiler&metric=alert_status[] -This takes a String, compiles it and loads it returning you a class from what you built. -By default it uses the current ClassLoader. -It supports nested classes, otherwise builds one class at a time. +toc::[] -== On Maven Central +This library lets you feed _plain Java source as a_ `String`, compile it in-memory and +immediately load the resulting `Class` - perfect for hot-swapping logic while the JVM +is still running. -You can include in your project with +== 1 Quick-Start -```xml +[source,xml,subs=+quotes] +---- + net.openhft compiler - + Look up the most recent version on Maven Central. -``` - -== Simple example - -You need a CachedCompiler and access to your JDK's tools.jar. - -```java -// dynamically you can call -String className = "mypackage.MyClass"; -String javaCode = "package mypackage;\n" + - "public class MyClass implements Runnable {\n" + - " public void run() {\n" + - " System.out.println(\"Hello World\");\n" + - " }\n" + - "}\n"; -Class aClass = CompilerUtils.CACHED_COMPILER.loadFromJava(className, javaCode); -Runnable runner = (Runnable) aClass.newInstance(); -runner.run(); -``` - -I suggest making your class implement a KnownInterface of your choice as this will allow you to call/manipulate instances of you generated class. - -Another more hacky way is to use this to override a class, provided it hasn't been loaded already. -This means you can redefine an existing class and provide the methods and fields used match, -you have compiler redefine a class and code already compiled to use the class will still work. - -== Using the CachedCompiler. - -In this example, you can configure the compiler to write the files to a specific directory when you are in debug mode. - -```java -private static final CachedCompiler JCC = CompilerUtils.DEBUGGING ? - new CachedCompiler(new File(parent, "src/test/java"), new File(parent, "target/compiled")) : - CompilerUtils.CACHED_COMPILER; -``` - -By selecting the src directory to match where your IDE looks for those files, it will allow your debugger to set into the code you have generated at runtime. - -Note: you may need to delete these files if you want to regenerate them. +---- + +[source,groovy,subs=+quotes] +---- +/* Gradle (Kotlin DSL) */ +implementation("net.openhft:compiler:Look up the most recent version on Maven Central.") +---- + +.Example: compile and run a _Runnable_ at runtime +[source,java] +---- +import net.openhft.compiler.CompilerUtils; + +String className = "mypackage.MyDynamicClass"; +String src = """ + package mypackage; + public class MyDynamicClass implements Runnable { + public void run() { + System.out.println("Hello World"); + } + } +"""; + +Class clazz = CompilerUtils.CACHED_COMPILER.loadFromJava(className, src); +((Runnable) clazz.getDeclaredConstructor().newInstance()).run(); +---- + +== 2 Installation + +* Requires a **full JDK** (8, 11, 17 or 21 LTS), _not_ a slim JRE. +* On Java 11 + supply these flags (copy-paste safe): + +[source,bash] +---- +--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED +--add-opens=jdk.compiler/com.sun.tools.javac=ALL-UNNAMED +---- +* Spring-Boot / fat-JAR users +** unpack Chronicle jars: +`bootJar { requiresUnpack("**/chronicle-*.jar") }` + +== 3 Feature Highlights + +|=== +| Feature | Benefit + +| In-memory compile & load +| Hot-swap code without restarting JVM + +| CachedCompiler +| Skips recompilation of unchanged source + +| Debug Mode +| Writes `.java` / `.class` so IDE breakpoints work + +| Custom ClassLoader support +| Isolate plugins or enable class unloading + +| Nested-class handling +| Build helper hierarchy in a single call +|=== + +== 4 Advanced Usage & Patterns + +* Hot-swappable *strategy interface* for trading engines +** Rule-engine: compile business rules implementing `Rule` +*** Supports validator hook to vet user code +** Replace reflection: generate POJO accessors, 10 x faster +** Off-heap accessors with Chronicle Bytes / Map + + +== 5 Operational Notes + +* Compile on a background thread at start-up; then swap instances. +** Re-use class names _or_ child classloaders to control Metaspace. +*** Use `CompilerUtils.DEBUGGING = true` during dev; remember to prune artefacts. +** SLF4J categories: `net.openhft.compiler` (INFO), compilation errors at ERROR. +** Micrometer timers/counters: `compiler.compiles`, `compiler.failures`. + +== 6 FAQ / Troubleshooting + +* *`ToolProvider.getSystemJavaCompiler() == null`* +* You are running on a JRE; use a JDK. +* *`ClassNotFoundException: com.sun.tools.javac.api.JavacTool`* +* tools.jar is required on JDK <= 8. Newer JDKs need the `--add-exports` and `--add-opens` flags. +* Classes never unload +* Generate with a unique `ClassLoader` per version so classes can unload; each loader uses Metaspace. +* Illegal-reflective-access warning +* Add the `--add-opens` & `--add-exports` flags shown above. + +== 7 CI / Build & Test + +* GitHub Actions workflow runs `mvn verify`, unit & race-condition tests. +** Code-coverage report published to SonarCloud badge above. + +== 8 Contributing & License + +* Fork -> feature branch -> PR; run `mvn spotless:apply` before pushing. +** All code under the *Apache License 2.0* - see `LICENSE`. diff --git a/pom.xml b/pom.xml index 72f04e8..16d5f56 100644 --- a/pom.xml +++ b/pom.xml @@ -1,6 +1,6 @@