Creating a Data Source

In this Lesson

You will create your first Data Source for the Party solution.

Concepts

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

Tip
Consider 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.

  1. 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. ]


  2. Select the com.example.party package by clicking on it.



  3. Open the Soiree wizard for Data Source by right clicking on the package and selecting New … Data Source
  4. Enter the following information and click Finish



    You should now see the com.example.party.datasource.Party datasource in your project.



    Congratulations
    You 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.

Default Table

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.



Values

The Values section defines the values offered by the datasource.
The wizard added all the columns defined for the table in the database catalog.



Value Names

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

  1. 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.
  2. 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.
  3. Otherwise the column name will be used.



Keys

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.



Generated Queries

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.



Multi-Tenant

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

  1. 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.



  2. The Java classes that were created can be seen in your project. You will get acquainted with these files in future lessons.



Feel free to browse through the content of these Java files if you would like to be impressed by the all the code you just created.

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 ]