Glossary of Annotations

The following is a list of currently supported annotation types and details about their recommended use.

<description sentence(s)>

Annotation Type <description sentence(s)>
Syntax Does not require a tag.
Usage Defines a user-friendly description of what the interface or method does.
Start the description with a summary sentence that begins with a capital letter and ends with a period. Do not use all capitals) and do not capitalize words that are not proper nouns.
An example of a good beginning sentence could be as follows:
"The Purchase Order Data Object holds the purchase order data including nested data objects such as lines and shipments."
In general, a good description has multiple sentences and would be easily understood by a potential customer. An exception to the multiple sentence rule is cases where the package-level description provides detailed context information and the associated method-level descriptions can therefore be more brief (to avoid repetitiveness).
A bad example would be: "Create an order."
This description is barely usable. A better one would be:
"Use this package to create a customer order, specifying header and line information."
You can use the <br> tag for forcing a new line in description. The following is an example on how to force a new line in the description:
The following is an example on how to force a new line in the description:
FEM_BUDGETS_ATTR_T is an interface table for loading and updating Budget attribute assignments using the Dimension Member Loader. <br> These attribute assignments are properties that further describe each Budget. <br> When loading Budgets using the Dimension Member Loader, identify each new member in the FEM_BUDGETS_B_T table while providing an assignment row for each required attribute in the FEM_BUDGETS_ATTR_T table.
Example 
/*#
 * This is a sample description. Use 
 * standard English capitalization and 
 * punctuation. Write descriptions
 * carefully.
Required Required for all interfaces that have @rep:scope public.
Default If not set, the value is defaulted from the Javadoc or PL/SQL Doc of the interface or method.
Level Interface (class) and API (method).
Multiple Allowed No. Use only one per each program element (class or method).
Comments Optionally, you can use the following HTML tags in your descriptions:
<body>
<p>
<strong>
<em>
<ul>
<li>
<h1>
<h2>
<h3>

<pre> for multiple code samples (should be enclosed by <code> tags)

@rep:scope

Annotation Type @rep:scope
Syntax @rep:scope public | private | internal
Usage Indicates where to publish the interface, if at all.
Example @rep:scope public means publish everywhere.

Note: Public interfaces are displayed on the customer-facing UI.


@rep:scope private means that this interface is published to the Integration Repository but restricted for use by the owning team.
@rep:scope internal means publish within the company.
Required Required for all interfaces.
Default None.
Level Interface (class) and API (method).
Multiple Allowed No. Use only one per each program element (class or method).

@rep:product

Annotation Type @rep:product
Syntax @rep:product StringShortCode
Usage Specifies the product shortname of the interface.
Example @rep:product PO
Required Required for all interfaces.
Default None.
Level Interface (class) only.
Multiple Allowed No. Use only one per interface.

@rep:implementation

Annotation Type @rep:implementation
Syntax @rep:implementation StringClassName
Usage Specifies the implementation class name of the interface.
Example @rep:implementation oracle.apps.po.server.PurchaseOrdersAmImpl
Required Required for Java only.
Default None.
Level Interface (class).
Multiple Allowed No. Use only one per interface.

@rep:displayname

Annotation Type @rep:displayname
Syntax @rep:displayname StringName
Usage Defines a user-friendly name for the interface.
Example @rep:displayname Purchase Order Summary
Required Required for all interfaces that have @rep:scope public.
Default None.
Level Interface (class) and API (method).
Multiple Allowed No. Use only one per each program element (class or method).
Comments Display Name Guidelines
These guidelines apply to display names for all technologies (interfaces, classes, methods, parameters, XMLG maps, and so on).
Display names must meet the following criteria:

  • Be mixed case. Do not use all capitals or all lower case.

  • Be singular rather than plural. For example, use "Customer" instead of "Customers".

  • Be fully qualified and representative of your business area.

  • Not have underscores (_).

  • Not end with a period (.).

  • Not be the same as the internal name.

  • Not begin with a product code or product name.

  • Not contain obvious redundancies such as "Package", "API", or "APIs". As you write your display names, do consider the UI where the display name will be seen.


For example, use 'Promise Activity' as the display name, instead of IEX_PROMISES_PUB. The reason is that IEX_PROMISES_PUB contains underscores and is the same as the internal name.
Use 'Process Activity' as the display name, instead of 'Workflow Process Activity APIs'. This is because it begins with a product name and ends with "APIs".

@rep:lifecycle

Annotation Type @rep:lifecycle
Syntax @rep:lifecycle active | deprecated | obsolete | planned
Usage Indicates the lifecycle phase of the interface.
Example @rep:lifecycle active means the interface is active.
@rep:lifecycle deprecated means the interface has been deprecated.
@rep:lifecycle obsolete means the interface is obsolete and must not be used.
@rep:lifecycle planned means the interface is planned for a future release. This is used for prototypes and mockups.
Required Optional.
Default The default value is active.
Level Interface (class) and API (method).
Multiple Allowed No. Use only one per each program element (class or method).
Comments The parsers will validate that this annotation is in sync with the "@deprecated" Javadoc annotation.

@rep:compatibility

Annotation Type @rep:compatibility
Syntax @rep:compatibility S | N
Usage S indicates the lifecycle phase of the interface.
N indicates that backward compatibility is not assured.
Example @rep:compatibility S
Required Optional.
Default Conditional. The value is defaulted to S for @rep:scope public. Otherwise, the value is defaulted to N.
Level Interface (class) and API (method).
Multiple Allowed No. Use only one per each program element (class or method).

@link

Annotation Type @link

Note: This is supported only for a destination of Java.
Syntax {@link package.class#member label}
Usage Provides a link to another interface or method.
Example {@link #setAmounts(int,int,int,int) Set Amounts}
Required Optional.
Default None.
Level Interface (class) and API (method).
Multiple Allowed Yes.
Comments This is the standard Javadoc "@link" annotation, where the linked items are embedded as hyperlinks in the description that displays in the UI.
Take note of the following rules: Public APIs must not link to private or internal APIs. @link annotations must not link to documents that are not accessible by the Integration Repository viewer.

@see

Annotation Type @see
Syntax @see StringLocator
Usage Provides a link to another interface or method.
Example @see #setAmounts(int,int,int,int)
Required Optional.
Default None.
Level Interface (class) and API (method).
Multiple Allowed Yes.
Comments This is the standard Javadoc "@see" annotation.
The linked items will display on the UI under a "See Also" heading.
Usage in PL/SQL Code: @see package#procedure

@rep:ihelp

Annotation Type @rep:ihelp
Syntax When used as a separate child annotation on a single line:
@rep:ihelp <product_shortname>/@<help_target>#<help_target> <link_text>
When used as an inline annotation, add curly braces:
{@rep:ihelp <product_shortname>/@<help_target>#<help_target> <link_text>}
Usage Provides a link to an existing HTML online help page.
product_shortname is the product short name.
help_target is the help target that was manually embedded in the file by the technical writer, such as, "jtfaccsum_jsp," "aolpo," "overview," "ast_aboutcollateral".
For more information on how to customize Oracle E-Business Suite help, see Setting Up Oracle E-Business Suite Help, Oracle E-Business Suite Setup Guide.
Example @rep:ihelp #setAmounts(int,int,int,int)
Required Optional.
Default None.
Level Interface (class) and API (method).
Multiple Allowed Yes.

@rep:metalink

Annotation Type @rep:metalink
Syntax When used as a separate child annotation on a single line:
@rep:metalink <bulletin_number> <link_text>
When used as an inline annotation, add curly braces:
{@rep:metalink <bulletin_number> <link_text>}
Usage Provides a link to an existing My Oracle Support (formerly OracleMetaLink) Knowledge Document.
Example @rep:metalink 123456.1 See My Oracle Support Knowledge Document 123456.1
Required Optional.
Default None.
Level Interface (class) and API (method).
Multiple Allowed Yes.

@rep:category

Annotation Type @rep:category
Syntax

  • @rep:category BUSINESS_ENTITY BUSINESS_ENTITY_CODE

  • @rep:category IREP_CLASS_SUBTYPE JAVA_BEAN_SERVICES

  • @rep:category IREP_CLASS_SUBTYPE AM_SERVICES

Usage

  • Specifies the business category of the interface.

  • Indicates a Java API as a serviceable interface.

  • Indicates an Application Module class as a serviceable interface.

Example

  • @rep:category BUSINESS_ENTITY PO_PLANNED_PURCHASE_ORDER

    PO_PLANNED_PURCHASE_ORDER is your business entity code and your display name for example could be "Planned Purchase Order".

  • @rep:category IREP_CLASS_SUBTYPE JAVA_BEAN_SERVICES

    "Java Bean Services" can be displayed as a subtype of a Java API.

  • @rep:category IREP_CLASS_SUBTYPE AM_SERVICES

    "Application Module Services" can be displayed as a subtype of a Java API.

See Business Entity Annotation Guidelines for additional details.
Required

  • BUSINESS_ENTITY is mandatory for all interfaces. If the methods belonging to a class ALL have the same business entity, you only need to annotate the class. However, if the methods belonging to a class have heterogeneous business entities, then you have to annotate each of the methods appropriately.

  • IREP_CLASS_SUBTYPE JAVA_BEAN_SERVICES annotation is mandatory for all Java interfaces that need to be identified as a serviceable Java API.

  • IREP_CLASS_SUBTYPE AM_SERVICES annotation is mandatory for an Application Module that needs to be identified as a serviceable API.

Default None
Level BUSINESS_ENTITY is applicable for both class level and method level. However, JAVA_BEAN_SERVICES and AM_SERVICES are applicable only for class level.
Multiple Allowed Yes.
Comments You are encouraged to use the rep:category annotation liberally in your code.

@rep:usestable

Annotation Type @rep:usestable
Syntax @rep:usestable <table or view name> <sequence> <direction flag>
Usage Used when annotating concurrent programs to identify associated open interface tables or views.
<table or view name> is the name of the table or view.
<sequence> is an integer used to tell the UI the display order of the different pieces. By convention, in the rep:category OPEN_INTERFACE annotation, you will have used 1 for the concurrent program. Here in the rep:usestable annotations, order the input tables: list master (header) tables before detail (lines) tables. Finally, put any output views or tables at the end of the sequence.
<direction flag> is optional and specifies one of the following: IN (default), OUT, or BOTH.
Example @rep:usestable SampleTable 3 IN
Required Only if the concurrent program is part of an open interface.
Default None.
Level Interface.
Multiple Allowed Yes.

@rep:standard

Annotation Type @rep:standard
Syntax @rep:standard StringType StringVersionNumber StringSpecName
In the following example @rep:standard OAG 7.2 Process_PO_001 StringType is OAG, StringVersionNumber is 7.2 and StringSpecName is Process_PO_001
See Annotation Syntax for details about this annotation's syntax.
Usage Specifies the business standard name. This annotation is reserved for where Oracle is compliant with industry standards.
Example In the example @rep:standard RosettaNet 02.02.00 'Pip3B12-Shipping Order Confirmation, the StringSpecName is enclosed in Single Quotes because the spec name has empty spaces. It is not necessary to have these quotes if the StringSpecName does not have any empty spaces like the following example @rep:standard RosettaNet 02.02.00 Pip3B12-PurchaseOrderConfirmation.
Required Optional.
Default Methods default to the value set on the class.
Level Documents and data rows.
Multiple Allowed No. Use only one per each program element (class or method).

@rep:httpverb

Annotation Type @rep:httpverb
Syntax @rep:httpverb <HTTP_Method_Types>
Use a comma separated list of the HTTP verbs (GET and POST) at the method level.

Note: GET and POST are the supported HTTP methods for Java Bean Services and Application Module Services in this release.

Usage Use this annotation to indicate the HTTP Verbs suitable for the current method or operation.
If a method is not annotated with POST httpverb, the POST check box is still active by default in the selected interface details page. This allows an integration administrator to select the POST verb for that method if needed before service deployment. However, unlike the POST HTTP verb, if a method is not annotated with GET httpverb, then the GET check box becomes inactive or disabled for that method. This means that method will not be exposed as REST service with GET operation.
This annotation is available for Java files only.
Example The comma separate list can be used in the following ways:
@rep:httpverb get
@rep:httpverb post
@rep:httpverb get, post
Required Optional.
Default None.
Level Method level
Multiple Allowed No. Use only one per method.
Comments Use this annotation to optimize the HTTP method such as GET and POST.

@rep:interface

Annotation Type @rep:interface
Syntax @rep:interface StringClassName where the StringClassName syntax is transactiontype:subtype. Refer to the example below.
Usage Specifies the interface name for technologies where parsing tools can't easily introspect the interface name.
Example The StringClassName is always transactiontype:subtype
@rep:interface PO:POC
Required Optional.
Default None.
Level Interface only.
Multiple Allowed No. Use only one per interface.
Comments Used in technologies where there isn't a strong native definition of the interface, such as XML Gateway and e-Commerce Gateway

@param

Annotation Type @param
Syntax @param paramName paramDescription
Usage Specifies the name and description of a method, procedure, or function parameter (IN, OUT, or both).
Example @param PONumber The purchase order number.
Required Optional.
Default None.
Level Methods, procedures and functions.
Multiple Allowed Yes.
Comments For convenience, Java annotations are also supported.

@return

Annotation Type @return
Syntax @return StringDescription
Usage Specifies the description of a method or function return parameter.
Example @return The purchase order status.
Required Optional.
Default None.
Level Methods, procedures and functions.
Multiple Allowed Yes.
Comments For convenience, Java annotations are also supported.

@rep:paraminfo

Annotation Type @rep:paraminfo
Syntax @rep:paraminfo {@rep:innertype typeName} {@rep:precision value} {@rep:required} {@rep:key_param}
Usage rep:paraminfo
The rep:paraminfo annotation must come immediately in the line following the parameter's @param or @return annotation it is describing.
rep:innertype
Optional inline annotation to describe the inner type of generic objects such as collections.
rep:precision
Optional inline annotation to specify the parameter precision. Used for Strings and numbers.
rep:required
Optional inline annotation to indicate that a not null must be supplied. This is only needed for non-PL/SQL technologies.
rep:key_param
Optional inline annotation to define a parameter as a key parameter or path variable for REST services. It is applicable for Java or Application Module methods. If this annotation is used, then rep:required must be present. Additionally, this annotation is not applicable to rep:paraminfo after @return annotation.
Example 
/**
 * Gets the price for a purchase order line item.
 *
 * @param poNumber purchase order unique identifier
 * @paraminfo {@rep:precision 10} {@rep:required} {@rep:key_param}
 * @param lineNumber purchase order line unique identifier
 * @paraminfo {@rep:precision 10} {@rep:required}
 * @return the item price for the given purchase order line
 * @paraminfo {@rep:precision 10}
 *
 * @rep:scope public
 * @rep:displayname Get Purchase Order Line Item Price
 */
public Number getItemPrice(Number poNumber, Number lineNumber);
Required Optional.
Default None.
Level Methods only.
Multiple Allowed Yes. Multiple values can be assigned for different parameters.

@rep:businessevent

Annotation Type @rep:businessevent
Syntax @rep:businessevent BusinessEvent
Usage Indicates the name of the business event raised by this method.
Example @rep:businessevent oracle.apps.wf.notification.send
Required Optional.
Default Defaulted in file types where the business event can be derived.
Level Methods only.
Multiple Allowed Yes.
Comments Make sure to use this annotation at every instance where you raise a business event. Note that business events themselves do not require an annotation.

@rep:direction

Annotation Type @rep:direction
Syntax @rep:direction <OUT | IN>
Usage Indicates whether the interface is outbound or inbound.
Example @rep:direction OUT
Required Required for EDI and XML Gateway annotations only.
Default None.
Level Interface.
Multiple Allowed No.

@rep:service

Annotation Type @rep:service
Syntax @rep:service
Usage Indicates that a Java file is a business service object (BSO).
Use this tag as it is in your Java file. Refer to the Example section below. It takes no parameters.
Example 
 /**
* The Purchase Order service lets you to view, update, acknowledge and
* approve purchase orders. It also lets you receive items, and obtain
* pricing by line item.
*
* @see oracle.apps.fnd.framework.toolbox.tutorial.PurchaseOrderSDO
* @see oracle.apps.fnd.framework.toolbox.tutorial.PurchaseOrderAcknowledgementsSDO
* @see oracle.apps.fnd.framework.toolbox.tutorial.PurchaseOrderReceiptsSDO
*
* @rep:scope public
* @rep:displayname Purchase Order Service
* @rep:implementation oracle.apps.fnd.framework.toolbox.tutorial.server.PurchaseOrderSAMImpl
* @rep:product PO
* @rep:category BUSINESS_ENTITY PO_PURCHASE_ORDER
* @rep:service 
*/
Required Required for Business Service Objects.
Default None.
Level Class.
Multiple Allowed No.

@rep:servicedoc

Annotation Type @rep:servicedoc
Syntax @rep:servicedoc
Usage Indicates that a Java file is an SDO (as opposed to a normal Java API). Use this tag as is in your java file. Refer to the example section below. It takes no parameters.
Example 
 /**
* The Purchase Order Data Object holds the purchase order data including
* nested data objects such as lines and shipments.
*
* @see oracle.apps.fnd.framework.toolbox.tutorial.PurchaseOrderLineSDO
*
* @rep:scope public
* @rep:displayname Purchase Order Data Object
* @rep:product PO
* @rep:category BUSINESS_ENTITY PO_PURCHASE_ORDER
* @rep:servicedoc
*/
Required Required for Service Data Objects.
Default None.
Level Class.
Multiple Allowed No.
Comments Developers do not need to enter this annotation because it is automatically generated.

@rep:synchronicity

Annotation Type @rep:synchronicity
Syntax @rep:synchronicity <SYNCH or ASYNCH>
Usage Specifies synchronous or asynchronous behavior.
Example @rep:synchronicity SYNCH
Required Optional.
Default Is defaulted based on module type. For example, ASYNCH for XML Gateway and SYNCH for Business Service Object.
Level Class or method.
Multiple Allowed No.

@rep:appscontext

Annotation Type @rep:appscontext
Syntax @rep:appscontext <NONE, APPL, RESP, USER, NLS, or ORG>
Usage Specifies the context required to execute the method.
Example @rep:appscontext USER
Required Optional.
Default NONE
Level Method.
Multiple Allowed No, only one allowed per method.

@rep:comment

Annotation Type @rep:comment
Syntax @rep:comment <comment>
Usage This annotation is skipped by the parsers. It is for use by product teams when a non-published comment is desired.
Example @rep:comment This is a sample comment.
Required Optional.
Default None.
Level Any.

@rep:primaryinstance

Annotation Type @rep:primaryinstance
Syntax @rep:primaryinstance
Usage To indicate the primary instance of an overloaded method or procedure.
Required Required for all overloaded methods and procedures.
Default None.
Level Method or procedure.
Multiple Allowed No.
Comments The primary instance's display name and description will be used in the browser UI when a list of methods is displayed. The non-primary instances (such as, the overloads) should have descriptions that emphasize how they differ from the primary (such as, "This variant allows specification of the org_id."). The non-primary display names and descriptions will only be displayed when viewing the details of the overloaded interface.

@rep:usesmap

Annotation Type @rep:usesmap
Syntax @rep:usesmap <map_name> <sequence_number>
Usage To indicate the E-Commerce Gateway maps that are associated with a concurrent program.
<map_name> where map_name is the default map name.
<sequence_number> is an integer used to tell the UI the display order of the different pieces.
Example @rep:usesemap SampleMap 2
Required Optional.
Default None.
Level Any.
Multiple Allowed Yes.
Comments The default map name has the following naming convention "EC_XXXX_FF" where XXXX is the 4-letter acronym for your transaction.