From 6e5f9d92d855b4fca5cc3b3c6322998121f7cce8 Mon Sep 17 00:00:00 2001 From: David Gibbs Date: Mon, 13 Nov 2023 12:32:20 +0000 Subject: [PATCH] updated readmes --- customising-quickfixj.md | 48 ++++++++++++++------------ quickfixj-core/readme.md | 6 ++-- quickfixj-messages/readme.md | 57 ++++++++++++++++--------------- quickfixj-orchestration/readme.md | 4 +-- 4 files changed, 59 insertions(+), 56 deletions(-) diff --git a/customising-quickfixj.md b/customising-quickfixj.md index d9a9e658e9..0bab497287 100644 --- a/customising-quickfixj.md +++ b/customising-quickfixj.md @@ -11,11 +11,11 @@ The standard distribution of ```quickfixj-core``` can be used with custom artefa To build custom artefacts it's helpful to understand how QuickFIX/J builds the Field, Component and Message classes from the QuickFIX/J dictionaries and from [FIX Orchestra](https://www.fixtrading.org/standards/fix-orchestra/). -QuickFIX/J reference implementations for FIX versions FIX4.0 to FIX5.0sp2 and for FIXT1.1 are generated from the QuickFIX dictionaries for the specific version. The dictionaries are located in the ```src/main/resources``` directory of the respective modules of the ```quickfixj-messages``` module. -This intentionally provides consistency with the prior QuickFIX/J 2 release to ease migration to QuickFIX/J 3. +The QuickFIX/J reference implementations for FIX versions FIX4.0 to FIX5.0sp2 and for FIXT1.1 are generated from the QuickFIX dictionaries for the specific version. The dictionaries are located in the ```src/main/resources``` directory of the respective modules of the ```quickfixj-messages``` module. +Maintaining the FIX4.0 to FIX5.0sp2 builds intentionally provides consistency with the prior QuickFIX/J 2 release in order to ease migration to QuickFIX/J 3. -The QuickFIX/J reference implementation for FIX Latest is generated from a [FIX Orchestra](https://www.fixtrading.org/standards/fix-orchestra/) repository file. -An implementation derived from the standard FIX Orchestra repository is known as an "_orchestration_". +The most recent standard is defined as [FIX Latest](https://www.fixtrading.org/online-specification/). The QuickFIX/J reference implementation for FIX Latest is generated from a [FIX Orchestra](https://www.fixtrading.org/standards/fix-orchestra/) repository file. +An implementation or customisation of the FIX Standars derived from the FIX Orchestra repository is known as an "_orchestration_". The standard FIX Orchestra repository requires some modification to work well with QuickFIX/J. This is done by the ```quickfixj-orchestration``` module. The ```quickfixj-orchestration``` module publishes a modified Orchestra artefact which can then be the basis of a custom FIX Latest build using QuickFIX/J . @@ -28,7 +28,7 @@ Please see [QuickFIX/J Orchestration](./quickfixj-orchestration/readme.md) for d ### **Enable the use of ```BigDecimal``` for FIX Decimal Data Types** -This behaviour is controlled by the ```${generator.decimal}``` build property. It is "false" by default to avoid surprising side effects of Incompatible Data Types. +This behaviour is controlled by the ```${generator.decimal}``` build property. It is "false" by default to avoid surprising side effects of incompatible data types. To enable the use of ```BigDecimal``` in code generation, set the ```${generator.decimal}``` property to "true" in [quickfixj-messages](./quickfixj-messages/readme.md) and build the message artefacts. @@ -55,7 +55,26 @@ Code generation using ```BigDecimal``` is incompatible at runtime with ```int``` Runtime incompatibilities can be resolved by: * Amending the QuickFIX Dictionary to coerce the code generation and/or validation * Changing the ordering of code generation and/or overwrite behaviour of code generation -* Building independent artefacts for conflicting versions and not using them in the same runtime +* Omitting incompatible versions from your customised build +* Building artefacts independently for the conflicting versions and ensuring they are not used them in the same runtime + +See [QuickFIX/J Messages](./quickfixj-messages/readme.md) for details of the build and recommendation for **how to implement custom builds.** + +### **Customising the FIX Protocol for specialised Rules of Engagement** + +A Rules of Engagement can include customisation Messages, Components and Fields, including User Defined elements. + +It is not necessary to maintain a fork of the entire QuickFIX/J project to provide customised QuickFIX Dictionaries and to +generate type-safe libraries that are interoperable with QuickFIX/J. + +[FIX Orchestra](https://www.fixtrading.org/standards/fix-orchestra/) is intended for customisation to produce machine-readable Rules of Engagement. + +Consider creating a new project (or projects) to build the Messages, Components and Fields as needed for your specific Rules of Engagement. + +Edit the QuickFIX Dictionary or FIX Orchestra Repository (Orchestration) as required and +build the Messages, Components and Fields packages using the tools provided by the QuickFIX/J projects. + +QuickFIX/J Dictionaries, FIX Orchestra Orchestrations and/or documents can also be generated. See [QuickFIX/J Messages](./quickfixj-messages/readme.md) for details of the build and recommendation for **how to implement custom builds.** @@ -70,21 +89,6 @@ The following describes how to use ```quickfixj-core``` from QuickFIX/J 3 witho * build the required Message artefacts without the FIX Latest code generation. The Fields will then be generated only from legacy FIX Protocol Versions as they were prior to QuickFIX/J 3.0.0 - **or** * if you want to use Messages, Components and/or Fields from FIX Latest while preferring legacy constants, manipulate the order of code generation and/or the over-write behaviour of code behaviour to prefer earlier versions of FIX. -* For example, prevent FIX Latest code generation from over-writing existing generated sources (Fields). - -See [QuickFIX/J Messages](./quickfixj-messages/readme.md) for details of the build and recommendation for **how to implement custom builds.** - -### **Customising the FIX Protocol for specialised Rules of Engagement** - -A Rules of Engagement can include customisation Messages, Components and Fields, including User Defined elements. - -This can be accomplished by creating a new project to build the Messages, Components and Fields as needed for your specific Rules of Engagement. -Edit the QuickFIX Dictionary or FIX Orchestra Repository (Orchestration) as required and -build the Messages, Components and Fields packages using the tools provided by the QuickFIX/J projects. -It is not necessary to maintain a fork of the entire QuickFIX/J project to provide customised QuickFIX Dictionaries and to -generate type-safe libraries that are interoperable with QuickFIX/J. -QuickFIX/J Dictionaries, FIX Orchestra Orchestrations and/or documents can also be generated. - -[FIX Orchestra](https://www.fixtrading.org/standards/fix-orchestra/) is intended for customisation to produce machine-readable Rules of Engagement. +For example, generate FIX Latest first and overwrite the generated Field classes by subsequently running code generation for an earlier version. See [QuickFIX/J Messages](./quickfixj-messages/readme.md) for details of the build and recommendation for **how to implement custom builds.** diff --git a/quickfixj-core/readme.md b/quickfixj-core/readme.md index 1afb19f913..e1a31e128c 100644 --- a/quickfixj-core/readme.md +++ b/quickfixj-core/readme.md @@ -2,14 +2,12 @@ This module builds the QuickFIX/J FIX "engine" including supporting capabilities. -The core engine depends on ```quickfixj-base``` and does not have compile time dependency on the Field, Component and Messages classes derived from base classes in ```quickfixj-base```. A small number of derived Fields are provided by ```quickfixj-base``. +The core engine depends on ```quickfixj-base```. A small number of derived Fields are provided by ```quickfixj-base``. -This module does have **test** dependency on generated message classes. The distinction of *test* dependency is significant as it allows easier [customisation](../customising-quickfixj.md) of QuickFIX/J deployments. + This module has **test** dependency on generated message classes. The distinction of *test* dependency is significant as it allows easier [customisation](../customising-quickfixj.md) of QuickFIX/J deployments. ## Developing quickfixj-core To develop this module build ```quickfixj-base``` and ```quickfixj-messages``` first, or build the whole project. Full ```quickfixj-messages``` build times can be long. See [the ```quickfixj-messages``` readme](../quickfixj-messages/readme.md) for how to do a minimal development build of the messages. Once these dependencies are built then ```quickfixj-core``` can be built and tested independently for higher productivity. - -If and when you import the project into an IDE it can be better to exclude or close the ```quickfixj-messages``` module(s) to reduce the memory and computation overheads of importing these large packages. diff --git a/quickfixj-messages/readme.md b/quickfixj-messages/readme.md index d69637e663..341398a090 100644 --- a/quickfixj-messages/readme.md +++ b/quickfixj-messages/readme.md @@ -25,7 +25,7 @@ The more recent versions of the FIX protocol are, in general, super-sets of prio The generated Fields, Components and Messages depend on packages provided by ```quickfixj-base```. Some Standard Header and Trailer ```quickfix.Fields``` are provided by ```quickfixj-base```. -These fields are removed from the generated code for other artefacts before assembly to avoid conflicts with those provided by ```quickfixj-base```. +These fields are removed from the generated code for other artefacts before assembly to avoid runtime class-loader conflicts with those provided by ```quickfixj-base```. In the QuickFIX/J build, implementations for FIX versions from **FIX4.0 to FIX5.0sp2** are generated from the QuickFIX dictionaries for the specific version. The dictionaries are located in the ```src/main/resources``` directory of the respective modules of the ```quickfixj-messages``` module. @@ -38,14 +38,14 @@ An implementation based on the FIX Orchestra standard is known as an "_orchestra The code generation for FIX Latest and FIX T1.1 depends on the orchestration published by the ```quickfixj-orchestration``` module. The code generation for the FIX Protocol specification versions is done in the ```quickfixj-messages-all``` module. -It proceeds in order from oldest to most recent (latest), with the class generated from most recent specification of a Field over-writing any prior classes. +It proceeds in order from oldest to most recent (latest), with the class generated from more recent specification of a Field over-writing any prior classes. This behaviour can be controlled using the ```overwrite``` parameter on the ```quickfixj-codegenerator``` maven plugin and by changing the order of processing. -Consequently, in the reference QuickFIX/J build, almost all the Field classes are those generated from the -FIX Latest specification as in the orchestration published by the ```quickfixj-orchestration``` module.. +Consequently, in the reference QuickFIX/J build, almost all the resulting Field classes are those generated from the +FIX Latest specification as in the orchestration published by the ```quickfixj-orchestration``` module. This scheme works well though in a few cases, a Field data type, having the same designated java class name, has changed between legacy versions. In these cases a choice needs to be made which data type to use. -The QuickFIX/J project build prefers the most recent specification of the field. The Field class generated from most recent specification will overwrite the Field generated from the obsolete specification. +The QuickFIX/J project build order prefers the most recent specification of the field. The Field class generated from most recent specification will overwrite the Field generated from the obsolete specification. In the unlikely event that a legacy version of a Field is required, a custom build can be implemented. Please note; avoid class conflicts by ensuring that generated classes with the same package name only exist in one jar in your classpath. @@ -59,36 +59,37 @@ The packaging is done in reverse order so that Fields not present in older versi This results in smaller, concise distributions and quicker build times. It is not necessary for an application to depend on ```quickfixj-messages-all```. -An application needs only depend on the artefacts for the FIX Protocol versions that it requires. +An application needs only depend on the artefacts for the FIX Protocol versions that it requires at runtime. + Please note that if using the reference QuickFIX/J build, an application using FIX Protocol versions **5.0 and later** will also depend on ```quickfixj-messages-fixt11```. _Detail: The modules for FIX Protocol versions **5.0 and later** build in a slightly different way to the older versions so that - they can exclude classes present in ```quickfixj-messages-all-{version}.jar```_ + they can exclude FIXT1.1 classes present in ```quickfixj-messages-all-{version}.jar```_ ## Tools to use in a custom build * The [```quickfixj-orchestration```](../quickfixj-orchestration/readme.md) module publishes a FIX Latest orchestration that is QuickFIX/J compatible. This can serve as a foundation for a custom Orchestration. * **N.B.** There is also an orchestration available for `FIX4.2` and `FIX4.4`, but the QuickFIX/J project does not employ these resources. QuickFIX/J uses the legacy QuickFIX Dictionaries for greater consistency with legacy QuickFIX/J implementations. -* This project publishes the legacy ```quickfixj-codegenerator``` maven plug-in that is used to generate FIX Field, Component and Message sources from a QuickFIX Dictionary. -* This project depends on [```quickfixj-orchestra```](https://github.com/quickfix-j/quickfixj-orchestra) project artefacts: +* The QuickFIX/J project publishes the legacy ```quickfixj-codegenerator``` maven plug-in that is used to generate FIX Field, Component and Message sources from a QuickFIX Dictionary. +* The QuickFIX/J project depends on [```quickfixj-orchestra```](https://github.com/quickfix-j/quickfixj-orchestra) project artefacts: * ```quickfixj-from-fix-orchestra-code-generator-maven-plugin``` generates FIX Field, Component and Message sources directly from a FIX Orchestration. - * ```quickfixj-from-fix-orchestra-dictionary-generator-maven-plugin``` generates QuickFIX compatible dictionaries from FIX Orchestrations. -* This project publishes the [```class-pruner-maven-plugin```](../class-pruner-maven-plugin/readme.md) that can be used to delete (generated) sources and classes that are not present in provided QuickFIX Dictionaries. -This is a very specialised plug-in and is not expected to be needed for custom builds, see recommendations below. + * ```quickfixj-from-fix-orchestra-dictionary-generator-maven-plugin``` generates a QuickFIX compatible dictionary from a FIX Orchestration. +* The QuickFIX/J project publishes the [```class-pruner-maven-plugin```](../class-pruner-maven-plugin/readme.md) that can be used to delete (generated) sources and classes that are not present in a provided QuickFIX Dictionary. +This is a very specialised plug-in and may not be needed for custom builds, see recommendations below. -These tools should facilitate building custom Fields, Components and Message packages without needing to maintain a customised Fork of the entire QuickFIX/J project for this purpose. +These tools should facilitate building custom Fields, Components and Message packages without needing to maintain a customised Fork of the entire QuickFIX/J project. -Customised builds for Fields, Components and Message can be maintained in projects that depend on the QuickFIX/J build and tools but are independent. +Builds for customised Rules of Engagement can be maintained in projects that depend on the QuickFIX/J *core* build and tools but are otherwise independent. Elements of the structure and process of the ```quickfixj-messages``` can be copied if this is helpful (see below). ## Techniques to customise the generated code * Omit FIX Protocol versions that are not required * For versions prior to FIX Latest, edit the QuickFIX Dictionary to control code generation. - * **N.B.** [FIX Trading Community](https://www.fixtrading.org/) does publish repositories for `FIX 4.2` and `FIX 4.4` but these are not used by the QuickFIX/J build. These may be used as the basis of a custom build. + * **N.B.** [FIX Trading Community](https://www.fixtrading.org/) does publish FIX Orchestra repositories for `FIX 4.2` and `FIX 4.4` but these are not used by the QuickFIX/J build. These may be used as the basis of a custom build. * For __FIX Latest__, edit the FIX Orchestra Repository (Orchestration) to customise code generation. * Manipulate the order of code generation and/or the "over-write" behaviour of code generation -* Use features of the ```quickfixj-from-fix-orchestra-code-generator-maven-plugin``` (generates code from an orchestration) to : +* Use features of the ```quickfixj-from-fix-orchestra-code-generator-maven-plugin``` which generates code from an orchestration to : * Generate only Messages, Components and Fields used by the FIXT1.1 Session Layer [```generateOnlySession```] * Generate only Messages, Components and Fields used by the Application Layer [```excludeSession```] * Choose whether to generate FIXT1.1 Session Layer messages in the package ```quickfix.fixt11``` as in done by the conventional QuickFIX/J build [```generateFixt11Package```] @@ -99,44 +100,44 @@ Elements of the structure and process of the ```quickfixj-messages``` can be cop ## Recommendation on how to implement a custom build -Omission of unused elements may accelerate comprehension and facilitate the generation of documents and other artefacts. -Be aware any such changes during integration and conformance testing to test that Reject and/or Business Message Reject +Omission of unused elements may accelerate comprehension and results in the generation of more concise documents and other artefacts. +Be aware of such changes during integration and conformance testing to test that Reject and/or Business Message Reject messages are handled correctly. The artefacts created by the ```quickfixj-messages``` module are **test** dependencies of ```quickfixj-core```. -They are not specified as _compile_ or _runtime_ dependencies. This is intended to make it easier to customise QuickFIX/J deployments. -**Applications** that depend on ```quickfixj-core``` will need to include artefacts containing Field, Component and Message packages as **compile** or **runtime** dependencies. +They are not specified as _compile_ nor _runtime_ dependencies. This is intended to make it easier to customise QuickFIX/J deployments. +Of course FIX **Applications** that depend on ```quickfixj-core``` will need to include artefacts containing Field, Component and Message packages as **compile** or **runtime** dependencies. -Artefacts for unused FIX specification versions can be omitted from your runtime and it is not necessary to build artefacts that are not used. +Artefacts for unused FIX specification versions can be omitted from your runtime. In a custom build it is not necessary to build artefacts that are not used. **Please note**: In the conventions of the QuickFIX/J build, applications using FIX Protocol versions 5.0 and later will also depend on a ```quickfixj-messages-fixt11``` jar. This provides the FIXT1.1 transport classes. The intention is that a custom build should not need to generate the FIXT1.1 classes and can depend on the ```org.quickfixj:quickfixj-messages-fixt11``` artefact. -This convention is not mandatory. You may choose to package the FIXT1.1 classes in the same artefact as the Message and Field classes. +This convention is not mandatory. You could choose to buld FIXT1.1 yourself and/or to package the FIXT1.1 classes in the same artefact as the Message and Field classes. A custom build can provide custom artefacts for the required Fields, Component and Message. -The QuickFIX/J project can supply ```quickfixj-core```, its transitive dependency ```quickfixj-base``` and tools as described above. +The QuickFIX/J project can supply ```quickfixj-core```, its transitive dependency ```quickfixj-base```, ```quickfixj-messages-fixt11``` and tools as described above. **Custom builds must exclude those few ```quickfix.field```s provided by ```quickfixj-base```.** This avoids ambiguity, conflicts (*package name space collisions*) and jvm class verification exceptions. At run time the Components and Messages must use the Fields against which they have been compiled. -Use the same version of code and dictionary generators that are used by the QuickFIX/J version on which the application an build depends. +Use the same version of code and dictionary generators published with the QuickFIX/J version on which the application depends. One way to start a custom build this is to **copying** this maven module, or only ```quickfixj-messages-all```, into an independent build. If doing so: -* The Maven ```groupId```s should be changed (it's not necessary nor desirable to use ```org.quickfixj``` for custom distributions). The ```version```s and ```artefactId```s may likewise be changed. Artefacts can then be published to public maven repositories as long as the QuickFIX/J ```groupId``` is not used. +* The Maven ```groupId```s should be changed (it's not necessary nor desirable to use ```org.quickfixj``` for custom distributions). The ```version```s and ```artefactId```s may likewise be changed to match the version of your Rules of Engagement. Artefacts can then be published to public maven repositories as long as the QuickFIX/J ```groupId``` is not used. * Ensure the QuickFIX Software License and/or Apache 2 license is included in the distribution. It can be found in the root of this project and/or the [quickfixj-orchestra](https://github.com/quickfix-j/quickfixj-orchestra) project * Modules and directories for FIX Protocol versions that are not required can be removed. The ```quickfixj-messages-all``` contains the code generation. If removing unused FIX protocol versions then the copy of this module will need to be edited to omit these versions. * If creating customisations for FIX 5.0 or later, consider continuing to depend on the `org.quickfixj:quickfixj-messages-fixt11` artefact published by the QuickFIX/J project. This dependency should be stable. * The structure of these modules can be refactored to meet your requirements. This build has a complex structure to normalise the ```quickfixj-messages-all``` into a set of more minimal artefacts for specific FIX versions. This complexity should be unnecessary for more specialised and compact Rules of Engagement. One practical approach is to remove unnecessary dependencies from ```quickfixj-messages-all``` and build a single artefact per Rules of Engagement. This artefact can have a new ```groupId``` and ```artefactId``` as aforementioned. * FIX versions **FIX4.0 to FIX5.0sp2** * Edit the QuickFIX dictionary for the FIX protocol version that you are customising. The dictionary is found in ```/src/main/resources``` directory of the module corresponding to the FIX protocol version. - * **N.B.** [FIX Trading Community](https://www.fixtrading.org/) does publish repositories for FIX 4.2 and FIX 4.4 but these are not used by the QuickFIX/J build. These may be used as the basis of a customised build. + * **N.B.** [FIX Trading Community](https://www.fixtrading.org/) does publish repositories for FIX 4.2 and FIX 4.4 but these are not used by the QuickFIX/J build but they may be used as the basis of a customised build. * FIX Latest: * The [quickfixj-orchestration](../quickfixj-orchestration/readme.md) module publishes a QuickFIX/J compatible __FIX Latest__ orchestration as ```org.quickfixj:quickfixj-orchestration```. This can be a starting point for customisation. Please note that this is a complete representation of the FIX Latest specification and results in a very large distribution.The purpose of [FIX Orchestra](https://www.fixtrading.org/standards/fix-orchestra/) is to provide a machine-readable Rules of Engagement. __FIX Latest__ is a very large distribution so customisation is **expected**. See [quickfixj-orchestration](../quickfixj-orchestration/readme.md) for references to [FIX Trading Community](https://www.fixtrading.org/) tools. - * A custom orchestration should be used in place of the ```org.quickfixj:quickfixj-orchestration``` dependency to build the messages. - * The ```quickfixj-messages-all``` maven build includes a ```minimal-fix-latest``` profile. The purpose of this profile is to minimise the size of FIX Latest packages. The minimal packages will include only those Fields, Components and Messages on which tests in the ```quickfixj-core``` module depend. This is done to reduce memory requirements and speed up the build of QuickFIX/J. This profile may serve as a very simple example of customising an orchestration using ```xslt```. This profile serves no purpose in a custom build of Messages and Fields. If you are not building ```quickfixj-core``` the ```minimal-fix-latest``` profile can be removed. + * A custom orchestration dependency should be used in place of the ```org.quickfixj:quickfixj-orchestration``` dependency. + * The ```quickfixj-messages-all``` maven build includes a ```minimal-fix-latest``` profile. The minimal packages include only those Fields, Components and Messages on which tests in the ```quickfixj-core``` module (and some basic compilation verifications) depend. This is done to reduce memory requirements and speed up the build of QuickFIX/J during development of QuickFIX/J itself. The ```minimal-fix-latest``` profile may serve as a very simple example of customising an orchestration using ```xslt```. This profile serves no purpose in a custom build of Messages and Fields. The ```minimal-fix-latest``` is not expected to be useful for building custom orchestrations. ## QuickFIX/J Build Dependencies diff --git a/quickfixj-orchestration/readme.md b/quickfixj-orchestration/readme.md index 7b3bc21097..1ef7e31385 100644 --- a/quickfixj-orchestration/readme.md +++ b/quickfixj-orchestration/readme.md @@ -2,7 +2,7 @@ QuickFIX/J support for FIX Orchestra ![](./FIXorchestraLogo.png) -The module publishes a QUICKFIX/J compatible FIX dictionary and a QUICKFIX/J FIX "orchestration". +This module publishes a QUICKFIX/J compatible FIX dictionary and a QUICKFIX/J FIX "orchestration". An "orchestration" is an implementation of a FIX Orchestra standard repository. This module depends on the FIX Latest standard "orchestration" published by the FIX Trading Community. @@ -16,7 +16,7 @@ The published artefact can also be the basis of a custom implementation of FIX L The complete FIX Latest specification results in a very large distribution. This project builds the entire specification to prove compatibility. -Customisation is advisable to use FIX Latest for an integration. This will allow a more clear representation of the Rules of Engagement, and aids maintainability as well as speeding build time and reducing memory requirements for the build. +Customisation is advisable when using FIX Latest for an integration. This allows a more concise representation of the Rules of Engagement, and aids maintainability as well as speeding build time and reducing memory requirements for the build. See [QuickFIX/J Messages](./quickfixj-messages/readme.md) for details of the build and recommendations of how to implement custom builds.