Code Lists and Code Sources

Code List
A code list is a collection of codes and their associated descriptions. These are typically used to present a list of options in a user interface element such as a combo-box, spinner, or radio button group. They can also be used by text label or text value elements to display the description associated with their bound value instead of showing the value itself.

Code Source
A code source is exactly what the name implies – a source from which code lists can be obtained. Each code source may provide one or more code lists. For example, Soiree provides a code source named CODE-DEPOT which provides any list created by the Code List editor.

There are two ways in which code lists are delivered to a Soiree client for use by a scene’s elements

  1. Code Source Lists
    Code source lists lists are passed to the client by reference. The scheme node contains only the name of the source and list as shown here



    The Soiree client obtains the actual code list from the code source by making an out-of-band request to SxServer. The client downloads and caches the code list to improve the client responsiveness. Later, when a code source reports that a list has been modified the client will remove the code list from its cache and obtain a fresh copy of the list the next time it is needed.

  2. Dynamic Lists
    Dynamic code lists are delivered to the client by value. The scheme node contains the actual list of codes. Dynamic lists are never cached by the client and the code list must be present in the scheme node each time the scheme is sent to the client. Dynamic lists are specified in the agent editor as shown here



    The <DYNAMIC> value instructs the Soiree client to obtain the code list from the node itself instead of from a code source.

    The code list is provided to the node by the agent. The agent must add the code list to the scheme node as part of its scheme loading process as shown here

    //Create an empty dynamic code list and assign it to the node
    CodeList exampleList = CodeList.createDynamicCodeList();
    scheme.getExampleNode().setDynamicCodeList(exampleList);
    
    //add codes/descriptions to the code list
    exampleList.addItem("A", "Code A Description");
    exampleList.addItem("B", "Code B Description");
    

Creating a code source
You may create a code source to expose any list of information needed by your solution. The process of creating a code source will now be described.

  1. Start the Code Source wizard and provide the required values.



    Unique Names
    The Source Name is a ‘short name’ used to identify the source in the agent editor with a more readable for designers.

    The source name must be unique among all other code lists because the ‘source name’ is an alias for the code source.
  2. Right click in the List Names area to add a new list name. Here is an example of a code source offering two lists containing order status codes. One list is defined to return the codes in process order and the other return the codes in alphabetical order.


  3. Press the build button


    It will create a class in the src folder and it’s superclass in the src-gen folder.


  4. The class contains 2 methods for each code list. You must implement the requirements for each method. Refer to the comments in the class for instructions.


    • loadXXX
      This method should load the code list.
    • isXXXModified
      This method accepts a timestamp provided by the client and is the last updated time of the client’s code list cache. This method should return true if the code list has been modified since the specified time.
      Tracking Modifications
      The code source should establish a way to know the last modified time of each code list. For example, if the source of information for a list contains a last modified timestamp for each code in the list it could be used to determine when the list was last changed.

Passing selection parameters to the code source
There are time when a static list name may not suffice. For example, imagine the order status list must contain different values depending on the type of item being ordered. The code source would need to know the item number in order to determine which codes should be provided. You can accomplish this through the list name.

Example: Define a list name that is something like this

order_status_for_item

At runtime the agent would change the list name on the node to include the item number.

String itemNumber = "1023"
scheme.getXXXXNode().setCodeListName("order_status_for_item_" + itemNumber)

Modify the code source to extract the item number from the code list name. This is accomplished by overriding the getCodeList() method.

@Override
public CodeList getCodeList(DBConnectionProvider connectionProvider,
		CodeListKey key) throws Exception {
	if (key.getName().startsWith("order_status_for_item")) {
		//parse the item number out of the list name
		//return the appropriate list of codes
		return ...
	}else{
		return super.getCodeList(connectionProvider, key);
	}
}

The isOrder_status_for_itemModified() method should return true if any of the item specific code lists has changed.

Registering Code List Changes
When the source of information for a code list is modified you need to notify Soiree’s code list service of the change. This is necessary in order for the client to be notified of the code list change. This is accomplished by calling the following method in the super class.


Agent access to code lists
If agents need access to code lists contained in an item controlled code list the list can be obtained as by calling the following method.

CodeListBroker.getCodeList(codeListId, tenant)

CodeListId is the fully qualified item name (package + name) not the short source name.