|
| Query |
|
| |||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||||||
com.sas.iquery.metadata.expr.AbstractTimeValueExpression
public abstract class AbstractTimeValueExpression
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.
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.
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.
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:
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").
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.
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.
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.
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: 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 |
|---|
public static final java.lang.String EVENT_VALUE_CHANGED
| Constructor Detail |
|---|
protected AbstractTimeValueExpression()
protected AbstractTimeValueExpression(java.util.Date value)
| Method Detail |
|---|
public static AbstractTimeValueExpression newValue(java.util.Date value,
int expressionType)
value - the input time value which is used to construct a new time-value expressionexpressionType - the expression type of the input time value
public java.util.Date getValue()
public void setValue(java.util.Date value)
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.
value - the time-value to set on this object.public java.lang.Double getExplicitDoubleValue()
public void setExplicitDoubleValue(java.lang.Double doubleValue)
doubleValue - the value to use for representing this time-value within queries
public java.lang.String generateQueryText(com.sas.iquery.strategies.sas.oma.relational.DataSelectionProcessorAbstract dataSelectionProcessor)
throws MetadataException
_dataSelectionProcessor - The data selection processor determines which language to use.dataSelection - The data selection is used to retrieve the server properties.
MetadataException
public java.lang.String generateQueryText(DataSelection dataSelection,
ConnectionType connectionType)
throws MetadataException
MetadataExceptionpublic boolean equals(java.lang.Object obj)
equals in class java.lang.Objectobj - the input object for which the equality comparison is made
|
| Query |
|
| |||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||||||
