In this Lesson
You will create your first Data Source for the Party solution.
This lesson contains exercises based on the concepts in the Data Source Introduction lesson.
You will be creating a datasource that provides full access to the Party table. This datasource will eventually be used to display information in the skin you have been creating.
Full Access Datasource
A full access datasource is one that provides the ability to maintain a table using insert, update, delete, and select statements that operate on all columns in the table
TipConsider using the table name as the full access datasource name. This makes it very easy for people to find the datasource that maintains the table.
A full access datasource has the following characteristics
- It accesses only one table.
- It contains values for all columns in the table.
- It uses the table’s unique index as the datasource key.
- It provides a query to select a single row from the table.
- It provides a query to browse through all rows in the table.
- It provides a query to insert a row into the table.
- It provides a query to update a single row in the table.
- It provides a query to delete a single row in the table.
A full access datasource can only be created for tables that have column values that can uniquely identify a single row. [ how else could you find a specific row? ]
Create a Data Source for the Party table
In this exercise you will create a data source that provides full access to the party table.
- Start Derby if it is not already running. [ the Data Source wizard and editor require an connection to the database in order to function properly. ]
- Select the com.example.party package by clicking on it.
- Open the Soiree wizard for Data Source by right clicking on the package and selecting New … Data Source
- Enter the following information and click Finish
You should now see the com.example.party.datasource.Party datasource in your project.
CongratulationsYou just created a data source item that provides full access to the Party table.
[ you wrote those SQL statements rather quickly ]
Inspect the datasource item
When you selected the Add full table access the Data Source wizard added to the datasource everything needed to support full access to the table.
If you had left the Add full table access option unchecked you would need to add everything yourself. You will get a chance to do that in a future lesson.
For now, let’s simply a take a look at what was created for you. We will only look at those sections of the definition that contain information provided by the wizard.
The Default Table name will be used when you add new queries to the definition. Changing this name will change the name on all the generated queries that already exist in the table if they are using the old table name.
The Values section defines the values offered by the datasource.
The wizard added all the columns defined for the table in the database catalog.
Each datasource that you create will be turned into a Java class by Soiree. It is important to understand how columns names are represented in the Java class that is produced.
The name of the column in Java is determined as follows
- Alias name
If you provide an alias name then Java will use the alias. This is useful if the database column name is cryptic and you would prefer using a better name in Java.
- Underscore character
If the column name contains an underscore character then the name will be converted to camelCase by using the underscore character as a word delimiter. party_name becomes partyName.
- Otherwise the column name will be used.
The Keys section defines the values that can be used to uniquely identify one row. These keys are used by the datasource to keep track of the currently focused row.
The wizard added the names from the first unique index defined in the database catalog.
Soiree can generate many of the queries you will need for your solution.
The Generated Queries section contains the queries you are asking Soiree to generate for you. The wizard added 6 queries to the definition. Click on a query to see the options which affect how the query will be generated.
To add a generated query you must right click on the query list area and select Add Query. There are 6 types of generated queries that can be produced.
The wizard enabled multi-tenant support because it noticed the table contained a column name that matched the Tenant Column Name configured in Eclipse Preferences.
Build the Java classes
- Press the Build button to create the Java classes for this datasource.
You will see some output in the Datasource view. The green arrow next to the datasource name indicates that the Java build succeeded.
If the build process were to fail it would show an error condition. You can see the error by selecting the failed datasource and then pressing the Show error button.
This particular error was created intentionally by adding a delete query that specified a table name of ARTY instead of PARTY.
- The Java classes that were created can be seen in your project. You will get acquainted with these files in future lessons.
Clearing the Database Cache
The Data Source editor reads the database catalog to obtain information about the table and indexes used in the datasource. After it looks up the information from the catalog it then stores that information in a cache. This cache is used to make the editor more responsive – it does not read from the database catalog if the cache has what it needs.
If database changes are made while you are using the editor you will need to clear the cache to force the editor to read the latest information from the database catalog. You can clear the cached information by selecting this button.
You are now finished with this lesson.[ there is more to learn about datasources. you will attend other parties with datasources in future lessons ]