Junos Space Java APIs


Asynchronous Jobs (Long Running Request)

InternalScheduleContext

This class is extension of ScheduleContext and is used internally.

JobInfoTO

This stores data related to a task or job.

FIELD NAME TYPE DESCRIPTION
id int Task ID of the job.
taskName String Name of the task.
jobState JobState State of the job. This refers to the complex type named JobState.
jobStatus JobStatus Status of the Job. This refers to the complex type named JobStatus.
percentComplete double Refers to the percentage of the job completed.
startTime Date Refers to the time when the task instance actually started.
endTime Date Refers to the time when the task instance finished.
scheduledStartTime Date Refers to the time when the task instance is supposed to start.
details String User-readable details about the task instance.

JobManagerCallerInterface3

This interface exposes operations used for job management. Any implementation that supports scheduling must implement this interface.

JobResultHandler

This class represents an EJB that sends the job results to a Long Running Request (LLR). Every stateless EJB implemenation class that contains a schedule method (for example, a Job method) must implement this interface.

METHOD PARAMETERS DESCRIPTION
String getResultDataToPost(int jobId, Serializable dataFromResult)
jobId
Task ID as an integer value.
dataFromResult
The serialized form of the object containing data.
 This method takes the task ID and the results in the serialized formed. It then returns the results in the String format.

JobWorker

JobWorker is an implementation of the JobManagerCallerInterface3 interface. Any EJB implementation that supports job scheduling must be an extension of this class. This class abstracts the operations exposed by JobManagerCallerInterface3. Consequently, it is advised that you do not override the operations exposed by the interface.

ScheduleContext

The ScheduleContext object is used for creating a ScheduleTo object corresponding to a schedule query parameter passed by the client to execute jobs in the future.

IPv4 Address Conversion


IpAddressSet

This interface has utilities for converting IPv4 addresses to various representations.

FIELD NAME PARAMETERS
 DESCRIPTION
public static Long ip2Int (String ip)
ip
IPv4 IP Address represented as a string (for example 64.233.187.99)
 Returns IPv4 Address represented as a long integer (for example 1089059683)
public static String int2Ip (Long ip)
ip
IPv4 IP Address represented as a long integer (for example 1089059683)
 Returns IPv4 Address represented as a string (for example 64.233.187.99)
public static Long subnet2Int (String subnetMask)
subnetMask
IPv4 IP Subnet mask represented as a string (for example 255.255.255.0)
 Returns IPv4 Subnet mask represented as a long integer (for example 4294967040)

Paging, Sorting, and Filtering

PagingContext

Used to support paging, filtering, and sorting on the database.

FIELD NAME TYPE DESCRIPTION
filterType Enum (KEYWORD,TAG,PREDEFINED,SELECTION) Used to specify the type of filtering to be used.
KEYWORD
Filter on keyword (partial match of a data value from a specific database column).
TAG
Filter search on the tag or tag expression. The filter is the name for the tag or tag expression
PREDEFINED
Filter type for search on a predefined. query. The filter is the name for the predefined query.
SELECTION
Filter type for search.
sortDirection Enum(ASCENDING,DESCENDING) Used to specify the sort direction for the collection that needs to be sorted.
pageSize int Used to specify the page size while asking for paged records.
pageNumber int Used to specify page the number while asking for paged records.
filterCriteria FilterCriteria This object contains binary tree based on filter= query parameter passed by client.
sortByAttrName String The name of the attribute on which data needs to be sorted.

PagingResult

A holder for the data contained in the PagingContext Object.

FIELD NAME TYPE DESCRIPTION
ctx PagingContext This object contains the returned pageNo, pageSize, and total number of records in the data set.

InternalPagingContext

This class is an extension of PagingContext and is used internally.

FIELD NAME TYPE DESCRIPTION
schedule ScheduleTO The schedule. This refers to the complex type named ScheduleTO.
name
The name of the schedule context

JobState

JobState is an enumeration that holds the state of the jobs or tasks.

VALUE DESCRIPTION
SCHEDULED Specifies that the task is scheduled to be executed in future
STARTING Specifies that the task is starting
INPROGRESS Specifies that the task has already been started and is in progress.
INPROGRESS Specifies that the task has already been started and is in progress.
DONE Specifies that the task is completed.
CANCELLING Specifies that the task has been cancelled and is still in progress of cancelling.
DISABLED Specifies that the task has been DISABLED.

JobStatus

JobStatus is an enumeration that holds the status of the task.

VALUE DESCRIPTION
UNDETERMINED The operation either has not run yet or is in progress but is not finished yet.
INCOMPLETE The operation can no longer run, but never completed (for example, after a power failure).
FAILURE The operation has completed, but with an error condition.
SUCCESS The operation has completed with success
CANCELLED The operation has been cancelled
DEPRECATED The operation is deprecated. It should never be allowed to be rescheduled or run again

ScheduleTO

FIELD NAME TYPE DESCRIPTION
id int The unique ID of the schedule.
startTime Date Refers to the time that the task instance REALLY started.
endTime Date Refers to the time that the task instance REALLY finished.
repetitionsLeft int The number of repetitions left for recurring jobs (1 for non-recurring jobs).
repeatInterval String The number of milliseconds between successive scheduled start times for a task.
unit ScheduleUnit The unit of the schedule. This refers to the enum named ScheduleUnit,

ScheduleUnit

VALUE DESCRIPTION
Milliseconds Refers to MILLISECOND of Calendar.
Seconds Refers to SECOND of Calendar.
Minutes Refers to MINUTE of Calendar.
Hour Refers to HOUR of Calendar.
Days Refers to DATE of Calendar.
Weeks Refers to WEEK_OF_YEAR of Calendar.
Months Refers to MONTH of Calendar.
Years Refers to YEAR of Calendar.

ApiContext

ApiContext provides a base URL and credentials required by an EJB to call downstream REST services. The base URL is the combination of HTTP Scheme and HTTP Authority. For example, URL: http://space.com:8080/api/space. The base URL extracted from the this URL is 'http://space.com:8080', where 'http' is the 'HTTP scheme' and 'space.com:8080' is 'HTTP Authority'.

FIELD NAME TYPE DESCRIPTION
baseUrl String This is used to get the base URL
authCtx AuthorizationContext This reference contains Username and Password.

AuthorizationContext

It provides credentials extracted from HTTP Request.

FIELD NAME TYPE DESCRIPTION
username String Used to get the username.
password String Used to get the password.

UriContext

Provides the base URL and credentials extracted from the HTTP request. This class should be used as a parameter to the REST method that needs to implement filtering, paging, and sorting. Use the getApicontext() method of this class to pass the filtering, paging and sorting information to downstream EJB methods. Base URL is the combination of HTTP Scheme and HTTP Authority. For example, URL: http://space.com:8080/api/space. The base URL is extracted from the this URL is 'http://space.com:8080', where 'http' is the 'HTTP scheme' and 'space.com:8080' is 'HTTP Authority'.

FIELD NAME TYPE DESCRIPTION
baseUrl String Used to get the base URL.
authCtx AuthorizationContext This reference contains Username and Password.
apiCtx ApiContext ApiContext is encapsulated by UriContext. Use the getApicontext() method of UriContext to retrieve the ApiContext required for downstream EJB methods.

InternalApiContext

This class is an extension of ApiContext and is used internally.

JSServiceClient

This class is a wrapper for the Apache HttpClient and Jersey Client API for client-side communication with HTTP-based REST Web services.

METHOD PARAMETERS DESCRIPTION
public JSServiceClient(UriContext uriContext);
uriContext
This is a reference to UriContext.
 This is a constructor that takes UriContext as an argument. This constructor should be used whenever a REST API needs to be accessed through a REST Resource.
public JSServiceClient(ApiContext apiContext);
apiContext
This is a reference to ApiContext.
 This is a constructor that takes ApiContext as an argument. This constructor should be used whenever a REST API needs to be accessed through an EJB.
public HttpClient httpClient(); None This method returns a reference to the Apache HttpClient object.
public Client jerseyClient(); None This method returns a reference to the Jersey Client object.

Database Notifications

AbstractManagedObject

A managed object is any class that extends the AbstractManagedObject Abstract Class. This special class is used for all transfer objects that are returned by an EJB or are passed to an EJB. An object of this class can be bound to any number of JPA Entity classes to achieve notification with the @ManagedObject annotation. The AbstractManagedObject class is used by Junos Space's Notification Framework, which notifies clients whenever an Entity that is bound by a Managed Object is modified, inserted, or deleted.

This class also has the getAuditDetail() method, which is overriden to provide Audit Log Detail information.

GuiNotificationMDBean

This is an encapsulation for the server-side notification mechanism. Any application that supports notification with a Message Drive Bean must extend this class.

CRUD Operations

EntityManagerWrapper

This is an abstraction over CRUD operations provided by EntityManager. It also encapsulates the mechanism to send notifications whenever the database is changed.

METHOD PARAMETERS DESCRIPTION
public List executeNamedQuery(String queryName, Map<string, object=""> namedParams, PagingContext ctx); </string>
queryName
This is the name of the Query. It MUST follow the naming convention <entityclass>.<queryname="">.</queryname=""></entityclass>
namedParams
The map of parameters keyed by their names to be used in the NamedQuery.
ctx
A PagingContext object to support paging, sorting, and filtering.

Returns: A list of Entity Objects

 This method is used to execute a named query. Here a map of parameters can be passed to use in the query.
public void flush(ApiContextInterface apiCtx);
apiCtx
ApiContextInterface is a marker interface. This field is not currently used.
 This method is used to synchronize all the changes that are made to the persistent entities back to the underlying database.
public AbstractEntity merge(AbstractEntity entity, ApiContextInterface apiCtx);
entity
The entity object to be merged.
apiCtx
ApiContextInterface is a marker interface. This field is not currently used.
Returns: An entity object after it gets modified. 		This method associated a detached entity with the current persistence context.
public void persist(AbstractEntity entity, ApiContextInterface apiCtx)
entity
An entity object
apiCtx
ApiContextInterface is a marker interface.
 Make an entity instance managed and persistent. Also used to send database notifications whenever an object is persisted.
public void remove(AbstractEntity entity, ApiContextInterface apiCtx)
entity
Entity object
apiCtx
ApiContextInterface is a marker interface.
 This method is used to remove the entity instance. Also used to send database notifications whenever an object is removed.

Audit Logging

AbstractManagedObject

A managed object is any class that extends the AbstractManagedObject Abstract Class. This special class is used for all transfer objects that are returned by an EJB or are passed to an EJB. An object of this class can be bound to any number of JPA Entity classes to achieve notification through the @ManagedObject annotation. The AbstractManagedObject class is used by Junos Space's Notification Framework which notifies clients whenever an Entity that is bound by a Managed Object is modified, inserted, or deleted.

This class also has the getAuditDetail() method, which is overriden to provide Audit Log Detail information.

JSAuditlogHelper

The JSAuditlogHelper class is a utility class containing static methods that native Java applications can use to log their own audit records to the platform database. These records appear in the Audit Log listing API.

METHOD PARAMETERS DESCRIPTION
public static void addDescriptionToAuditLog(final String description)
description
The description text in the form of a free flowing string to be recorded in the audit log entry.
 This method will log a text message only.
public static void addModifiedObjectToAuditLog(final AbstractManagedObject mo, final String description)
object
The managed object that is modified by the REST API.
description
The description text in the form of a free flowing string to be recorded in the audit log entry.
 This method is used when the API modifies a resource and validates the request body successfully. This resource, which is of type AbstactManagedObject, is passed to the previous method as the first parameter. The descriptive information of changes is passed as the second parameter.
public static void addModifiedObjectsToAuditLog(final List objectList, final String description)
objectList
A list of managed objects that are modified by the REST API.
description
The description text in the form of a free flowing string to be recorded in the audit log entry.
 This method is used when the API validates the request body successfully and modifies more than one resource. These resources should be of the AbstactManagedObject type. Pass the list of these modified objects to the previous method as the first parameter. Pass the descriptive information about the changes as the second parameter.

Application Initialization

AppEnabledCallback

This interface is an application initialization callback that should be used for the execution of the platform's services such as job manager, REST APIs, and others.

METHOD PARAMETERS DESCRIPTION
public void execute(AppInitBasicContext ctx)
ctx
This determines whether or not the initialization code is being executed on the master cluster node.
 This is a callback method that gets executed automatically.

Note: Because the application will not be in its final INIT state, the EJB code will NOT be able to utilize many Junos Space services, such as start jobs or call some REST APIs.
If you want to call jobs from the application initialization code, you can use the AppEnabledCallbackEJB mechanism described below.

appinit.properties key EJB Interface Implementation Method Description
dbinit.x.y* AppDataInit public void initDB() Executed only once on the database node (currently the cluster master node).
clusterinit.x.y* AppClusterInit public void initCluster() Executed only once on the cluster master node.
hostinit.x.y* AppHostInit public void initHost() Executed on all the cluster nodes.

AppInitBasicContext

This interface determines whether or not the initialization code is being executed on the master cluster node.

FIELD NAME TYPE DESCRIPTION
isMasterNode AppInitBasicContext This is the master node for the class.

AppInitContext

This interface determines if the initialization code is being executed on app deployment, app upgrade, or server restart.

FIELD NAME TYPE DESCRIPTION
attribute (AppInitContext.APPSTARTSTATE_ATTR) Enum
 One of the following:
  • AppInitContext.APPSTARTSTATE_FRESHINSTALL
  • AppInitContext.APPSTARTSTATE_RESTART
  • AppInitContext.APPSTARTSTATE_UPGRADE