Best practices for developing application code

For developing an application, you must write a clean service implementation code for BMC Helix Innovation Studio. After you develop the application code, you can upload the application to a central repository, called Marketplace. From Marketplace, other developers can download and use the code. While the application code is being uploaded, BMC Helix Innovation Studio verifies whether the application code complies with the development rules and uploads only compliant application codes to the Marketplace. Noncompliant application codes are rejected and are not uploaded to Marketplace.

The following rules are required for writing Java-based services that are secure, performant, and safe. Refer to the rules while developing your application code and make sure that the application code complies with the development rules. 

For example: BMC Helix Innovation Studio Services must have the following attributes:

  • Manage resources effectively
  • Avoid being stateful 
  • Avoid blocking
  • Avoid performing an end-run around the platform architecture

The best practices for developing application code are defined for the following categories:

Related topics

Developing-and-deploying-code-based-applications

Setting-up-the-environment-to-develop-a-code-based-application

Architecture and Design

Follow the best practices listed in this table:

Dos

Don'ts

Use the core platform services and extend them, if
needed, by using Java code or connectors. The Java code is deployed in your bundle.

Do not introduce new elements to the BMC Helix Innovation Studio container technology stack that run out of processor start threads, such as the following elements:

  • another database
  • job scheduler
  • caching framework

Use the standard platform technology stack

Do not affect the configuration of the technology stack, such as with Jersey, Spring, OSGi, or Jetty configurations.

Not applicable

  • Do not create any code that would affect other code in some cross-cutting transparent manner.
  • Do not use aspects.
  • Do not write your own servlets, servlet filters, Jersey filters, or interceptors.

Use HTTP integration to access services that use third-party libraries.

Introduce new functionality by requesting for enhancements on the platform.

Use provided dependencies, without version dependencies, at own risk.

Do not include any third-party libraries for Java. Use only documented, approved third-party libraries for JavaScript that are already provided with the SDK.

Use Rx APIs to access data on BMC Helix Innovation Studio. You can use the AR REST API to access data on other Remedy servers as an integration.

  • Do not use Core AR-API or API-Clients (other than Mid Tier for configuration cases). That is, do not use Developer Studio to create Forms and Workflow.
  • Do not install or use a version prior to the current version to attempt to connect to BMC Helix Innovation Studio.

Supportability

Follow the best practices listed in this table:

Dos

Don'ts

Make sure that the code logs all errors appropriately. Implement debug level logging to
provide sufficient information to troubleshoot problems.

For example,

catch RxException (e) {
    ServiceLocator.getLogger().error("Could not calculate
service values
with " + paramA + ", " + paramB + ":  failed because of " + e.getLocalizedMessage());
    // Handle the error.
}
  • Do not resolve error conditions without logging them.
  • Do not log an error level to any information that is not an error.
  • Do not log an info level to any information that might log a large number of entries and negatively impact performance.  



Persistence

Follow the best practices listed in this table:

Dos

Don'ts

Use the Record Service, including Attachment Fields, or HTTP-based integration

Do not use the file system.

For example:

Do not read or write from File I/O streams, for resources, configuration, or any other purpose.

// DON'T DO THIS
BufferedReader br = new BufferedReader(new FileReader(FILENAME));
while ((sCurrentLine = br.readLine()) != null) {
// do something with sCurrentLine
}

Threads and Concurrency

Follow the best practices listed in this table:

Dos

Don'ts

Use time-based rules to trigger a workflow in the background.

Do not start threads.

For example, do not implement Runnable to start in a thread.

(new Thread(new MyRunnable())).start();

Also, do not extend the thread as follows:

public class HelloThread extends Thread { .. . . }

Consider using the Process Service to help synchronize activities without writing a Java code.

Do not use thread synchronization mechanisms, such as sleep or the synchronized keyword. Do not interact with threading APIs for any other reason.

Do not use the synchronized keyword, or sleep() for your current thread.

public class SynchronizedCounter {
   private int c = 0;
   public synchronized void increment() {
      c++;
    }
   public int getCount() { return c; }
}

Avoid code that can take a long time to execute. Instead, break long background processing into smaller actions or processes. Use time-based rules to start each process so that you can configure them to run in parallel.

Do not block threads on any long-running operation.For example, avoid nested loops where the number of iterations is unknown in advance. Additionally, do not block a thread waiting for a long time for a response from a network resource.

solveTravellingSalesmanProblem();

Use BMC Integration Service to integrate with any third-party systems outside of BMC Helix Innovation Studio.

Do not make any network calls.

Memory Management

Follow the best practices listed in this table:

Dos

Don'ts

Store information persistently by using Records and Associations or use the platform-provided Cache Service.

Do not allow information to be shared across threads or client requests. Write a code that is stateless.

For example: 

  • Do store data in static variables. 
  • Do not create a data caching mechanism.
  • Do not create member variables for services or JAX-RS resources.

Do not store information in members of your Service or JAX-RS resource as displayed in the following example:

public class MyService implements Service {

// DO NOT do this
private static int lastRate = 0;

// DO NOT do this - A member variable which implements a cache.
private Map rateCache;

public MyService() {
rateCache = new HashMap();
}

/**
 * A service action
 */
@Action
public Integer computeCost(
@ActionParameter(name = "id") @NotBlank @NotNull String id,
    @ActionParameter(name = "hours") @NotBlank @NotNull int hours,
@ActionParameter(name = "rate") @NotBlank @NotNull int rate) {

if (lastRate != rate) {
// DO NOT do this
lastRate = rate;
ServiceLocator.getLogger().info("rate has changed from " + lastRate + " to " + rate);
}

// DO NOT do this
Integer cost = rateCache.get(id);
if (cost == null) {
cost = hours * rate;

rateCache.put(id, cost);
}
return cost;
}
}

Use DataPageQuery pattern.

Requests for data should be chunked using the DataPageQuery pattern (or some other pattern that supports pagination). Furthermore, the processing of data in preparing the response should use RecordInstanceDataPageQuery. Avoid processing an arbitrary amount of data in a single request.

    // Get a chunk of data (error handling not shown here)
    DataPageQueryParameters params = new DataPageQueryParameters(50, 0, propertySelections, null, queryPredicatesByName);
    DataPage result = ServiceLocator.getRecordService().getRecordInstancesByIdDataPage(params);

// Process the chunk
List<?> records = result.getData();
List<ResultInfo> resultList = new LinkedList<ResultInfo>();
   for (Object record : records){
// Construct the object to be returned.
String id = (String)mappedRecord.get(ID);
resultList.add(new ResultInfo( (HashMap<String, Object>)record );
}

// Return the chunk of data
return new DataPage(resultList.size(), resultList);

Do not minimize the loading of large amount of data into memory.

Use the Record Service to persist data between calls.

Do not interact with thread local storage.

Thread local storage is just as ineffective as using a static variable. That is because threads are not allocated to a particular tenant and must not share any state.

public class MyService implements Service {

// DO NOT use ThreadLocal.
private ThreadLocal someData;
public MyService() {
someData = new ThreadLocal();
}

//  Something that updates thread storage.
// DO NOT do this.
@Action
public void setData(@ActionParameter(name = "data") @NotBlank @NotNull String data) {
someData.set(data);

}

// Something that accesses thread storage.
// DO NOT do this.
@Action
public String getData() {
return (String) someData.get(); 
}
}

HTTP

Follow the best practices listed in this table:

Dos

Don'ts

Follow the standard syntax as shown in the samples:

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import com.bmc.arsys.rx.services.common.RestfulResource;
 
@Path("example/myresource")
public class MyResource implements RestfulResource {
   @GET
   @Path("/{id}")
    public String get(@PathParam("id") String id) {

   // Do some processing with id.
String result = something();

       return result;
    }
}

Use standard, supported JAX/RS techniques for custom REST interfaces.

Deploy services as application or library bundles.

Do not include additional servlet containers or legacy Mid TierHTTP services.

Security

Follow the best practices listed in this table:

Dos

Don'ts

Use the platform permission constructs.

Do not create your own permission enforcement mechanism.

For example, do not attempt to parse group lists and implement a new model.

Use the security context provided by the platform.

Do not attempt authorization impersonation or any other changes to any security context.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*