Number Range Object API

Usage Documentation
Applies to SAP PI B2B SP 02
CONTENTS

SUMMARY .................................................................................................................................... 2

PREREQUISIT ................................................................................................................................. 2

NUMBER RANGE OBJECT (NRO) API ............................................................................................... 2

CODE EXAMPLE ......................................................................................................................... 7

RELATED CONTENT ........................................................................................................................ 7

1
SUMMARY

The following API provides a programmable way to create, read, update, and delete operations on Number
Range Objects.

Prerequ isit

The extracted ‘.jar’ file (com.sap.aii.nro.interface.filter.jar) from the ‘PIB2BCONTENT.SCA’ archive should be
imported into the repository as an “Imported Archives” object.

A newly or an existing function library should be used with this new imported archive as a dependency.

Number Ra nge Object (NRO) API

Number Range Object API can be used to do the following operations:

 Create Number Range Object
 Read Number Range Object
 Update Number Range Object
 Delete Number Range Object
 Update and Read Number Range Object
o Use this method when you find duplicates while using Read Number Range Object Method
o It uses a separate locking mechanism to avoid duplicate number range values

API is part of the _nro_facade project which is available in the PIB2BTOOLKIT.sca. You can also find the ‘.jar’
file which has to be imported into repository (ESR) while creating the UDF in the PIB2BCONTENT.sca

Note

API is dependent on the Number Range Object application, make sure that the application deployed
successfully from the PIB2BTOOLKIT.sca.

GETTING NRO API ACCESS INSTANCE

The NROApiAccess interface controls the API access. There are two ways, to get an instance of the same. NRO
API Access factory is uses

 NROApiAccessRemote api = NROApiAccessFactory.createNROApiAccess();

o This method can be used to access the NRO Api from an application which will be deployed in
the same PI server where the _nro_facade project is deployed.
 NROApiAccessRemote api = NROApiAccessFactory.createRemoteNROApiAccess();
o This method can be used to access the NRO Api from an UDF.

2
CREATE NUMBER RANGE OBJECT

This method creates a new Number Range Object.

 The method createNewNumberRangeObject

o This method helps you in creating a new Number Range Object of your choice and this can be
accessed from the module as well.

/**
*
* create a New NumberRangeObject
*
* @param numberRangeName
* Name of the Number Range Object
* @param value
* value from the Number range should start ,should be a value
* between 'minimumValue' and 'maximumValue' Pass value 0 if not required
* @param minValue
* minimum value for the number range
* @param maxValue
* maximum value for the number range
* @param valueLength
* Number of characters in number range , Pass value 0 if not
* required
* @param rotate
* 'true' If the number range should be repeated
* @param warnLevel
* Percentage value of the warnLevel, value should be in between 0 and
* 100,Pass Value 0 if not required
* @param description
* Description for the Number Range
* @return
* @throws NROApiAccessException
* Name used already exists and is not marked for delete
* @throws NROApiAccessLockException
* Lock cannot be acquired , it is the reponsibility of the client to retry.
*
*/
public INumberRangeObject createNewNumberRangeObject(String numberRangeName, long
value, long minValue, long maxValue, short valueLength, boolean rotate, int
warnLevel, String description)
throws NROApiAccessException, NROApiAccessLockException;

Note

The method createNewNumberRangeObject can throw NROApiAccessLockException when it cannot acquire

lock to complete the operation, in that case the client should retry. Refer to the related link found at the end
of this document, for detailed description of NRO.

3
READ NUMBER RANGE OB JECT

This method reads an already created Number Range Object.

 The method getNumberRangeObjectWithName

o This method helps you in retrieving an already existing NRO. A NRO created in the NRO
Maintenance UI can also be retrieved and used in the program

/**
* @param numberRangeName
* number range name of the existing number range object
* @return
* @throws NROApiAccessException
*/

public INumberRangeObject getNumberRangeObjectWithName(String numberRangeName)

throws NROApiAccessException;

DELETE NUMBER RANGE OBJECT

This method sets an existing Number Range Object for deleted.

 The method setDeleted

o This method marks an NRO to be deleted. Once the NRO is set to deleted it cannot be used
further unless invoked by calling create or update method.

/**
* @param numberRangeName
* Sets the number range to deleted, number range set for deleted can be reused
* by calling create/update number range api
* @return
* @throws NROApiAccessException
* Number range does not exist
* @throws NROApiAccessLockException
* Lock cannot be acquired , it is the reponsibility of the client to retry.
*/
public boolean setDeleted(String numberRangeName)
throws NROApiAccessException ,NROApiAccessLockException;

Note

The method setDeleted can throw NROApiAccessLockException when it cannot acquire lock to complete the
operation, in that case the client should retry.
Refer to the related link found at the end of this document, for detailed description of NRO.

4
UPDATE NUMBER RANGE OBJECT

This method updates an existing Number Range Object

 The method updateNumberRangeObject

o This method allows you to update the already existing NRO.

/**
* update an existing NumberRangeObject
*
* @param numberRangeName
* Name of the existing Number Range Object
* @param value
* value from the Number range should start ,should be a value between
* 'minimumValue' and 'maximumValue' of the number range
* @param minValue
* minimum value for the number range
* @param maxValue
* maximum value for the number range
* @param valueLength
* Number of characters for the getNumber() method , Pass Value 0 if not
* required
* @param rotate
* 'true' If the number range should be repeated
* @param warnLevel
* Percentage value of the warnLevel, Value should be in between 0 and 100,
* Pass Value 0 if not required
* @param description
* Description for the Number Range
* @return
* @throws NROApiAccessException
* Name used does not exist.
* @throws NROApiAccessLockException
* Lock cannot be acquired , it is the reponsibility of the client to retry.
*/

public INumberRangeObject updateNumberRangeObject(String numberRangeName,

long value, long minValue, long maxValue, short valueLength, boolean rotate,
int warnLevel, String description)
throws NROApiAccessException , NROApiAccessLockException;

Note

The method updateNumberRangeObject can throw NROApiAccessLockException when it cannot acquire lock
to complete the operation, in that case the client should retry.
Refer to the related link found at the end of this document, for detailed description of NRO.

5
UPDATE AND READ NUMBER RANGE OBJECT

This method updates the Number Range Object value by one and returns the same object. In case of high load
scenarios please use this method to avoid duplicates.

 The method getAndUpdateNumberRangeObjectWithName

o This method helps you in getting an auto incremented (+1) Number Range Object.

/**
* Increments the numberRangeName by one
* @param numberRangeName
* number range name of the existing number range object
* @return the updated number range object
* @throws NROApiAccessException
*/
public INumberRangeObject getAndUpdateNumberRangeObjectWithName(String
numberRangeName) throws NROApiAccessException;

Note

The method getAndUpdateNumberRangeObjectWithName can throw NROApiAccessLockException when it

cannot acquire lock to complete the operation, in that case the client should retry. Refer to the related link
found at the end of this document, for detailed description of NRO.

You use the procedure below to access the NRO API’s from an UDF:

Code Exa mple One

AbstractTrace trace = container.getTrace();

long value = 0;

try{
NROApiAccessRemote api = NROApiAccessFactory.createRemoteNROApiAccess();
// Here the value gets incremented by one and then the object is returned
INumberRangeObject obj = api.getAndUpdateNumberRangeObjectWithName(var1);
value = obj.getValue() - 1;
} catch (Exception ex) {
trace.addWarning("Unable to get NRO. " + ex.getMessage());
throw new RuntimeException("The values " + var1 + ", in " + container + " could not
be processed.", ex);
}

return ""+value;

Note

Use the above procedure to acquire a unique number range object when you have a high load scenario (3 – 4
messages per second)

6
Code Exa mple Two

AbstractTrace trace = container.getTrace();

long value = 0;

try{
NROApiAccessRemote api = NROApiAccessFactory.createRemoteNROApiAccess();
INumberRangeObject obj = api.getNumberRangeObjectWithName(var1);
value = obj.getValue();

api.updateNumberRangeObject(
obj.getName(),
obj.getValue()+1,
obj.getMinValue(),
obj.getMaxValue(),
obj.getValueLength(),
Boolean.getBoolean(obj.getRotate()),
obj.getWarnLevel(),
obj.getDescription()
);
} catch (Exception ex) {
trace.addWarning("Unable to get NRO. " + ex.getMessage());
throw new RuntimeException("The values " + var1 + ", in " + container + " could not
be processed.", ex);
}

return ""+value;

Related Content

NRO Learning Series