KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > net > sf > jasperreports > engine > JRDataSourceProvider


1 /*
2  * ============================================================================
3  * GNU Lesser General Public License
4  * ============================================================================
5  *
6  * JasperReports - Free Java report-generating library.
7  * Copyright (C) 2001-2006 JasperSoft Corporation http://www.jaspersoft.com
8  *
9  * This library is free software; you can redistribute it and/or
10  * modify it under the terms of the GNU Lesser General Public
11  * License as published by the Free Software Foundation; either
12  * version 2.1 of the License, or (at your option) any later version.
13  *
14  * This library is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17  * Lesser General Public License for more details.
18  *
19  * You should have received a copy of the GNU Lesser General Public
20  * License along with this library; if not, write to the Free Software
21  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
22  *
23  * JasperSoft Corporation
24  * 303 Second Street, Suite 450 North
25  * San Francisco, CA 94107
26  * http://www.jaspersoft.com
27  */
28 package net.sf.jasperreports.engine;
29
30 /**
31  * Abstracts the means of creating and disposing a data source.
32  * This interface is meant to be the standard way to plug custom
33  * data sources into GUI designers. Typically the report developer will
34  * implement this interface to create and return a configured data source
35  * of the desired type and then configure the designer to use this implementation.
36  * <br>
37  * The following example demonstrates a provider for a
38  * {@link net.sf.jasperreports.engine.data.JRBeanCollectionDataSource JRBeanCollectionDataSource}.
39  * <code>
40  * <pre>
41  * public class MyBeansDataSource extends JRAbstractBeanDataSourceProvider {
42  *
43  * public MyBeansDataSource() {
44  * super(PersonBean.class);
45  * }
46  *
47  * public JRDataSource create(JasperReport report) throws JRException {
48  * ArrayList list = new ArrayList();
49  * list.add(new PersonBean("Teodor"));
50  * list.add(new PersonBean("Peter"));
51  * return new JRBeanCollectionDataSource(list);
52  * }
53  *
54  * public void dispose(JRDataSource dataSource) throws JRException {
55  * // nothing to dispose
56  * }
57  * }
58  * </pre>
59  * </code>
60  * @author Peter Severin (peter_s@sourceforge.net, contact@jasperassistant.com)
61  * @version $Id: JRDataSourceProvider.java 1229 2006-04-19 13:27:35 +0300 (Wed, 19 Apr 2006) teodord $
62  */
63 public interface JRDataSourceProvider
64 {
65
66     /**
67      * Returns true if the provider supports the {@link #getFields(JasperReport) getFields}
68      * operation. By returning true in this method the data source provider indicates
69      * that it is able to introspect the data source and discover the available fields.
70      *
71      * @return true if the getFields() operation is supported.
72      */
73     public boolean supportsGetFieldsOperation();
74     
75     /**
76      * Returns the fields that are available from the data source.
77      * The provider can use the passed in report to extract some additional
78      * configuration information such as report properties.
79      *
80      * @param report the report that will be filled using the data source created by this provider.
81      * The passed in report can be null. That means that no compiled report is available yet.
82      * @return a non null fields array. If there are no fields then an empty array must be returned.
83      *
84      * @throws UnsupportedOperationException is the method is not supported
85      * @throws JRException if an error occurs.
86      */
87     public JRField[] getFields(JasperReport report) throws JRException, UnsupportedOperationException JavaDoc;
88     
89     /**
90      * Creates and returns a new instance of the provided data source.
91      * The provider can use the passed in report to extract some additional
92      * configuration information such as report properties.
93      *
94      * @param report the report that will be filled using the created data source.
95      * @throws JRException if the data source creation has failed
96      */
97     public JRDataSource create(JasperReport report) throws JRException;
98
99     /**
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 }
120
Popular Tags