home *** CD-ROM | disk | FTP | other *** search
/ Symantec Visual Cafe for Java 2.5 / symantec-visual-cafe-2.5-database-dev-edition.iso / VCafe / prosrc.bin / DataSource.java < prev    next >
Encoding:
Java Source  |  1998-03-18  |  14.5 KB  |  417 lines
  1. /*
  2.  * Copyright (c) 1997 Krumel & Associates, Inc. All Rights Reserved.
  3.  *
  4.  * www.krumel.com - controls@krumel.com
  5.  *
  6.  * Permission is given to the buyer of this package for one software
  7.  * developer to use this software on one CPU (one workstation) and to make
  8.  * one backup copy.  You may uitilize and/or modify this class for use in your
  9.  * projects.  You may distribute or sell any executable which results from
  10.  * using this code in yur application, except a utility or class of similar
  11.  * nature to this product.  You may distribute this product in compiled
  12.  * form only, but soley to be used with your cmpiled executable product
  13.  * for the puposes of dynamic loading. You may NOT redistribute the source
  14.  * code in any form or make it accessible through a network or other
  15.  * distribution media to others. Please refer to the file "copyright.html"
  16.  * for further important copyright and licensing information.
  17.  *
  18.  * The source code is the confidential and proprietary information
  19.  * of Krumel & Associates, Inc. ("Confidential Information").  You shall
  20.  * not disclose such Confidential Information and shall use it only in
  21.  * accordance with the terms of the license agreement you entered into
  22.  * with Krumel & Associates, Inc..
  23.  
  24.  * KRUMEL & ASSOCIATES MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE
  25.  * SUITABILITY OF THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT
  26.  * NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  27.  * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. KRUMEL & ASSOCIATES SHALL NOT
  28.  * BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING,
  29.  * MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
  30.  */
  31.  
  32. package symantec.itools.db.awt;
  33.  
  34. import java.awt.Image;
  35.  
  36. /**
  37.  * Interface defines the API required to support storing data for the TableView.<p>
  38.  *
  39.  * All row and column values are 0 relative.
  40.  */
  41. public interface DataSource extends java.io.Serializable {
  42.     /**
  43.      * TableView level event that signifies that the current row has changed.
  44.      */
  45.     public static final String ROW_CHANGE_EVENT = "Row Change";
  46.  
  47.     /**
  48.      * Sets the TableView displaying the data.
  49.      */
  50.     public void setTableView(TableView v);
  51.  
  52.     /**
  53.      * Gets the TableView displaying the data for the DataSource
  54.      */
  55.     public TableView getView();
  56.  
  57.     /**
  58.      * Informs the data source whether the TableView will be requesting successive data
  59.      * for read only purposes.
  60.      * @param manual true if the data source should expect read only data requests
  61.      */
  62.     public void fetchMode(boolean manual);
  63.  
  64.     /**
  65.      * Sets the Data type for cell data when no data value has been set.
  66.      */
  67.     public void setDefaultData(Data defaultValue);
  68.  
  69.     /**
  70.      * Requests the DataSource set an appropriate default data type .
  71.      */
  72.     public void setDefaultData();
  73.  
  74.     /**
  75.      * Gets whether the DataSource has the ability to configure a TableView
  76.      */
  77.     public boolean supportsMeta();
  78.  
  79.     /**
  80.      * Called by the TableView to configure the interface if the DataSource supports
  81.      * meta information
  82.      * @param v The TableView to configure
  83.      * @exception   TypeNotSupported If the data source does not support the type of
  84.      *          action requested
  85.      */
  86.     public void setupTableView(TableView v) throws TypeNotSupported;
  87.  
  88.     /**
  89.      * Requests the current data element be reset to the previously committed
  90.      * state
  91.      */
  92.     public void rollbackCurrentData();
  93.  
  94.     /**
  95.      * Gets the data for a cell that should only be used for reading. It does
  96.      * not change the cell data being currently edited.
  97.      * @param row the cells row
  98.      * @exception DataNotAvailable if the requested data is not set in the data source
  99.      */
  100.     public Data readData(int row, int col) throws DataNotAvailable;
  101.  
  102.     /**
  103.      * Gets the data for a cell.  If the requested data is not the data being
  104.      * currently edited, the current data should be set to the data requested
  105.      * @exception DataNotAvailable if the requested data is not set in the data source
  106.      */
  107.     public Data getData(Coordinate coords) throws DataNotAvailable;
  108.  
  109.     /**
  110.      * Gets the data for a cell.  If the requested data is not the data being
  111.      * currently edited, the current data should be set to the data requested
  112.      * @exception DataNotAvailable if the requested data is not set in the data source
  113.      */
  114.     public Data getData(int r, int c) throws DataNotAvailable;
  115.  
  116.     /**
  117.      * Commits the current data.
  118.      * @exception   TypeNotSupported If the data source does not support the type of
  119.      *          action requested or is not successful
  120.      */
  121.     public void commitData() throws TypeNotSupported;
  122.  
  123.     /**
  124.      * Sets the data value for a cell.
  125.      * @param r the row of the cell
  126.      * @param c the column of the cell
  127.      * @param data the data value for the cell
  128.      * @exception   TypeNotSupported If the data source does not support the type of
  129.      *          action requested or is not successful
  130.      */
  131.     public void setData(int r, int c, Data data) throws TypeNotSupported;
  132.  
  133.     /**
  134.      * Sets the data value for a cell.
  135.      * @param coord the cooridates of the cell
  136.      * @param data the data value for the cell
  137.      * @exception   TypeNotSupported If the data source does not support the type of
  138.      *          action requested or is not successful
  139.      */
  140.     public void setData(Coordinate coord, Data data) throws TypeNotSupported;
  141.  
  142.     /**
  143.      * Gets the textual representation of a cell's data
  144.      * @exception DataNotAvailable if the requested data is not set in the data source
  145.      */
  146.     public String getText(Coordinate coords) throws DataNotAvailable;
  147.  
  148.     /**
  149.      * Gets an image representation of a cell's data
  150.      * @exception DataNotAvailable if the requested data is not set in the data source
  151.      */
  152.     public Image getImage(Coordinate coords) throws DataNotAvailable;
  153.  
  154.     /**
  155.      * Deletes or marks a row for deletion from the data source
  156.      * @exception   TypeNotSupported If the data source does not support the type of
  157.      *          action requested or is not successful
  158.      */
  159.     public void deleteRow(int row) throws TypeNotSupported;
  160.  
  161.     /**
  162.      * Undeletes a row in the data source
  163.      * @exception   TypeNotSupported If the data source does not support the type of
  164.      *          action requested or is not successful
  165.      */
  166.     public void undeleteRow(int row) throws TypeNotSupported;
  167.  
  168.     /**
  169.      * Inserts a new row in the data source above the specified row
  170.      * @exception   TypeNotSupported If the data source does not support the type of
  171.      *          action requested or is not successful
  172.      */
  173.     public void insertRow(int row) throws TypeNotSupported;
  174.  
  175.     /**
  176.      * Appends a new row at the end of the data source's data.
  177.      * @exception TypeNotSupported if the data source does not support the type of
  178.      *          action requested or is not successful
  179.      */
  180.     public int appendRow() throws TypeNotSupported;
  181.  
  182.     /**
  183.      * Gets whether the data source supports a specified type of data.
  184.      */
  185.     public boolean supports(Coordinate coords, int type);
  186.  
  187.     /**
  188.      * Called in response to circulating an event caused by an invocation of
  189.      * TableView.routeEvent().  The event IDs are specified in the CellEvent class
  190.      */
  191.     public void handleCellEvent(symantec.itools.db.awt.event.CellEvent e);
  192.  
  193.     /**
  194.      * Gives a data source a chance to perform any actions in response to a table
  195.      * level event.
  196.      */
  197.     public void handleTableEvent(symantec.itools.db.awt.event.TableEvent e);
  198.  
  199.     /**
  200.      * Routes any exceptions generated to the TableView for proper handling which may
  201.      * include putting a message on status bar or logging to a file.
  202.      */
  203.     public void handleException(int row, int col, Exception ex);
  204.  
  205.     /**
  206.      * Requests the data source reread it data.
  207.      */
  208.     public void refresh();
  209.  
  210.     /**
  211.      * Requests the data source remove all data.
  212.      */
  213.     public void clear();
  214.  
  215.     /**
  216.      * Requests the data source save the current state as appopriate.
  217.      * @exception TypeNotSupported if the data source does not support the type of
  218.      *          action requested or is not successful
  219.      */
  220.     public void save() throws TypeNotSupported;
  221.  
  222.     /**
  223.      * Requests that any actions performed on a row be undone. The meaning
  224.      * is left open and is to interpreted as appropriate for the type of
  225.      * data source
  226.      * @exception TypeNotSupported if the data source does not support the type of
  227.      *          action requested or is not successful
  228.      */
  229.     public void undoRow(int row) throws TypeNotSupported;
  230.  
  231.     /**
  232.      * Gets whether a cells data is editable or non-editable
  233.      * @return true if the data may be altered by the user.
  234.      */
  235.     public boolean isDataEditable(int row, int col);
  236.  
  237.     /**
  238.      * Informs the data source of the current row of the TableView.
  239.      * @exception TypeNotSupported if the data source does not support the type of
  240.      *          action requested or is not successful
  241.      */
  242.     public void setCurrentRow(int row) throws TypeNotSupported;
  243.  
  244.  
  245.     //BS: added constants new, clean, deleted, modified row and non_exists
  246.  
  247.     /**
  248.      * A constant indicating the row is new.
  249.      * @see #rowState
  250.      * @see #CLEAN_ROW
  251.      * @see #DELETED_ROW
  252.      * @see #MODIFIED_ROW
  253.      * @see #NONEXISTS_ROW
  254.      */
  255.     public static final int NEW_ROW = 0;
  256.     /**
  257.      * A constant indicating the state of the row is clean (it has not been
  258.      * been changed since loaded from its source).
  259.      * @see #rowState
  260.      * @see #NEW_ROW
  261.      * @see #DELETED_ROW
  262.      * @see #MODIFIED_ROW
  263.      * @see #NONEXISTS_ROW
  264.      */
  265.     public static final int CLEAN_ROW = 1;
  266.     /**
  267.      * A constant indicating the row has been marked for deletion.
  268.      * @see #rowState
  269.      * @see #NEW_ROW
  270.      * @see #CLEAN_ROW
  271.      * @see #MODIFIED_ROW
  272.      * @see #NONEXISTS_ROW
  273.      */
  274.     public static final int DELETED_ROW = 2;
  275.     /**
  276.      * A constant indicating the row has been modified since creation.
  277.      * @see #rowState
  278.      * @see #NEW_ROW
  279.      * @see #CLEAN_ROW
  280.      * @see #DELETED_ROW
  281.      * @see #NONEXISTS_ROW
  282.      */
  283.     public static final int MODIFIED_ROW = 3;
  284.     /**
  285.      * A constant indicating the row does not exist.
  286.      * @see #rowState
  287.      * @see #NEW_ROW
  288.      * @see #CLEAN_ROW
  289.      * @see #DELETED_ROW
  290.      * @see #MODIFIED_ROW
  291.      */
  292.     public static final int NONEXISTS_ROW = 4;
  293.  
  294.     /**
  295.      * Gets the state of the row.
  296.      * @return the state of the row's data. One of NEW_ROW, CLEAN_ROW, DELETED_ROW,
  297.      *          or MODIFIED_ROW
  298.      */
  299.  
  300.     public int rowState(int row);
  301.  
  302.     /**
  303.      * Gets the last row valid in requested range
  304.      * @exception DataNotAvailable if the requested data is not set in the data source
  305.      */
  306.     public int validDataRowRange(int top, int bottom) throws DataNotAvailable;
  307.  
  308.     /**
  309.      * Gets the number of rows of data stored in the data source
  310.      */
  311.     public int rows();
  312.  
  313.     /**
  314.      * Requests the data source get all of the rows from its source of data.
  315.      */
  316.     public int fetchAllRows();
  317.  
  318.     //Here are some methods needed to support DefaultData
  319.     /**
  320.      * Method used to support Defaultdata class. Gets the type of data supported
  321.      * by the cell.
  322.      */
  323.     public int type(int row, int col);
  324.  
  325.     /**
  326.      * Method used to support Defaultdata class. Commits the data for the
  327.      * specified cell
  328.      * @exception TypeNotSupported if the data source does not support the type of
  329.      *          action requested or is not successful
  330.      */
  331.     public void commit(int row, int col) throws TypeNotSupported;
  332.  
  333.     /**
  334.      * Method used to support Defaultdata class. Gets whether the data for the
  335.      * specified cell supports choice selection lists.
  336.      */
  337.     public boolean supportsChoice(int row, int col);
  338.  
  339.     /**
  340.      * Method used to support Defaultdata class. Gets the choices for the cell to
  341.      * display.
  342.      * @exception TypeNotSupported if the data source does not support the type of
  343.      *          action requested or is not successful
  344.      */
  345.     public Data[] getChoices(int row, int col) throws TypeNotSupported;
  346.  
  347.     /**
  348.      * Method used to support Defaultdata class. Sets the textual value for a cell.
  349.      */
  350.     public void setText(int row, int col, String t);
  351.     //pos is space where to be inserted (0 = first char)
  352.  
  353.     /**
  354.      * Method used to support Defaultdata class. Inserts a character at the
  355.      * specified location in the data value for a cell.
  356.      * @param row The cell's row
  357.      * @param col The cell's column
  358.      * @param pos The position to insert character
  359.      * @param c The character
  360.      */
  361.     public void insertChar(int row, int col, int pos, char c);
  362.  
  363.     /**
  364.      * Method used to support Defaultdata class. Sets the text for a cell to a
  365.      * character
  366.      */
  367.     public void setText(int row, int col, char c);
  368.  
  369.     /**
  370.      * Method used to support Defaultdata class.  Appends a character to the end
  371.      * of the textual representation of the cell's data.
  372.      */
  373.     public void appendChar(int row, int col, char c);
  374.  
  375.     /**
  376.      * Method used to support Defaultdata class. Clears the textual value of a cell.
  377.      */
  378.     public void clearText(int row, int col);
  379.  
  380.     /**
  381.      * Method used to support Defaultdata class. Deletes a character from a cell's
  382.      * data.
  383.      * @param row The cell's row
  384.      * @param col The cell's column
  385.      * @param pos The position to delete character
  386.      */
  387.     public void deleteChar(int row, int col, int pos);
  388.  
  389.     /**
  390.      * Method used to support Defaultdata class. Gets a substring from a cell's
  391.      * data.
  392.      * @param row The cell's row
  393.      * @param col The cell's column
  394.      * @param spos The starting position of the substring, inclusive
  395.      * @param epos The last position of the substring, exclusive
  396.      */
  397.     public String subString(int row, int col, int spos, int epos);
  398.  
  399.     /**
  400.      * Method used to support Defaultdata class. Sets the image data for a cell
  401.      */
  402.     public void setImage(int row, int col, Image i);
  403.  
  404.     /**
  405.      * Method used to support Defaultdata class. Gets a string representation of
  406.      * a cell's data.
  407.      */
  408.     public String toString(int row, int col);
  409.  
  410.     /**
  411.      * Method used to support Defaultdata class. Gets an image representationof
  412.      * a cell's data.
  413.      */
  414.     public Image toImage(int row, int col);
  415. }
  416.  
  417.