In this Lesson
- Learn about Soiree’s code list service
- Use a code list to validate information in a datasource
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
- 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
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.
This is the id of the code (the code value )
This is the comment of the code ( the code’s description )
- 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.
- 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.
- Modify the list of codes
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.
- Select the com.example.party package in the package explorer and then open the Soiree Code List wizard.
- Create a code list named PartyTimes as shown here
- Add times from 10 a.m. to 11 p.m. as shown here
- Press the Finish button. The item will be added to your project as shown here
- Press the Build button.
- 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 folderYou 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.