at.spardat.xma.datasource.ITableProvider Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2003, 2007 s IT Solutions AT Spardat GmbH .
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* s IT Solutions AT Spardat GmbH - initial API and implementation
*******************************************************************************/
// @(#) $Id: ITableProvider.java 2089 2007-11-28 13:56:13Z s3460 $
package at.spardat.xma.datasource;
import at.spardat.xma.session.XMASession;
/**
* Is implemented by {@link XMATabularDataSourceServer} and must be implemented by
* an XMA project that provides an additional (custom) datasource.
*
* The classes implementing this interface must be thread safe, i.e., explicitely
* care about synchronization.
*
* @author YSD, 19.06.2003 23:17:35
*/
public interface ITableProvider {
/**
* This method is requested to provide a table in the form of a {@link ITabularData}.
* If lastModified is not specified (if it is {@link ITabularDataSource#UNKNOWN_TIMESTAMP}),
* the callee must return the table.
* If lastModified is defined, the callee must provide a table if and only
* if the modification time changed. If the time of the last modification is still
* lastModified, the returned table in the result data may be null.
* The latter form has the semantics of an HTTP conditional get where the ressource
* is unchanged.
*
* This method is intended to be overwritten (extended) by XMA projects that must handle their
* own types of data sources.
*
* @param session the active XMASession
*
* @param spec a table specification as defined in {@link 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 {@link at.spardat.xma.security.XMAContext XMAContext}
* and are included because they are needed as keys in any cache.
* @param 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.
* @return a newly created value object or null.
* Also see the javadoc of the getter methods there. If
* the lastModified parameter was {@link XMATabularDataSourceServer#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.
*/
public ProviderResultServer provideTable (XMASession session, TableSpec spec, long lastModified);
/**
* Defines the number of seconds a table of a particular type
* may be cached at the XMA client without calling the XMA-server for an uptodate check.
*
* This method is intended to be overwritten (extended) by XMA projects that must handle their
* own types of data sources.
*
* Since the returned information is not cached, this method may be called quite
* frequently and therefore should consume almost no cpu.
*
* @return 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.
*/
public int getExpireDurationClientSecs (String type);
/**
* Defines the number of seconds a table of a particular type
* may be cached at the server without calling provideTable again.
*
* This method is intended to be overwritten (extended) by XMA projects that must handle their
* own types of data sources.
*
* Since the returned information is not cached, this method may be called quite
* frequently and therefore should consume almost no cpu.
*/
public int getExpireDurationServerSecs (String type);
}