at.spardat.xma.datasource
Class XMATabularDataSourceServer

java.lang.Object
  extended byat.spardat.xma.datasource.XMATabularDataSourceServer
All Implemented Interfaces:
ITableProvider, ITabularDataSource

public class XMATabularDataSourceServer
extends java.lang.Object
implements ITabularDataSource, ITableProvider

The purpose of this class if twofold. First, it implements ITabularDataSource at the server side of XMA. Second, it is responsible for querying the origin data source at the server side (database, legacy system or something else).

If a XMA application defines additional data source types, it must subclass this class and call the method addTableProvider(String, ITableProvider) in the derived class's constructor to add additional handler objects that must implement ITableProvider. Basically, ITableProvider is responsible for querying tables for a particular type and has the methods provideTable, getExpireDurationClientSecs and getExpireDurationServerSecs. The first method actually gathers the data and the other control caching behaviour.

getExpireDurationClientSecs defines how long the returned table may stay in the XMA client cache without querying the XMA server again. getExpireDurationServerSecs defines how long the table may reside in the server cache without calling provideTable again. Values of zero indicate that caches effectively are ignored.

Note that the expiration mechanism effectively avoids requests to next higher cache for the specified amount of time, even if the ressource has changed at the origin server in the meantime. Therefore, in the worst case, a XMA client might see a ressource that has been changed getExpireDurationClientSecs + getExpireDurationServerSecs seconds ago. A XMA server might see a ressource that has been changed getExpireDurationServerSecs seconds ago in the worst case.

If a table is considered to be expired at the client, the client validates the table by issuing an HTTP conditional get. The recipient of the HTTP get, the XMA server, itself looks up its cache. If the table is also expired in the server cache, provideTable is called.

This class registers only an ITableProvider for type 'rsc', i.e. resource bundles.


Field Summary
static long UNKNOWN_TIMESTAMP
          Constant for a timestamp that is unknown.
 
Constructor Summary
XMATabularDataSourceServer()
          Constructs and installs predefined table providers.
 
Method Summary
 void addTableProvider(java.lang.String type, ITableProvider provider)
          Installs a ITableProvider for a given type.
 ITabularDomData getDomTable(java.lang.String spec, XMASession session)
          Convenience method to retrieve a table that contains domain values.
 int getExpireDurationClientSecs(java.lang.String type)
          The default implemententation is to consult the installed table providers.
 int getExpireDurationServerSecs(java.lang.String type)
          The default implemententation is to consult the installed table providers.
 ITabularData getTable(java.lang.String spec, XMASession session)
          This method is not indented to be overwritten.
protected  ITableProvider getTableProviderSafe(java.lang.String type)
          Returns the ITableProvider for a given tabular datasource type.
 void invalidate(java.lang.String spec)
          Removes the resource specified by spec from memory.
 ProviderResultServer provideTable(XMASession session, TableSpec spec, long lastModified)
          The default implemententation is to consult the installed table providers.
protected static long tableHash2randomTimeStamp(int hashCode)
          Maps a given hash code to a timestamp ranging from 1.1.1970 up to 1.7.2003.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

UNKNOWN_TIMESTAMP

public static final long UNKNOWN_TIMESTAMP
Constant for a timestamp that is unknown. May be used to specify unknown last modified timestamps.

See Also:
Constant Field Values
Constructor Detail

XMATabularDataSourceServer

public XMATabularDataSourceServer()
Constructs and installs predefined table providers.

Method Detail

addTableProvider

public void addTableProvider(java.lang.String type,
                             ITableProvider provider)
Installs a ITableProvider for a given type. If requests for tabular data sources are made and the provided type is specified, the call is delegated to the given provider.


getTable

public ITabularData getTable(java.lang.String spec,
                             XMASession session)
This method is not indented to be overwritten.

Specified by:
getTable in interface ITabularDataSource
Parameters:
spec - identifies a table as defined above.
session - XMASession
Returns:
the table data. The returned table is never null.
See Also:
ITabularDataSource.getTable(java.lang.String, at.spardat.xma.session.XMASession)

getDomTable

public ITabularDomData getDomTable(java.lang.String spec,
                                   XMASession session)
Description copied from interface: ITabularDataSource
Convenience method to retrieve a table that contains domain values. Not that this method may only be called if the underlying tabular data is indeed a domain table. It is the ITableProvider-implementor that decides on this.

Specified by:
getDomTable in interface ITabularDataSource
Parameters:
spec - identifies a table as defined above.
session - XMASession
Returns:
the table data. The returned table is never null.
See Also:
ITabularDataSource.getDomTable(java.lang.String, at.spardat.xma.session.XMASession)

invalidate

public void invalidate(java.lang.String spec)
Removes the resource specified by spec from memory. The resource is removed from a cache hold by TabularDataSourceServer or by TableManager.

Parameters:
spec -

provideTable

public ProviderResultServer provideTable(XMASession session,
                                         TableSpec spec,
                                         long lastModified)
The default implemententation is to consult the installed table providers.

Specified by:
provideTable in interface ITableProvider
Parameters:
session - the active XMASession
spec - a table specification as defined in ITabularDataSource. The following properties are always contained in spec:
  • type indicates the table type.
  • _loc indicates the Locale of the XMA context.
  • _man indicates the mandant of the XMA context.
  • _env indicates the environment of the XMA context.
The attributes with leading underscore are drawn from XMAContext and are included because they are needed as keys in any cache.
lastModified - may be either UNKNOWN_TIMESTAMP to unconditionally request the data or a timestamp which indicates a lastModified timestamp which has been delivered (presumably some time ago) and the callee is requested to provide the table if it has changed since that time. The units are number of milliseconds since 1.1.1970 UTC.
Returns:
a newly created value object or null. Also see the javadoc of the getter methods there. If the lastModified parameter was UNKNOWN_TIMESTAMP, the returned object must not be null. Otherwise null may be returned which indicates that the table did not change with respect to lastModified. If the callee returns a table, the value objects last modified timestamp may be set or not, depending on whether the callee is able to compute a last modified timestamp.
Throws:
at.spardat.enterprise.exc.SysException - if no provider for the type can be found.
See Also:
ITableProvider.provideTable(XMASession, at.spardat.xma.datasource.TableSpec, long)

getExpireDurationClientSecs

public int getExpireDurationClientSecs(java.lang.String type)
The default implemententation is to consult the installed table providers.

Specified by:
getExpireDurationClientSecs in interface ITableProvider
Returns:
number of seconds a table remains valid in the XMA clients cache without contacting the server for an uptodate check. The implementor must provide a number greater than 60. The maximum of the returned value and 60 will be used.
Throws:
at.spardat.enterprise.exc.SysException - if no provider for the type can be found.
See Also:
ITableProvider.getExpireDurationClientSecs(java.lang.String)

getExpireDurationServerSecs

public int getExpireDurationServerSecs(java.lang.String type)
The default implemententation is to consult the installed table providers.

Specified by:
getExpireDurationServerSecs in interface ITableProvider
Throws:
at.spardat.enterprise.exc.SysException - if no provider for the type can be found.
See Also:
ITableProvider.getExpireDurationServerSecs(java.lang.String)

getTableProviderSafe

protected ITableProvider getTableProviderSafe(java.lang.String type)
Returns the ITableProvider for a given tabular datasource type.

Parameters:
type - the requested type
Returns:
ITableProvider never null.
Throws:
at.spardat.enterprise.exc.SysException - if there is no provider for type.

tableHash2randomTimeStamp

protected static long tableHash2randomTimeStamp(int hashCode)
Maps a given hash code to a timestamp ranging from 1.1.1970 up to 1.7.2003. The purpose of this method is to generate an artificial lastModified timestamp for tabular datas which are not able to provide one.

Parameters:
hashCode - the input hashCode
Returns:
a long timestamp (milliseconds since 1.1.1970 UTC).