The Oracle Integration Repository is a centralized repository that contains numerous integration interface endpoints exposed by applications throughout the entire Oracle E-Business Suite. The Integration Repository is populated by the parsing of annotated source code files. Source code files are the "source of truth" for Integration Repository metadata, and it is vitally important that they are annotated in a prescribed and standardized fashion.
This section describes what you should know in general about Integration Repository annotations, regardless of the source code file type that you are working with.
Annotations are modifiers that contain an annotation type and zero or more member-value pairs. Each member-value pair associates a value with a different member of the annotation type.
The annotation syntax is similar to Javadoc syntax:
@NameSpace:TypeName keyString
@NameSpace:TypeName freeString
@NameSpace:TypeName keyString keyString keyString
@NameSpace:TypeName keyString freeString
@NameSpace:TypeName {inline annotation} {inline annotation}
Element Definitions
NameSpace identifies the group of annotations that you are using. It is case sensitive. The annotations currently in use are in the rep namespace. Future annotations may be introduced in different namespaces.
TypeName identifies the name of the annotation type. It is case sensitive. For consistency across product teams, always use lowercase typenames.
keyString is the first word that follows the annotation. It is a whole string that excludes spaces.
freeString is a string that follows the keystring. It may have spaces or inline annotations. It is terminated at the beginning of the next annotation or at the end of the documentation comment.
Format Requirement
In your source code file, repository annotations will appear as a Javadoc-style block of comments.
Use the following general procedure. (If you are working in Java and your file already has robust Javadoc comments, then in many cases you'll only need to add the appropriate "@rep:" tags.)
Choose which interfaces you will expose to the Integration Repository. Be mindful that you can annotate interfaces as public, private, or internal, as well as active, obsolete, deprecated, or planned.
Only interfaces that you annotate as public will appear in the external Integration Repository UI; private and internal interfaces will appear in an internal-only Oracle UI. Consequently, all interfaces that have previously been documented as public in customer manuals should be defined as public in your source file annotations.
In your source file, set off the beginning of the annotation block according to the following conditional rule:
For Java, insert "slash-star-star" characters (/**).
For non-Java files, insert "slash-star-pound" characters (/*#).
Enter a text description. Use complete sentences and standard English.
Where applicable, add plain Javadoc tags such as @param and @return.
Next, add "@rep:" tags such as @rep:scope and @rep:product.
Optionally, add a nonpublishable comment using the @rep:comment annotation. (Use for reminders, notes, and so on. The parsers skip this annotation.)
End the annotation block with a "star-slash" (*/).
Refer to the following example. Note that the first line could alternatively be slash-star-pound (/*#) if the source file was PL/SQL or another non-Java technology.
/**
* This is the first sentence of a description of a sample
* interface. This description can span multiple lines.
* Be careful for public interfaces, where the description is
* displayed externally in the Integration Repository UI.
* It should be reviewed for content as well as spelling and
* grammar errors. Additionally, the first sentence of
* the description should be a concise summary of the
* interface or method, as the repository UI will display
* the first sentence by itself.
*
* @param <param name> <parameter description>
@rep:paraminfo {@rep:innertype <typeName>} {@rep:precision <value>} {@rep:required}
* @rep:scope <public | internal | private>
* @rep:product <product short code>
* @rep:displayname Sample Interface
*/
Annotation Syntax Checker and iLDT Generator
A syntax checker is available at the following directory: $IAS_ORACLE_HOME/perl/bin/perl $FND_TOP/bin/irep_parser.pl
Details about the checker can be found by using the -h flag.
Class Level vs. Method Level
For the purpose of classifying annotation requirements, we are using loose definitions of the terms "class" and "method". In the context of interface annotations, PL/SQL packages are thought of as classes, and PL/SQL functions or procedures are thought of as methods. For some technologies there are different annotation requirements at the class level and the method level. See the "Required" and "Optional" annotation lists below for details.
Concurrent Program Considerations
In cases where a Concurrent Program (CP) is implemented with an underlying technology that is also an interface type (such as a PL/SQL or Java CP) there may be some confusion as to what needs to be annotated.
Assuming that you intend to have the Concurrent Program exposed by the repository, you should annotate the Concurrent Program. Do not annotate the underlying implementation (such as PL/SQL file) unless you intend to expose it separately from the concurrent program in the repository.
The annotation standards are discussed in this chapter: