biz.c24.io.api.presentation.stream
Class SpreadSheet

java.lang.Object
  extended by biz.c24.io.api.presentation.stream.SpreadSheet
Direct Known Subclasses:
SpreadSheetReader, SpreadSheetWriter

public abstract class SpreadSheet
extends Object

Spreadsheet support broker.

Provides the basic functionality for Microsoft ® Spreadsheet support. This class designed as agent that facades functionality provided by other 3rd party tools. (A.k.a Jakarta POI.) The guaranteed functionality is expressed by this facade and will not changed in future. Any provided implementation may extend only.

The movement that is provided by this broker is performed in two following ways:

Such differentiation is required due other nature of movement within and between tables. In first case, the movement is not taking into consideration the spreading of sibling component (i.e. rows/columns, depends on orientation), whereas in movement between the tables, it is required to make the movement not from current location, but rather from last extension point. Therefore the occupy and withdraw methods should enframe the binding the each table, this simplifies the movement between them. For more details see the occupation and withdrawal procedures.

Additionally the broker provides the basic mark / rollback functionality for processing the alternative lexical branches (if any exists in used model).

Version:
$Revision: 18046 $ $Date: 2011-10-18 12:25:10 -0400 (Tue, 18 Oct 2011) $
See Also:
SpreadSheetReader, SpreadSheetWriter, SpreadSheet.Locator

Nested Class Summary
 class SpreadSheet.Locator
          Helper class that represents the location of cell within the workbook.
 
Field Summary
protected  Stack ditches
          Stack of borders of the spreading the tables has been read.
protected  SpreadSheet.Locator location
          Location implementation instance.
protected  org.apache.poi.ss.usermodel.Workbook workbook
          Liable 3rd party broker.
 
Constructor Summary
protected SpreadSheet(org.apache.poi.ss.usermodel.Workbook workbook)
          Constructor with 3rd party workbook instance.
 
Method Summary
protected  SpreadSheet.Locator calculateNext(SpreadSheet.Locator step)
          Calculates the next location on the specified step movement.
protected  SpreadSheet.Locator getDitch()
          Returns the current (i.e. last known) "ditch".
 SpreadSheet.Locator getLocation()
          Returns the current location.
protected  String getSheetName(int idx)
          Returns the sheet name.
 SpreadSheet.Locator mark()
          Marks the location to which consequent rollback will restore the broker state.
 void next(String step)
          Moves the current location on provided offset (i.e.
 SpreadSheet.Locator occupy()
          Start the new spreading occupation.
protected  SpreadSheet.Locator parse(String address)
          Returns the parsed address as location.
protected abstract  int resolveSheet(String name)
          Returns the sheet index in workbook used.
 void rollback(SpreadSheet.Locator ditch)
          Rollbacks the last known "ditch" to preliminary stored location.
 void setStartLocation(String start)
          Sets the current location to specified address.
 void withdraw(SpreadSheet.Locator backPoint)
          Returns the position in provided location and restore up the last occupied ditch.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

workbook

protected final org.apache.poi.ss.usermodel.Workbook workbook
Liable 3rd party broker.


location

protected SpreadSheet.Locator location
Location implementation instance.


ditches

protected final Stack ditches
Stack of borders of the spreading the tables has been read.

Constructor Detail

SpreadSheet

protected SpreadSheet(org.apache.poi.ss.usermodel.Workbook workbook)
Constructor with 3rd party workbook instance.

Constructs the SpreadSheet broker instance with provided workbook.

Parameters:
workbook - The workbook implementation that will be used.
Method Detail

getLocation

public SpreadSheet.Locator getLocation()
Returns the current location.

Returns:
The location instance that represents the current position withing SpreadSheet.
See Also:
SpreadSheet.Locator

setStartLocation

public void setStartLocation(String start)
Sets the current location to specified address.

Parameters:
start - The address from where parsing of the SpreadSheet will start.
See Also:
getLocation()

next

public void next(String step)
Moves the current location on provided offset (i.e. step).

Parses the provided string representation of offset and set the new location that is calculated. The scope of extension is updated by new location.

Parameters:
step - The textual representation of step that need to perform.

occupy

public SpreadSheet.Locator occupy()
Start the new spreading occupation.

Stores the current location (its clone) for following withdraw. In fact prepares the broker to do the subsequent spreading for sibling tables (i.e. ADS' CDTs). Before any spreading, the client should call this method to be able fix the spreading by following withdrawing.

Returns:
The current location that may be used for subsequent withdraw.
See Also:
withdraw(biz.c24.io.api.presentation.stream.SpreadSheet.Locator)

withdraw

public void withdraw(SpreadSheet.Locator backPoint)
Returns the position in provided location and restore up the last occupied ditch.

Doing "withdraw" to the last known "occupied ditch". To understand this mechanism need to represents the spreading as serial attacks during military occupation. Each next attack bring the new space, and there is need to dig around to keep this territory during enemy counter-attack. So, the "invasion" is the sequential process of "attack" and "digging the ditches" to which there is need to withdraw.

Parameters:
backPoint - The new location to where withdrawal should be performed.
See Also:
occupy()

mark

public SpreadSheet.Locator mark()
Marks the location to which consequent rollback will restore the broker state.

Returns the last known ditch clone for consequent restoring to the prevent state in case of lexical branch failure. In military terms, the building of backbone defencive line in light of big probability of counter-attack due lack of offencive capabilities.

Returns:
The last known "ditch" as location instance.

rollback

public void rollback(SpreadSheet.Locator ditch)
Rollbacks the last known "ditch" to preliminary stored location.

Used in conjunction with mark "ditch" to rollback on preliminary stored location thereby restoring the last good known broker state during processing the alternative lexical state transition.

Parameters:
ditch - The last known "ditch" to which it is need to restore the broker state.

parse

protected SpreadSheet.Locator parse(String address)
Returns the parsed address as location.

The address should conform the used cell reference style.

Parameters:
address - The textual representation of address that need to parse.
Returns:
The parsed address as location instance.

calculateNext

protected SpreadSheet.Locator calculateNext(SpreadSheet.Locator step)
Calculates the next location on the specified step movement.

Realizes movement in following manner depends on provided step:

So, this will produce the new location calculation only and it is up to client move on or stay on the same place.

Parameters:
step - The requested step (i.e. the offset) on which movement need to do.
Returns:
The suggested new location.

getDitch

protected SpreadSheet.Locator getDitch()
Returns the current (i.e. last known) "ditch".

Returns:
The location that represents the last known withdrawal position.

resolveSheet

protected abstract int resolveSheet(String name)
Returns the sheet index in workbook used.

Returns the requested sheet by its name. If provided name is null the current existing sheet index is returned.

Note: Due difference in behavior during reading and writing: the writing supposes the sheet creation "on the fly", there is needing to add the polymorphism for current sheet getter. So, details please see in corresponding implementations.

Parameters:
name - The requested sheet name, may be null.
Returns:
The requested sheet index, zero-based.

getSheetName

protected String getSheetName(int idx)
Returns the sheet name.

Resolve the sheet name by its index within workbook, zero-based. The sheet should exist and index provided should be positive integer.

Parameters:
idx - The index of sheet which name is requested.
Returns:
The sheet name.


C24 Technologies © 2002-2012: All Rights Reserved.