All Libraries | This Library | Package | Class | Use | Tree | Deprecated | Index | Grand Index | Help
|  | Query |
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

*** This class is subject to change. ***

## com.sas.iquery.metadata.expr
Class AbstractTimeValueExpression

    com.sas.iquery.metadata.expr.AbstractTimeValueExpression

All Implemented Interfaces:
  Base, BusinessModelResourceReferencer, ModelItem, UsabilityInterface, ExpressionInterface, PropertyChangeListenee, java.beans.PropertyChangeListener, java.lang.Cloneable, java.util.EventListener

Direct Known Subclasses:
  DateValueExpression, TimestampValueExpression, TimeValueExpression

    public abstract class AbstractTimeValueExpression

implements ExpressionInterface

Specifies objects that implement the ExpressionInterface in order to store time-values that are based on the Greenwich Mean Time (GMT) time zone. Objects of this class can be used within the SAS Query Services' expression model in order to model expressions that contain time-values. See the subclasses for what types of values they specifically model.

# Time-value discussion

## Terminology

All of the following terms refer to different forms of time-values and do not imply any specific visual format for the value. From here on when using the term "time-value" we mean any of the following terms.

- Date -- this is obvious
- Time -- A particular time within a 24-hour day with no date associated with it.
- Timestamp -- A time-value representing a point in time accurate to some small precision usually a second or less (conceptually composed of both date and time components).
- DateTime -- Same as Timestamp. This term is a SAS term for what others in the industry refer to as a Timestamp (for example, Java and some databases refer to these as Timestamps).

## Time-values

### How time-values are stored in Database servers

Generally, client API users don't care how time values are stored in database servers ... as long as they are stored consistently. What client users really care about is what form the values need to be in when they need to supply them to the server and what forms they can be in when they come back from the server.

### Time-value literals in SQL syntax

The valid forms for specifying time-value literals in SQL are database-dependent and moreover, sometimes they are database-access-method dependent. Examples of valid time-values specified in SQL sent to SAS workspace servers via IOM are:

- Date: '01JAN2002'd
- Time-of-day: '13:30:59't
- Timestamp: '01JAN2002:13:30:59'dt

while the time-value literal formats to use when connecting to SAS via JDBC are of the form {TS|D|T 'XXXXXXXXX'}. And other databases, when accessed directly, may have other forms yet.

Because of this, it is not good practice to store time-value literals within the SAS Query Services' expression model as Strings since there is no chance for SAS Query Services' SQL generation to recognize them in order to convert them to the proper format prior to sending the SQL to the server. They should be modeled using the classes that extend this class so SQL generation can generate the proper time-value literals in the SQL.

If SAS Query Services API users get SAS double values for any of these time-values they need to be converted to valid Java objects prior to using with SAS Query Services's time-value classes (like this one). See further below where we talk about converting between Java and non-Java time-values.

Although SAS servers store time values without an explicit timezone, that is, values are stored as dates, times, and timestamps as given and returned as received, the values are stored in a standard agreed upon GMT timezone. To expand on this from a client point-of-view -- if SAS servers have no knowledge of timezones associated with the values they take in (parsed in SQL or updated via resultsets), store or give out in resultsets, then there must be an implicit timezone associated with the server's data in order to allow for enterprise-wide (multiple-timezone) sharing of time-values. That means the values must be stored in a standard agreed upon timezone and for SAS Servers, that is the GMT timezone.

Time-values specified in the literal formats above (for example, '13:30:59't) must be in the GMT timezone for them to be shared in a multi-timezone environment. This should not be a significant problem for API users or for SQL generation since all Java and SAS Query Services time-values are defined to be relative to the GMT timezone. So the issue of "when to worry about the timezones" in dealing with SAS servers resolves to this: API users must be concerned about timezones when needing to convert time-values (see section below called "Converting time-values").

## Timezones

### Basics

Associated with every time-value in the world, whether in computers or not, is a timezone. Whether explicitly or implicitly specified, one is required to add context to a time-value. One can't just say 10:00, one must specify (to be complete) a timezone along with 10:00, that is, EST, PST, GMT, etc. For example, 10:00 in EST is 7:00 in PST.

In addition to times and timestamps being relative to timezones, dates are also relative to timezones. The period of time May 29, 2003 in EST is not the same as the period of time May 29, 2003 in the PST.

Note that in many cases timezones are implicit when using time-values; meaning that a timezone may not be explicitly stored or transferred across a wire or handed back by a method call, etc. with the time-value -- but, it is understood that a certain timezone is associated with the time-value. For example, in Java, java.util.Date objects store timestamps that are relative to the GMT timezone. No timezone is set on the objects -- nor can be gotten directly from those objects -- but it is understood that when using them, their values are relative to the GMT timezone.

### Timezones with Java & SAS Query Services model classes

Java's main time-value classes (java.util.Date, java.sql.Date, java.sql.Time, and java.sql.Timestamp) all have their values implicitly based on the GMT timezone. That is, there is no way to specify the timezone explicitly on these types of objects, the values stored in these objects are always relative to GMT.

The SAS Query Services' expression model's time-value classes integrate directly with Java's classes and store no time-values separate from the Java objects they reference. As such, all time-values specified when using the IQ expression model are GMT-based.

## Converting time-values

When converting between different forms of a time-value, one must always keep in mind whether timezone differences are applicable. For example, when converting a timestamp from a java.util.Date (which is always relative to GMT) into a viewable text form, many users want to see the timestamp text value in their local timezone. Others may wish to see it in GMT or another timezone. Keep in mind that when doing this conversion, timezone differences should be taken into account based on the requirements for the conversion.

### Converting viewable text values to Java time-values

Java provides a powerful time-value parsing class: java.text.SimpleDateFormat. It is invaluable in providing capabilities for converting text values to java.util.Date objects. Because the parsing of the text turns it into a GMT-based value stored in a Date object, the parser must have a timezone associated with the text value it is to parse. Unless overridden, the method SimpleDateFormat.parse() parses text assuming the value-text is specified in the current timezone.

### Converting Java time-values to viewable text values

The same incredibly useful class (java.text.SimpleDateFormat) is used for converting Java time-values into viewable text. See the the methods SimpleDateFormat.applyPattern(String) and java.text.DateFormat.format(String) to get started.

### Converting between Java and non-Java time-values.

It is the intention of the SAS Query Services' expression model API to interact with API users using traditional Java objects & standards. As such, one can see that all classes and methods dealing with time-values are based on java's main time-value classes (java.util.Date, java.sql.Date, java.sql.Time, and java.sql.Timestamp). If API users have a need to use non-Java time-values, they must be converted to Java's classes in order to use with the SAS Query Services expression model.

For example, it is possible for API users to query SAS workspace servers and obtain a raw SAS time-values (as doubles in Java). These values are not directly compatible with Java's time-value classes and must be converted prior to use with the expression model. Conversion methods can be found in the com.sas.text.SASDateTimeFormat class.

## Modeling expressions containing time-values

### Example, modeling comparisons of data items and timestamp strings

An example:

     // Modeling:      a DataItem having timestamps  <  a timestamp a user typed in

     // Assumption: The user is told by the UI that his typed-in string
     //             will be interpreted to be "from his or her timezone"
     // Assumption: The user is told by the UI that the valid format
     //             recognized is: YYYY:MMM:DD:HH:mm:ss where MMM is 3-letter month,
     //             HH is 24 hour and 0-based, and mm is minutes.
     // This format is just an example format and has nothing to do directly with IQ.
     // We're just using it in this example code.  UIs can choose whatever DT format
     // patterns they wish to use when interacting with their users.
     // The format letters and rules are all described in the java.text.SimpleDateFormat class
     String timestampString  = <user typed in timestamp-value text string>;

     java.text.SimpleDateFormat formatter = DateFormat.getDateTimeInstance();
     formatter.applyPattern("yyyyMMMdd':'HH':'mm':'ss'");
     java.util.Date timestamp = formatter.parse(timestampString);
     TimestampValueExpression iqTimestamp = new TimestampValueExpression(timestamp);

     FilterItem filter = mapOrDataSelection.newFilterItem();
     mapOrDataSelection.addBusinessItem(filter);
     SimpleConditionalExpression_Comparison comparison = new SimpleConditionalExpression_Comparison();
     comparison.setLeftExpression(dtDataItemToBeFilteredOn);
     comparison.setComparisonOperator(ComparisonOperator.COMPARE_LT);
     comparison.setRightExpression(iqTimestamp);

Field Summary
`static java.lang.String` | `EVENT_VALUE_CHANGED` Indication that value changed.

Fields inherited from interface com.sas.iquery.metadata.business.ModelItem
`EVENT_OBJECT_PROPERTY_CHANGED`

Fields inherited from interface com.sas.iquery.metadata.business.Base
`EVENT_OBJECT_DEFINITION_CHANGED`

Constructor Summary
`protected` | `AbstractTimeValueExpression()`
`protected` | `AbstractTimeValueExpression(java.util.Date value)`

Method Summary
`boolean` | `equals(java.lang.Object obj)` Returns true if this object is the same class as the given object and their time values are equal.
`java.lang.String` | `generateQueryText(DataSelection dataSelection, ConnectionType connectionType)` Return query text of TimeValue expression.
`java.lang.String` | `generateQueryText(com.sas.iquery.strategies.sas.oma.relational.DataSelectionProcessorAbstract dataSelectionProcessor)` Return a String value of the expression, given the language provided on the data selection processor.
`java.lang.Double` | `getExplicitDoubleValue()` Returns the explicit double value to be used in queries for this time-value instead of generating a time-value in a DB-specific format.
`java.util.Date` | `getValue()` Returns the value within this object as a java.util.Date object.
`static AbstractTimeValueExpression` | `newValue(java.util.Date value, int expressionType)` Returns a new time-value expression with the given value and whose type is given by the expression type.
`void` | `setExplicitDoubleValue(java.lang.Double doubleValue)` Sets a double value to use for representing this time-value within queries.
`void` | `setValue(java.util.Date value)` Sets the value within this object to be the given value within the given argument.

Methods inherited from interface com.sas.iquery.metadata.expr.ExpressionInterface
`getExpressionType`

Methods inherited from interface com.sas.iquery.metadata.business.BusinessModelResourceReferencer
`getResources`

Methods inherited from interface com.sas.iquery.metadata.PropertyChangeListenee
`addListener, getListeners, removeListener`

Methods inherited from interface com.sas.iquery.metadata.business.UsabilityInterface
`getReasonsUnusable, isUsableInQuery`

Field Detail

### EVENT_VALUE_CHANGED

    public static final java.lang.String EVENT_VALUE_CHANGED

  Indication that value changed.

  See Also:
    Constant Field Values

Constructor Detail

*** This constructor is subject to change. ***

### AbstractTimeValueExpression

    protected AbstractTimeValueExpression()

*** This constructor is subject to change. ***

### AbstractTimeValueExpression

    protected AbstractTimeValueExpression(java.util.Date value)

Method Detail

### newValue

    public static AbstractTimeValueExpression newValue(java.util.Date value,
                                                       int expressionType)

  Returns a new time-value expression with the given value and whose type is given by the expression type. Returns null if expression type is not an ExpressionTypes.DATE, TIME or TIMESTAMP value.

  Parameters:
    `value` - the input time value which is used to construct a new time-value expression
    `expressionType` - the expression type of the input time value
  Returns:
    AbstractTimeValueExpression or new time-value expression

### getValue

    public java.util.Date getValue()

  Returns the value within this object as a java.util.Date object.

  Returns:
    Date the object contained within this object

### setValue

    public void setValue(java.util.Date value)

  Sets the value within this object to be the given value within the given argument.

  The subsequent calls to get the time-value from this object will return different instances than what were specified when set on this object but will have the same values and will compare equal via the equals() method.

  Changes to the specified object after calling this method will not affect this object's stored value.

  Parameters:
    `value` - the time-value to set on this object.

### getExplicitDoubleValue

    public java.lang.Double getExplicitDoubleValue()

  Returns the explicit double value to be used in queries for this time-value instead of generating a time-value in a DB-specific format. Returns null if no explicit value is set.

  Returns:
    Double or the explicit double value to be used in queries

### setExplicitDoubleValue

    public void setExplicitDoubleValue(java.lang.Double doubleValue)

  Sets a double value to use for representing this time-value within queries. If set (non-null), the value will be used to represent this time-value in queries.

  Parameters:
    `doubleValue` - the value to use for representing this time-value within queries

### generateQueryText

    public java.lang.String generateQueryText(com.sas.iquery.strategies.sas.oma.relational.DataSelectionProcessorAbstract dataSelectionProcessor)
                                       throws MetadataException

  Return a String value of the expression, given the language provided on the data selection processor.

  Parameters:
    `_dataSelectionProcessor` - The data selection processor determines which language to use.
    `dataSelection` - The data selection is used to retrieve the server properties.
  Returns:
    a String value for the time expression using the language provided on the data selection processor.
  Throws:
    `MetadataException`

### generateQueryText

    public java.lang.String generateQueryText(@Nonnull
                                              DataSelection dataSelection,
                                              @Nonnull
                                              ConnectionType connectionType)
                                       throws MetadataException

  Return query text of TimeValue expression.

  Returns:
    string value of expression.
  Throws:
    `MetadataException`

### equals

    public boolean equals(java.lang.Object obj)

  Returns true if this object is the same class as the given object and their time values are equal. Any explicit double value that may be set on the objects is not factored into this comparison.

  Overrides:
    `equals` in class `java.lang.Object`
  Parameters:
    `obj` - the input object for which the equality comparison is made
  Returns:
    boolean to indicate whether this object and the input object's time values are equal

*** This class is subject to change. ***

All Libraries | This Library | Package | Class | Use | Tree | Deprecated | Index | Grand Index | Help
|  | Query |
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2009 SAS Institute Inc. All Rights Reserved.