Create a Code List

In this Lesson

You will

  • Learn about Soiree’s code list service
  • Use a code list to validate information in a datasource

Concepts

The data access role is responsible for the information contained in the database. This includes the design of the database as well as its content. Some of the content frequently involves simple lists of things that consist of nothing more than a code and its description. You may create database tables ( or other structure ) to define these lists or may want to use the code list service provided by Soiree.

Soiree provides a code list service as a convenient way to provide simple lists of values.

Each list of codes is given a name (a Soiree item ID) and contains one or more name/value pairs.



Code lists are used in two ways

  • They can be used to provide code selection in a Combo Box [ you will do it in a later lesson for the designer role ]


  • They can also be accessed by Java programs and used for data validation. [ you will do it in the next lesson ]

Code List Caching

Soiree clients cache the code lists on the client device to improve responsiveness.

  • The first time a code list is needed the client downloads the list from the server and stores the list in its local cache. The next time the client needs the list it simply retrieves it from the cache instead of contacting the server. [ does that make the server feel unwanted? ]
  • If the code list on the server is changed the client will be notified of the change and the client will remove the list from its local cache. This forces the client to retrieve the new list from the server the next time the list is needed.

Code List Deployment Options

Code lists may be deployed in two ways

  • Item Controlled
    This option provides a static list of codes.
    The only way the list can be altered is by changing the codes defined in the item definition and then redeploying the item to the server. When the client requests a code list the server returns the list directly from the code list resource (the runtime version of the code list item located on the server’s Java classpath).
  • Solution Controlled
    This option provides a list of codes that can be modified by a process within your solution at runtime. When the server starts it looks for code list resources on the Java classpath. If the code list is solution controlled the server will install the codes from the item definition into the SoireeCodeListItem table – but only the first time.
    If codes values exist in the table the server will ignore any codes that are in the item definition. The SoireeCodeListItem table becomes the source of truth for the code list and the solution is now responsible for any changes that are made to the list. Any process in your solution can modify the list by performing the following steps – in the order shown here

    1. Modify the list of codes
      Soiree provides a datasource named SoireeCodeListItem that can be used to manipulate the code values. The SoireeCodeListItem table contains the following columns
      • I_LIST
        This is the id of the list. It is a system assigned value that is assigned to your code list. You need to look up this value for your list by using the SoireeCodeList datasource to select a row from the SoireeCodeList table where N_LIST = “your item id” to obtain the value contained in I_LIST.
      • I_CODE
        This is the id of the code (the code value )
      • C_CODE
        This is the comment of the code ( the code’s description )
    2. Mark the list as modified
      Each code list has one row in the SoireeCodeList table that is used to keep track of when a code list was last modified. The N_LIST (name of the list) column contains the ID of the code list and the T_MODF (timestamp of the modification) column contains the timestamp of the last time the list was modified. Soiree provides a datasource named SoireeCodeList that can be used to update the T_MODF column with the timestamp of when the code list was changed.
    3. Tell Soiree a list has been modified
      You then need to tell Soiree that a code list has been modified so that clients will be notified of the change. You can do this by calling CodeListServer.updateSourceRegistryTimestamp(getDBConnectionProvider(),CodeDepotSource.SOURCE_NAME)

    Because Solution controlled code lists are stored in a table there are length constraints imposed on the code and description. As of this writing the column length constraints are 50 characters for the code value and 128 characters for the code description. Of course, you could remove those constraints by changing the definition of your SoireeCodeListItem table.

Multi-tenant support

Code lists provide multi-tenant support. Every code list must specify one of two options

  • All Tenants
    This allows the code list to be used by all tenants that don’t have a tenant specific list defined for them.
  • Single tenant
    This limits the use of the code list to a single a tenant.

These two options may be used in combination. You could define a code list named com.example.ListOne that allows access to all tenants. You could then define a second code list with the same name ( com.example.ListOne ) that is restricted to a single tenant, say tenant 17.

At runtime, when tenant 17 is using the solution they will see the code list defined for tenant 17. All other tenants would see the code list defined for all tenants.

Create a Code List

In this exercise you will be creating a code list for the times at which a party may begin or end.

  1. Select the com.example.party package in the package explorer and then open the Soiree Code List wizard.
  2. Create a code list named PartyTimes as shown here



  3. Add times from 10 a.m. to 11 p.m. as shown here



  4. Press the Finish button. The item will be added to your project as shown here



  5. Press the Build button.



  6. The build process will create a class in the src-gen folder that contains static properties for the code list name and all of the code values. Other Java classes needing to reference these values should use these generated class properties instead of hard-coding the values.



    src-gen folder
    You should not modify any Java classes that Soiree creates in the src-gen folder. Soiree deletes and recreates these files every time you build the item.

That’s it for this lesson.