001: /*
002: * ============================================================================
003: * GNU Lesser General Public License
004: * ============================================================================
005: *
006: * JasperReports - Free Java report-generating library.
007: * Copyright (C) 2001-2006 JasperSoft Corporation http://www.jaspersoft.com
008: *
009: * This library is free software; you can redistribute it and/or
010: * modify it under the terms of the GNU Lesser General Public
011: * License as published by the Free Software Foundation; either
012: * version 2.1 of the License, or (at your option) any later version.
013: *
014: * This library is distributed in the hope that it will be useful,
015: * but WITHOUT ANY WARRANTY; without even the implied warranty of
016: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
017: * Lesser General Public License for more details.
018: *
019: * You should have received a copy of the GNU Lesser General Public
020: * License along with this library; if not, write to the Free Software
021: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
022: *
023: * JasperSoft Corporation
024: * 303 Second Street, Suite 450 North
025: * San Francisco, CA 94107
026: * http://www.jaspersoft.com
027: */
028: package net.sf.jasperreports.engine;
029:
030: /**
031: * Abstracts the means of creating and disposing a data source.
032: * This interface is meant to be the standard way to plug custom
033: * data sources into GUI designers. Typically the report developer will
034: * implement this interface to create and return a configured data source
035: * of the desired type and then configure the designer to use this implementation.
036: * <br>
037: * The following example demonstrates a provider for a
038: * {@link net.sf.jasperreports.engine.data.JRBeanCollectionDataSource JRBeanCollectionDataSource}.
039: * <code>
040: * <pre>
041: * public class MyBeansDataSource extends JRAbstractBeanDataSourceProvider {
042: *
043: * public MyBeansDataSource() {
044: * super(PersonBean.class);
045: * }
046: *
047: * public JRDataSource create(JasperReport report) throws JRException {
048: * ArrayList list = new ArrayList();
049: * list.add(new PersonBean("Teodor"));
050: * list.add(new PersonBean("Peter"));
051: * return new JRBeanCollectionDataSource(list);
052: * }
053: *
054: * public void dispose(JRDataSource dataSource) throws JRException {
055: * // nothing to dispose
056: * }
057: * }
058: * </pre>
059: * </code>
060: * @author Peter Severin (peter_s@sourceforge.net, contact@jasperassistant.com)
061: * @version $Id: JRDataSourceProvider.java 1229 2006-04-19 10:27:35Z teodord $
062: */
063: public interface JRDataSourceProvider {
064:
065: /**
066: * Returns true if the provider supports the {@link #getFields(JasperReport) getFields}
067: * operation. By returning true in this method the data source provider indicates
068: * that it is able to introspect the data source and discover the available fields.
069: *
070: * @return true if the getFields() operation is supported.
071: */
072: public boolean supportsGetFieldsOperation();
073:
074: /**
075: * Returns the fields that are available from the data source.
076: * The provider can use the passed in report to extract some additional
077: * configuration information such as report properties.
078: *
079: * @param report the report that will be filled using the data source created by this provider.
080: * The passed in report can be null. That means that no compiled report is available yet.
081: * @return a non null fields array. If there are no fields then an empty array must be returned.
082: *
083: * @throws UnsupportedOperationException is the method is not supported
084: * @throws JRException if an error occurs.
085: */
086: public JRField[] getFields(JasperReport report) throws JRException,
087: UnsupportedOperationException;
088:
089: /**
090: * Creates and returns a new instance of the provided data source.
091: * The provider can use the passed in report to extract some additional
092: * configuration information such as report properties.
093: *
094: * @param report the report that will be filled using the created data source.
095: * @throws JRException if the data source creation has failed
096: */
097: public JRDataSource create(JasperReport report) throws JRException;
098:
099: /**
100: * Disposes the data source previously obtained using the
101: * {@link #create(JasperReport) create} method.
102: * This method must close any resources associated with the
103: * data source. For instance the database connection should be
104: * closed in case of the
105: * {@link JRResultSetDataSource JRResultSetDataSource}.
106: * <br>
107: * Note: The provider must take care of the resource - data source association.
108: * For example in case of the {@link JRResultSetDataSource JRResultSetDataSource}
109: * a subclass of this data source can be created. This subclass will
110: * hold the database connection and the prepared statement that were
111: * used to obtain the ResultSet. On the time of the dispose these resources
112: * can be retrieved from the data source object and closed.
113: *
114: * @param dataSource the data source to dispose
115: * @throws JRException if the data source could not be disposed
116: */
117: public void dispose(JRDataSource dataSource) throws JRException;
118:
119: }
|