From d3f7efef97a7601b4f1044aac706e0c54f6a26b1 Mon Sep 17 00:00:00 2001 From: Ian Young Date: Mon, 18 Jun 2012 19:44:17 +0000 Subject: [PATCH] Initial conversion to Markdown. --- mdx/conventions.md | 77 ++++++++++++++++++++++++++++++++++++++++++ mdx/conventions.txt | 82 --------------------------------------------- 2 files changed, 77 insertions(+), 82 deletions(-) create mode 100644 mdx/conventions.md delete mode 100644 mdx/conventions.txt diff --git a/mdx/conventions.md b/mdx/conventions.md new file mode 100644 index 00000000..b9d6b173 --- /dev/null +++ b/mdx/conventions.md @@ -0,0 +1,77 @@ +# Conventions for the `/mdx/` directory tree. + +Each directory under `/mdx/` represents a source of metadata, referred to as a +channel. Each channel is named in the form "country_source", for example: +`us_incommon` is the channel name for the US's InCommon federation. Exceptions are made for the UK federation, whose channel is just +called `uk`, and for channels not associated with particular countries, which +are named as "int_source", for example `int_edugain`. + +Each channel contains a number of Spring bean configuration files. The +`beans.xml` file is present in all channels. In addition a channel may provide a +`verbs.xml` and/or `.xml` files implementing channel-specific verbs. For example, a file called `test.xml` would be one place where you could put a verb called `test`. + +## `beans.xml` conventions + +Most beans defined within a channel appear in a `beans.xml` configuration file +within the channel directory. + +As well as being available to channel-local operations, these beans are +available to operations involving more than one channel. Therefore, all beans +defined in `beans.xml` should be named with the channel name as a prefix in +order to avoid clashes when beans from more than one channel are brought +together at run time. For example, a bean which would naturally be called +`productionAggregate` would be named `us_incommon_productionAggregate` within +the `us_incommon` channel, `se_swamid_productionAggregate` within the +`se_swamid` channel and so on. + +All beans defined in `beans.xml` should be set as `lazy-init="true"`. All +aggregator component beans should additionally declare +`init-method="initialize"`. + +## Common `beans.xml` channel beans + +channel_productionAggregate is a stage that fetches the source's production +aggregate + +channel_exportAggregate is a stage that fetches the source's export aggregate. +Omitted if the source doesn't have an export aggregate. + +channel_signingCertificate + +channel_checkSignature + +channel_exportedEntities is a composite stage which returns the source's +exported entities as a collection. If the source doesn't have an export +aggregate, it may instead derive a pseudo export collection from the +production aggregate. + +## `verbs.xml` and `.xml` conventions + +Verbs are operations that can be directly executed by the aggregator CLI. They +are implemented as aggregator pipeline objects named by the verb they +implement, without qualification by the channel name. A qualified name is not +required in this case because verbs are never called from other channels, only +from the CLI. + +Verbs are defined either in a file named after the verb (e.g., `collect.xml`, +`import.xml`) or in a `verbs.xml` file. The Ant build file looks for a +specifically-named file first, then falls back to the `verbs.xml` file. + +For example, executing the `import` verb on the `us_incommon` channel involves +looking for an `import.xml` file in the `us_incommon` directory. If this is +found, the `import` pipeline in `/mdx/us_incommon/import.xml` is invoked; +otherwise, the CLI is invoked on the `import` pipeline in +`/mdx/us_incommon/verbs.xml`. + +Verb definition files should import the channel's `beans.xml` file as well as +the `common-beans.xml` file from the parent `/mdx/` directory through a relative +path. + +Verb definition files should not import each other; any beans required to be +shared between verb definition files should be moved into the channel's +`beans.xml` file and given an appropriately channel-qualified name. + +All aggregator component beans declared within a verb definition file should +declare `init-method="initialize"`. If more than one verb is defined in a +`verbs.xml` file, all beans within the file should also be set as +`lazy-init="true"`. diff --git a/mdx/conventions.txt b/mdx/conventions.txt deleted file mode 100644 index f108e358..00000000 --- a/mdx/conventions.txt +++ /dev/null @@ -1,82 +0,0 @@ -Conventions for the /mdx/ directory tree. -========================================= - -Each directory under /mdx/ represents a source of metadata, referred to as a -channel. Each channel is named in the form "country_source", for example: -us_incommon. Exceptions are made for the UK federation, whose channel is just -called "uk", and for channels not associated with particular countries, which -are named as "int_source", for example "int_edugain". - -Each channel contains a number of Spring bean configuration files. The -beans.xml file is present in all channels, in addition a channel may provide a -verbs.xml and/or .xml files implementing channel-specific verbs. - -beans.xml conventions -===================== - -Most beans defined within a channel appear in a beans.xml configuration file -within the channel directory. - -As well as being available to channel-local operations, these beans are -available to operations involving more than one channel. Therefore, all beans -defined in beans.xml should be named with the channel name as a prefix in -order to avoid clashes when beans from more than one channel are brought -together at run time. For example, a bean which would naturally be called -"productionAggregate" would be named "us_incommon_productionAggregate" within -the "us_incommon" channel, "se_swamid_productionAggregate" within the -"se_swamid" channel and so on. - -All beans defined in beans.xml should be set as lazy-init="true". All -aggregator component beans should additionally declare -init-method="initialize". - -common beans.xml channel beans -============================== - -channel_productionAggregate is a stage that fetches the source's production -aggregate - -channel_exportAggregate is a stage that fetches the source's export aggregate. -Omitted if the source doesn't have an export aggregate. - -channel_signingCertificate - -channel_checkSignature - -channel_exportedEntities is a composite stage which returns the source's -exported entities as a collection. If the source doesn't have an export -aggregate, it may instead derive a pseudo export collection from the -production aggregate. - -verbs.xml and .xml conventions -==================================== - -Verbs are operations that can be directly executed by the aggregator CLI. They -are implemented as aggregator pipeline objects named by the verb they -implement, without qualification by the channel name. A qualified name is not -required in this case because verbs are never called from other channels, only -from the CLI. - -Verbs are defined either in a file named after the verb (e.g., "collect.xml", -"import.xml") or in a "verbs.xml" file. The Ant build file looks for a -specifically-named file first, then falls back to the verbs.xml file. - -For example, executing the "import" verb on the "us_incommon" channel involves -looking for an "import.xml" file in the "us_incommon" directory. If this is -found, the "import" pipeline in /mdx/us_incommon/import.xml is invoked; -otherwise, the CLI is invoked on the "import" pipeline in -/mdx/us_incommon/verbs.xml. - -Verb definition files should import the channel's beans.xml file as well as -the common-beans.xml file from the parent /mdx/ directory through a relative -path. - -Verb definition files should not import each other; any beans required to be -shared between verb definition files should be moved into the channel's -beans.xml file and given an appropriately channel-qualified name. - -All aggregator component beans declared within a verb definition file should -declare init-method="initialize". If more than one verb is defined in a -verbs.xml file, all beans within the file should also be set as -lazy-init="true". -