- Fragment properties

Fragment properties

In the previous examples curly braces were used to list out the groups to which a fragment belongs. However, the curly braces can also be used to directly assign fragment properties using the normal property group syntax. For example:

SELECT A1, A2, A3, A4 FROM LIB.A [[{id: fragment1; groups: groupB;} INNER JOIN LIB.B ON A1 = B1 ]]

[[{groupC} INNER JOIN LIB.C ON A1 = C1 ]] [[{id: fragment3; groups: groupB,groupC;} AND C6 = B6 ]]

WHERE (A1 = ? OR CAST(??1 AS INTEGER) IS NULL) AND

(A2 = ? OR CAST(??3 AS CHAR(10)) IS NULL) [[{groupB} AND

(B2 = ? OR CAST(??5 AS CHAR(10)) IS NULL) AND

(B3 = ? OR CAST(??7 AS CHAR(10)) IS NULL) ]] [[{groupC} AND

C2 = ? ]]

ORDER BY A1

Here, two properties are defined for the first fragment, the id property and the groups property. The following fragment properties can be assigned:

• • class – The name of the Java class which should be used for the fragment. The class must implement IFragment and provide a default constructor

  • groups – The names of the groups to which the fragment belongs

  • id – A unique identifier for the fragment. The ID is useful when working with the fragments in code; otherwise there is no need to assign an ID

  • include – This property describes when WOW should include the fragment in the SQL statement. The possible values for this property are:

  • auto – WOW should decide when to include the fragment and when not to (this is the default value)

  • false – The fragment should never be included in the SQL. This setting can be overridden in code, but otherwise the fragment won’t be included

  • true – The fragment should always be included in the SQL. This setting can be overridden in code, but otherwise the fragment will be included

  • remove values – The list of values which will cause WOW to remove the fragment from the SQL. If the value of a display parameter in the fragment is equal to one of the values in the list, then that display parameter is treated as though it did not have a value (but only for the purposes of WOW’s fragment logic). So a parameter whose value is in the remove values property can cause its containing fragment (and other fragments in its fragment group) to be removed from the SQL. If the value “null” is present in the remove values property then display parameters without values can cause their fragment to be removed as usual; if the remove values property is present but does not contain “null” then display parameters without values will not cause their fragment to be removed.

• environment - A comma separated list of environments in which the fragment may be included. For example if the environment property is set to "prod, dev" then the fragment will never be included unless the webapps environment has been set to either prod or dev.

When the only property that is being assigned is the groups property, then you can simply list out the fragment’s groups, as is done in the initial examples. Only when you want to assign other properties do you have to use the property group format.

In this example, the A3 prompt will never be sent to the database:

SELECT A1, A2, A3, A4 FROM LIB.A [[{group1} INNER JOIN LIB.B ON A1 = B1 ]]

WHERE (A1 = ? OR CAST(??1 AS INTEGER) IS NULL) AND

(A2 = ? OR CAST(??3 AS CHAR(10)) IS NULL) [[{group1} AND

(B2 = ? OR CAST(??5 AS CHAR(10)) IS NULL) AND

(B3 = ? OR CAST(??7 AS CHAR(10)) IS NULL) ]]

[[{groups:group2; include:false;} AND A3 = ?]]

ORDER BY [[{group2}A3,]] A1

However, if the user enters a value for the A3 prompt, then the results would be sorted by the A3 column. In other words, the fact that the A3 parameter is never sent to the DB does not prevent the last fragment from being sent to the DB if the user enters a value for the A3 parameter.

Working with fragments in code

Internally each fragment defined in the SQL statement is represented by an IFragment object. (That interface, like most of the fragment code is located in the planetj.database.sql.fragment package.) The IFragment objects are contained in the SQLContext object. One important thing to keep in mind is that fragments are never actually removed from a SQLContext’s internally stored code. Instead, they are stripped out of the code which is sent to the database, but remain in the code stored in the SQLContext. For this reason, in code the terms “included” and “removed” are not used to describe the fragments; instead “active” and “inactive” are used to refer to fragments which are sent to the DB, or not.

There are several methods which can be used to retrieve the code for a SQLContext, depending on how much processing you want WOW to do with the code:

• • getOriginalCode() – Returns the code as it was entered in the builder.

  • getCode() – Returns the internal code stored in the SQLContext. This will include all fragments regardless of whether or not they are active, but does not include the fragment control characters (i.e. the opening “[[{group1, group2}” and closing “]]” are not included).

  • getCode(true) – Returns the internal code stored in the SQLContext, after removing any fragments which are not active. All fragment control characters are also removed.

Below is a listing of some of the methods which can be used when working with fragments:

• • SQLContext.getFragments – Returns a SQLFragmentCollection object which contains the individual fragments

  • SQLFragmentCollection.getFragment – Gets a fragment by its ID. A fragment’s ID is assigned with the id property in the property group.

  • SQLFragmentCollection.getFragmentGroup – Gets a group of fragments by the group name

  • IFragment.isActive – Returns true/false depending on whether or not the fragment is active

  • IFragment.setActive – Sets a fragment as either being active or not active (if a fragment is not active it is not sent to the database)

  • IFragment.getDisplayParameters – Returns a List containing all of the fragment’s display parameters

  • IFragment.getDisplayParameterStatus – Examines all of the display parameters in the fragment and returns one of the following constants:

  • PARAMETERS_NONE – The fragment does not contain any display parameters

  • PARAMETERS_VALUELESS – None of the fragment’s display parameters have values

  • PARAMETERS_SOME_WITH_VALUES – The fragment contains multiple display parameters, some of those parameters have values and others do not

  • PARAMETERS_ALL_WITH_VALUES – All of the fragment’s display parameters contain a value