Users will place their annotations in Javadoc comments, immediately before the declaration of the class or method.
must begin with description sentence(s)
Only required for Java business service objects; not required for plain Java or SDOs.
Use BUSINESS_ENTITY at the class level only if all underlying methods have the same business entity. In those cases, you do not need to repeat the annotation at the method level.
Use IREP_CLASS_SUBTYPE JAVA_BEAN_SERVICES at the class level to indicate that a Java API is serviceable. For more information, see Annotations for Java Bean Services.
Use IREP_CLASS_SUBTYPE AM_SERVICES at the class level to indicate that an Application Module class of a Java API is serviceable. See Annotations for Application Module Services.
must begin with description sentence(s)
Use only when applicable and when other tags such as @see and @rep:metalink do not provide parameter explanations.
return (if applicable)
Use parameter level annotation @rep:paraminfo {@rep:required} {@rep:key_param} for Java APIs as REST services. See: Annotations for Java Bean Services and Annotations for Application Module Services.
rep:businessevent (if an event is raised)
Use BUSINESS_ENTITY at the method level only when a class methods have heterogeneous business entities.
Use this annotation to specify the HTTP Verbs suitable for a Java method. See: Annotations for Java Bean Services and Annotations for Application Module Services.
Not all Java APIs registered in the Integration Repository can be exposed as REST services. Only Java API parameters that are either serializable Java Beans or simple data types such as String, Int, and so forth can be exposed as Java Bean Services.
In addition to existing Java specific annotations, add the following optional annotations in a .Java file to annotate Java APIs as REST services:
@rep:category IREP_CLASS_SUBTYPE JAVA_BEAN_SERVICES
This class-level annotation marks a Java API as a serviceable interface.
It is applicable for .Java files only.
For more information, see rep:category.
@rep:httpverb <comma separated list of HTTP VERBS - GET, POST>
This method-level annotation explicitly identifies the HTTP verbs suitable for a method or an operation.
For more information, see: rep:httpverb.
@rep:paraminfo {@rep:required} {@rep:key_param}
This parameter-level annotation marks path variables.
@rep:key_param is an inline annotation added to an existing @rep:paraminfo annotation.
For more information, see: rep:paraminfo.
Similar to Java Bean Services, a system integration developer needs to add the following optional annotations to annotate Application Module Implementation java class which is a .java file for Application Module Services:
@rep:category IREP_CLASS_SUBTYPE AM_SERVICES
This class-level annotation marks an Application Module as a serviceable interface.
It is applicable for .Java files only.
For more information, see rep:category.
@rep:httpverb <comma separated list of HTTP VERBS - GET, POST>
As mentioned earlier for the Java Bean Services, this method-level annotation explicitly identifies the HTTP verbs suitable for a method or an operation.
See: rep:httpverb.
@rep:paraminfo {@rep:required} {@rep:key_param}
Similar to the annotations for Java Bean Services, this parameter-level annotation marks path variables.
See: rep:paraminfo.
Once the system integration developer completes the annotation for the Application Module Services, the annotated interface definition needs to be validated through the Integration Repository Parser (IREP Parser). If no error occurs during the validation, an Integration Repository loader file (iLDT ) can be generated. An integration repository administrator can then upload the iLDT file to the Integration Repository using FNDLOAD.
You can use the following template when annotating Application Module Services:
Interface Template:
/**
* < Interface description
* ...
* >
*
* @rep:scope <public>
* @rep:product <product code>
* @rep:displayname <Interface display name>
* @rep:lifecycle <active|deprecated|obsolete|planned>
* @rep:category IREP_CLASS_SUBTYPE AM_SERVICES
* @rep:category BUSINESS_ENTITY <business_entity_code> <sequenceNumber>
*/
Methods Template:
/**
* < Method description
* ...
* >
*
* @param <paramName> < Parameter description
* ... >
* @rep:paraminfo {@rep:innertype <typeName>} {@rep:precision <value>} {@rep:required} {@rep:key_param}
*
*
* @return < Parameter description
* ... >
* @rep:paraminfo {@rep:innertype <typeName>} {@rep:precision <value>} {@rep:required}
*
*
* @rep:scope <public|private|internal>
* @rep:displayname <Interface display name>
* @rep:httpverb <GET|POST|GET,POST>
* @rep:lifecycle <active|deprecated|obsolete|planned>
* @rep:category BUSINESS_ENTITY <business_entity_code> <sequenceNumber>
*/
You can use the following template when annotating Java Bean Services:
Interface Template:
/**
* < Interface description
* ...
* >
*
* @rep:scope <public>
* @rep:displayname <Interface display name>
* @rep:product <product code>
* @rep:lifecycle <active|deprecated|obsolete|planned>
* @rep:category BUSINESS_ENTITY <business_entity_code> <sequenceNumber>
* @rep:category IREP_CLASS_SUBTYPE JAVA_BEAN_SERVICES
*/
Methods Template:
/**
* < Method description
* ...
* >
*
* @param <paramName> < Parameter description
* ... >
* @rep:paraminfo {@rep:innertype <typeName>} {@rep:precision <value>} {@rep:required} {@rep:key_param}
*
*
* @return < Parameter description
* ... >
* @rep:paraminfo {@rep:innertype <typeName>} {@rep:precision <value>} {@rep:required}
*
*
* @rep:scope <public|private|internal>
* @rep:displayname <Interface display name>
* @rep:httpverb <GET|POST|GET,POST>
* @rep:lifecycle <active|deprecated|obsolete|planned>
* @rep:category BUSINESS_ENTITY <business_entity_code> <sequenceNumber>
* @rep:businessevent <businessEventName>
*/
You can use the following template when annotating Business Service Objects:
Interface Template:
/**
* < Interface description
* ...
* >
*
* @rep:scope <public|private|internal>
* @rep:displayname <Interface display name>
* @rep:lifecycle <active|deprecated|obsolete|planned>
* @rep:product <product code>
* @rep:compatibility <S|N>
* @rep:implementation <full implementation class name>
* @rep:category <lookupType> <lookupCode> <sequenceNumber>
*/
Methods Template:
/**
* < Method description
* ...
* >
*
* @param <paramName> < Parameter description
* ... >
* @rep:paraminfo {@rep:innertype <typeName>} {@rep:precision <value>} {@rep:required}
*
*
* @return < Parameter description
* ... >
* @rep:paraminfo {@rep:innertype <typeName>} {@rep:precision <value>} {@rep:required}
*
*
* @rep:scope <public|private|internal>
* @rep:displayname <Interface display name>
* @rep:lifecycle <active|deprecated|obsolete|planned>
* @rep:compatibility <S|N>
* @rep:category <lookupType> <lookupCode> <sequenceNumber>
* @rep:businessevent <businessEventName>
*/
Here is an example of an annotated Workflow Worklist Application Module Service:
Class level:
/**
* This is a Workflow Worklist Application Module Implementation class
* which provides APIs to set preferred lists, get user worklist,
* get lists and search the worklist based on certain filter criteria
* like viewId, status, block size and block sequence.
* @rep:scope public
* @rep:product FND
* @rep:displayname Workflow Worklist
* @rep:category IREP_CLASS_SUBTYPE AM_SERVICES
* @rep:category BUSINESS_ENTITY WF_WORKLIST
*/
public class WFWorklistServiceAMImpl extends OAApplicationModuleImpl {
...
Method level:
/**
* This is the method for getting worklist summary for a user
* @param blockSize Block Size specifies the number of records to be fetched, cannot be null
* @paraminfo {@rep:required}
* @param blockSequence Block Sequence, cannot be null, value >=1
* @paraminfo {@rep:required}
* @return Array of notifications
* @rep:displayname Get HomePage Worklist
* @rep:httpverb get, post
* @rep:category BUSINESS_ENTITY WF_WORKLIST
*/
public Output[] getHomePGWorklist(String blockSize, String blockSequence) throws Exception {
...
Here is an example of an annotated Employee Information service:
package oracle.apps.per.sample.service;
...
/**
* A sample class to demonstrate how Java API can use the ISG REST framework. This class provides
* methods to retrieve list of direct reports, all reports of a person. It also has methods to
* retrieve personal details and accrual balance of a person.
* @rep:scope public
* @rep:product PER
* @rep:displayname Employee Information
* @rep:category IREP_CLASS_SUBTYPE JAVA_BEAN_SERVICES
*/
public class EmployeeInfo {
public EmployeeInfo() {
super();
}
/**
* This method returns a list of direct reports of the requesting user.
*
* @return List of person records who are direct reports
* @rep:paraminfo {@rep:innertype oracle.apps.per.sample.beans.PersonBean}
* @rep:scope public
* @rep:displayname Get Direct Reports
* @rep:httpverb get
* @rep:category BUSINESS_ENTITY sample
*/
// Demonstration of list return type
public List<PersonBean> getDirectReports() throws PerServiceException {
...
/**
* This method returns an array of all reports of the requesting user.
*
* @return Array of person records who are reporting into the requesting user's organization hierarchy
* @rep:scope public
* @rep:displayname Get All Reports
* @rep:httpverb get
* @rep:category BUSINESS_ENTITY sample
*/
// Demonstration of array return type
public PersonBean[] getAllReports() throws PerServiceException {
...
}
/**
* This method returns the person details for a specific person id. Throws error if the person
* is not in requesting user's org hierarchy.
*
* @return Details of a person in the logged on user's org hierarchy.
* @param personId Person Identifier
* @rep:paraminfo {@rep:required} {@rep:key_param}
* @rep:scope public
* @rep:displayname Get Person Details
* @rep:httpverb get
* @rep:category BUSINESS_ENTITY sample
*/
// Demonstration of simple navigation using path param
public PersonBean getPersonInfo(int personId) throws PerServiceException {
...
Here is an example of an annotated Purchase Order service:
...
package oracle.apps.po.tutorial;
import oracle.jbo.domain.Number;
import oracle.svc.data.DataList;
import oracle.svc.data.DataService;
import oracle.svc.msg.MessageService;
import oracle.apps.fnd.common.VersionInfo;
/**
* 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
*/
public interface PurchaseOrder extends DataService, MessageService
{
public static final String RCS_ID="$Header: appB_servicebean.htm 120.17 2015/07/21 21:37:22 appldev noship $";
public static final boolean RCS_ID_RECORDED =
VersionInfo.recordClassVersion(RCS_ID, "oracle.apps.fnd.framework.toolbox.tutorial");
/**
* Approves a purchase order.
*
* @param purchaseOrder purchase order unique identifier
* @rep:paraminfo {@rep:required}
*
* @rep:scope public
* @rep:displayname Approve Purchase Orders
* @rep:businessevent oracle.apps.po.approve
*/
public void approvePurchaseOrder(Number poNumber);
/**
* Acknowledges purchase orders, including whether the terms have
* been accepted or not. You can also provide updated line
* item pricing and shipment promise dates with the acknowledgement.
*
* @param purchaseOrders list of purchase order objects
* @rep:paraminfo {@rep:innertype oracle.apps.fnd.framework.toolbox.tutorial.PurchaseOrderAcknowledgementsSDO} {@required}
*
* @rep:scope public
* @rep:displayname Receive Purchase Order Items
* @rep:businessevent oracle.apps.po.acknowledge
*/
public void acknowledgePurchaseOrders(DataList purchaseOrders);
/**
* Receives purchase order items. For each given purchase order
* shipment, indicate the quantity to be received and, optionally,
* the receipt date if today's date is not an acceptable receipt date.
*
* @param purchaseOrders list of purchase order objects
* @rep:paraminfo {@rep:innertype oracle.apps.fnd.framework.toolbox.tutorial.PurchaseOrderReceiptsSDO} {@required}
*
* @rep:scope public
* @rep:displayname Receive Purchase Order Items
* @rep:businessevent oracle.apps.po.receive_item
*/
public void receiveItems(DataList purchaseOrders);
/**
* Gets the price for a purchase order line item.
*
* @param poNumber purchase order unique identifier
* @rep:paraminfo {@required}
* @param lineNumber purchase order line unique identifier
* @rep:paraminfo {@required}
* @return the item price for the given purchase order line
*
* @rep:scope public
* @rep:displayname Get Purchase Order Line Item Price
*/
public Number getItemPrice(Number poNumber,
Number lineNumber);
Here is an example of an annotated Purchase Order SDO data object:
package oracle.apps.po.tutorial;
import oracle.jbo.domain.Number;
import oracle.svc.data.DataObjectImpl;
import oracle.svc.data.DataList;
/**
* 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
*/
public class PurchaseOrderSDO extends DataObjectImpl
{
public PurchaseOrderSDO ()
{
super();
}
/**
* Returns the purchase order header id.
*
* @return purchase order header id.
*/
public Number getHeaderId()
{
return (Number)getAttribute("HeaderId");
}
/**
* Sets the purchase order header id.
*
* @param value purchase order header id.
* @rep:paraminfo {@rep:precision 5} {@rep:required}
*/
public void setHeaderId(Number value)
{
setAttribute("HeaderId", value);
}
/**
* Returns the purchase order name.
*
* @return purchase order name.
* @rep:paraminfo {rep:precision 80}
*/
public String getName()
{
return (String)getAttribute("Name");
}
/**
* Sets the purchase order header name.
*
* @param value purchase order header name.
* @rep:paraminfo {@rep:precision 80}
*/
public void setName(String value)
{
setAttribute("Name", value);
}
/**
* Returns the purchase order description.
*
* @return purchase order description.
* @rep:paraminfo {rep:precision 120}
*/
public String getDescription()
{
return (String)getAttribute("Description");
}
/**
* Sets the purchase order header description.
*
* @param value purchase order header description.
* @rep:paraminfo {@rep:precision 80}
*/
public void setDescription(String value)
{
setAttribute("Description", value);
}
/**
* @return the purchase order lines DataList.
* @rep:paraminfo {@rep:innertype oracle.apps.fnd.framework.toolbox.tutorial.PurchaseOrderLineSDO}
*/
public DataList getLines()
{
return (DataList)getAttribute("Lines");
}
/**
* @param list the putrchase order lines DataList.
* @rep:paraminfo {@rep:innertype oracle.apps.fnd.framework.toolbox.tutorial.PurchaseOrderLineSDO}
*/
public void setLines(DataList list)
{
setAttribute("Lines", list);
}
}