Previous Page Next Page
JReport Catalog API
Installing the Catalog API
Preparations before using the Catalog API
Using the Catalog API
Creating a connection
Inserting a table/view/synonym
Inserting a stored procedure
Importing an SQL file
Inserting a UDS
Inserting a business view
Inserting a formula, summary, parameter or a WHERE portion
Creating and modifying a query
Inserting, getting and deleting objects in a catalog
Refreshing the reference table of a catalog
Saving a catalog
Catalog API samples
JReport Catalog API is intended for those who want to work with a catalog programmatically. You can create a catalog and manage the objects in it with the methods provided by the Catalog API instead of using the GUI in JReport Designer. Compared with the Catalog Bean, the Catalog API offers greater functionality. As with a catalog in JReport Designer, the Catalog API provides methods which enable you to create a connection, add and delete objects such as tables, queries, business views in a catalog and so on, as shown in the following diagram.
The combination of the Catalog API and the Design API provides you with a Java development environment that enables you to create any report to meet your requirements.
Installing the Catalog API
When you install JReport Designer, the Catalog API is also installed at the same time. After installation, you will have the following components in <install_root>\lib:
- report.jar
- JREngine.jar
- log4j-core-2.10.0.jar and log4j-api-2.10.0.jar (Jar files used for the JReport Engine logging system)
- sac-1.3.jar (Jar file used for installing Catalog API with Design API product)
- ...
The Catalog API class is stored in the archive file report.jar. You will need to do the following steps before you can compile and run the program:
- Set the class path environment variable. Append the following string to your class path that starts the Catalog API (make sure that the path of the file JREngine.jar is before that of the file report.jar):
<install_root>\lib\report.jar;<install_root>\lib\sac-1.3.jar;<install_root>\lib\JREngine.jar;<install_root>\lib\log4j-core-2.10.0.jar;<install_root>\lib\log4j-api-2.10.0.jar
- In your Java program you must set the licensed user and Design API license key.
DesignerUserInfo userInfo=new DesignerUserInfo("UID","Design API Key");
- Set the reporthome parameter equal to the root path of JReport Designer. You can set this in your environment or with the -Dreporthome argument to your JVM.
JReport Server also includes the Catalog API. If you prefer to use the libraries from JReport Server, include the jar file <server_install_root>\lib\JRESServlets.jar in your class path instead of report.jar. You would then need to use the Server Design API license key rather than the Design API license key.
Preparations before using the Catalog API
Before you can use the Catalog API to perform tasks, you will have to create a Designer object and then get a Catalog API instance.
To create a Designer object:
To create a Designer object, use the constructor Designer(String path, String name, DesignerUserInfo user) in the Design API. The constructor has three parameters: the catalog path, catalog name, and the user ID and license key provided by Jinfonet.
The path needs to be a valid path to an existiing directory. The catalog name can be the name of an existing catalog when you want to open a catalog, or the name of a new catalog when you want to create a catalog. If you want to create a new catalog, the path directory should not already contain a catalog file.
To create the DesignerUserInfo instance, use the following constructor providing the user ID and the Server Designer License Key or Designer License Key you received when you purchased JReport.
DesignerUserInfo userInfo=new DesignerUserInfo(Uid, key);
To get a Catalog API instance
To get a Catalog API instance, use the method getCatalogAPI() in the Design API. You need to first get an instance from Designer as follows.
Designer desg = new Designer(catalogPath, catalogName, userInfo);
CatalogAPI catalog = desg.getCatalogAPI();
Using with the Catalog API
The Catalog API provides methods which enable you to create a connection, add and delete objects such as tables, queries, business views in a catalog, and so on.
Reference: For details about the Catalog API methods, refer to the JReport Javadoc jet.api package in <install_root>\help\api, which includes all the documents generated by Javadoc.
Creating a connection
The following methods are used to insert a database connection and return the handle of the newly inserted connection. If not successful, a null value is returned:
- insert(boolean bUseJDBCODBCBridge, String name, String desc, String url, String driver)
- insert(boolean bUseJDBCODBCBridge, String name, String desc, String url, String driver, ConnectionInfo info)
- insert(String dataSourceName, boolean bUseJDBCODBCBridge, String name, String desc,
String url, String driver)
- insert(String dataSourceName, boolean bUseJDBCODBCBridge, String name, String desc,
String url, String driver, ConnectionInfo info)
Parameters
- UseJDBCODBCBridge - Indicates to connect to the database with a JDBC-ODBC Bridge.
- name - The name of the connection.
- desc - The description for the connection.
- url - The URL used to connect to the database.
- driver - The database driver.
- info - The connection information.
Inserting a table/view/synonym
The following methods are used to insert a table, view or synonym into a catalog and to return the handle of the newly inserted object:
- insert(String catalogName, String schemaPattern, String tableName, int type)
- insert(String catalogName, String schemaPattern, String tablePattern, int type, boolean setMappingName)
Parameters
- catalogName - The catalog name.
- schemaPattern - The schema pattern.
- tablePattern - The table name.
- type - The table type.
Inserting a stored procedure
The following methods are used to insert a stored procedure into a connection and to return the handle of the newly inserted procedure.
- insert(String procName,String catalog,String schema,String name,String remarks,int iType)
- insert(String procName, String catalog, String schema, String name, String remarks, int iType)
Parameters
- procName - The procedure mapping name.
- catalog - The catalog name of the procedure.
- schema - The schema name of the procedure.
- name - The procedure name.
- remarks - The remarks on the procedure.
- iType - The result type of the procedure.
Importing an SQL file
The following methods are used to import an SQL file and to return the handle of the newly inserted SQL file:
- insert(String SQLName, String filename)
- insertSql(String dataSourceName, String SQLName, String filename)
Parameters
- SQLName - The SQL name.
- filename - The imported file name.
Inserting a UDS
The following methods are used to insert a user defined data source and to return the handle of the newly inserted UDS:
- insert(String strDSName, String strClassName, String strParameter, UDSColumnInfo udsColInfo)
- insert(String dataSourceName, String strDSName, String strClassName, String strParameter,
UDSColumnInfo udsColInfo)
Parameters
- strDSName - The UDS name.
- strClassName - The name of the UDS class.
- strParameter - The parameter value.
- udsColInfo - The specified column information.
Inserting a business view
To insert a business view, use the following method:
- insertBusinessView(String dataSourceName, String queriableName, String businessViewName, boolean isLogicView=false)
Parameters
- dataSourceName - The mapping name of the data source in the catalog to which you want to insert the object.
- queriableName - The queriable object's mapping name. The queriable object in JReport catalog could be a query, UDS, stored procedure or imported SQL. When queriableName is a valid name of an existing queriable object, a business view will be created.
- businessViewName - The name of the business view.
- isLogicView - Indicates whether to insert a business view. When it is false, a business view will be created.
When you have a business view created successfully, you can then add elements into it. A business view can contain the following elements: categories, group objects, aggregation objects and detail objects.
The following methods are used to insert a view element into a business view and to return the handle of the newly inserted object if it is inserted successfully, otherwise null if there is a failure:
- insertBusinessViewCategory(String parentHandle, BusinessViewCategoryInfo info)
- insertBusinessViewGroup(String parentHandle, BVGroupInfo info)
- insertBusinessViewAggregation(String parentHandle, BVAggregationInfo info)
- insertBusinessViewDetail(String parentHandle, BVDetailInfo info)
Parameters
- parentHandle - The handle of the parent object. It can be a business view or a category.
- info - The definition class of the view element. It can contain its children's definition.
Inserting a formula, summary, parameter or a WHERE portion
The following methods are used to insert a formula, summary, parameter or a WHERE portion into a catalog and to return the handle of the newly inserted object:
- insert(String formulaName, String desc, String expression)
- insert(String summaryName, String desc, int functionType, String fieldName, String groupByFld)
- insert(String parameterName, String desc, String prompt, String type, String default Value)
- insert(String wherePortionName, String desc, WherePortionInfo whereportionInfo)
Parameters
- formulaName - The name of the formula.
- desc - The description of the object.
- expression - The expression.
- summaryName - The name of the summary.
- functionType - The type of the function.
- fieldName - The field name calculated on.
- groupByFld - The field name grouped by.
- parameterName - The parameter Name.
- prompt - The input text prompt.
- type - The parameter data type.
- defaultValue - The defaultValue of the parameter.
- wherePortionName - The WHERE portion name.
- whereportionInfo - The WHERE portion information.
Creating and modifying a query
You can perform the following on a query with the Catalog API.
Inserting a query into a catalog
The following methods are used to insert a query into a catalog and to return the handle of the newly inserted query:
- insert(String qryName, QueryFieldInfo queryFieldInfo,QueryJoinInfo queryJoinInfo, QueryQBEInfo queryQBEInfo, QueryAndInfo queryAndInfo)
- insert(String dataSourceName, String qryName, QueryFieldInfo queryFieldInfo, QueryJoinInfo queryJoinInfo, QueryQBEInfo queryQBEInfo, QueryAndInfo queryAndInfo)
Parameters:
- qryName - The query name.
- queryFieldInfo - The table and fields information.
- queryJoinInfo - The join information.
- queryQBEInfo - The QBE information.
- queryAndInfo - The where condition information.
Adding or deleting tables in a query
- set(String dataSourceName, String qryName, String tablename, String columnname, boolean isFormula) -
Adds a new table to a query and returns a Boolean value: true if successful, otherwise false.
- deleteQueryTable(String dataSourceName, String qryName, String tablename) -
Deletes the selected table in a query and returns a Boolean value: true if successful, otherwise false.
Note: The tables that are to be added should exist in the specified catalog.
Parameters
- qryName - The query name.
- tablename - The name of the table that is to be inserted or deleted.
- selectAllFields - Specifies whether or not to insert a table with all its fields.
Adding or deleting fields in a query
- set(String dataSourceName, String qryName, String tablename, String columnname, boolean isFormula) -
Adds a new field to a query and returns a Boolean value: true if successful, otherwise false.
- deleteQueryField(String dataSourceName, String qryName, String tablename, String columnname) -
Deletes the selected fields in a query and returns a Boolean value: true if successful, otherwise false.
Parameters
- qryName - The query name.
- tablename - The table name of the inserted or deleted field.
- isFormula - Indicates whether the inserted field is a formula.
- columnname - The column name of the deleted field.
Adding or deleting joins in a query
- set(String dataSourceName, String qryName, String tableFrom, String columnFrom, String operator, String tableTo, String columnTo, boolean isSQL92, int outerJoin) -
Adds a new join to a query and returns a Boolean value: true if successful, otherwise false.
- deleteQueryJoin(String dataSourceName, String qryName, String tableFrom, String columnFrom, String operator, String tableTo, String columnTo) -
Deletes joins in a query and returns a Boolean value: true if successful, otherwise false.
Parameters
- qryName - The query name.
- tableFrom - The name of the table from which the join links.
- columFrom - The name of the column from which the join links.
- tableTo - The name of the table to which the join links.
- columnTo - The name of the column to which the join links.
- operator - Operator of the join to be inserted or deleted.
Adding or deleting QBE conditions in a query
- setQBE(String dataSourceName, String qryName, String tablename, String columnname, String expression) -
Adds a new QBE condition to a query and returns a Boolean value: true if successful, otherwise false.
- deleteQBE(String dataSourceName, String qryName, String tablename, String columnname, String expression) -
Deletes the QBE condition in a query and returns a Boolean value: true if successful, otherwise false.
Parameters
- qryName - The query name.
- tablename - The name of the table where the QBE condition will be added or deleted.
- columnname - The name of the column where the QBE condition will be added or deleted.
- expression - The expression of the QBE condition.
Adding or deleting where conditions in a query
- setCondition(String dataSourceName, String qryName, String sExpression1, String sOperator, String sExpression2, String sLogic) -
Adds a new where condition to a query and returns a Boolean value: true if successful, otherwise false.
- deleteCondition(String dataSourceName, String qryName, String sExpression1, String sOperator, String sExpression2, String sLogic) -
Deletes the where conditions in a query and returns a Boolean value: true if successful, otherwise false.
Parameters
- qryName - The query handle.
- sLogic - The logic string of the where condition that is to be inserted or deleted.
- sExpression1 - The first expression of the where condition that is to be inserted or deleted.
- sOperator - The operator of the where condition that is to be inserted or deleted.
- sExpression2 - The second expression of the where condition that is to be inserted or deleted.
Inserting, getting and deleting objects in a catalog
- insert(String name, int type)/insert(String dataSourceName, String name, int type) - Inserts an object into a catalog and returns the handle of the newly inserted object.
- getTables(String dataSourceName) -
Gets tables, views and synonyms in a connection and returns the mapping name array.
- getTables(boolean bIncludeSystemTable) -
Gets tables, views and synonyms in a data source and returns the name array.
- getProcedureNames(String dataSourceName) -
Gets all the stored procedures in a catalog and to return the mapping name array.
- getSQLs(String dataSourceName) -
Gets all the SQL files in a catalog and to return the mapping name array.
- getUDSs(String dataSourceName) -
Gets all the UDSs in a catalog and to return the mapping name array.
- getQueries(String dataSourceName) -
Gets queries in a catalog and returns the mapping name array.
- getNewQueryName() -
Gets a default name for a new query, which must be unique. The name for the first query in a catalog is query1. The following query is query2, then query3 and so on.
- getSQLString(String dataSourceName, String queryName) -
Gets the sql statement text of a query or an imported SQL and returns the SQL statement string.
- getImportedSQLString(String dataSourceName, String importedSQLName) -
Gets the original SQL statement of an imported SQL and returns the original SQL statement string.
- getColumns(String dataSourceName, String queryName, boolean allColumns) -
Gets columns in a query and returns the table name and column real names.
- getColumnMappingnames(String dataSourceName, String queryName) -
Gets column mapping names in a query and returns the table name and column mapping names.
- getColumnsCanBeGroupedBy(String dataSourceName, String queryName) -
Gets the columns which can be grouped by in a query.
- getDBFields(String dataSourceName, String qryName) -
Gets DBFields that can be used in a query and returns the mapping name array.
- getMappingnames(String dataSourceName, String DSName) -
Gets the field mapping names in a data source and returns the table name and column mapping names.
- getFormulae(String dataSourceName) -
Gets formulae that can be used in a catalog and returns the mapping name array.
- getFormulaeCanBeGroupedBy(String dataSourceName, String queryName, String groupBy) -
Gets formulae that are valid to a query and returns the formula names.
- getSummaries(String dataSourceName) -
Gets summaries that can be used in a catalog and returns the mapping name array.
- getSummaryCanBeSortedBy(String dataSourceName, String queryName, String groupBy) -
Gets summaries that can be sorted by.
- getParameter(String dataSourceName) -
Gets parameters in a catalog and returns the mapping name array.
- getParameterCanBeGroupedBy(String dataSourceName) -
Gets parameters that can be grouped by.
- getJoins(String dataSourceName, String queryName) -
Gets joins in a query and returns the join info array.
Note: String[i][0] = Table "From" Name, String[i][1] = Column "From" Name, String[i][2] = Table "To" Name, String[i][3] = Column "To" Name
- getAndConditions(String dataSourceName, String queryName) -
Gets AND conditions in a query and returns a condition info array.
Note: String[i][0] = "Logic", String[i][1] = "Expression1" String[i][2] = "Operator", String[i][3] = "Expression2"
- getQBEInfo(String dataSourceName, String queryName) -
Gets the QBE condition in a query and returns a QBE info array.
Note: String[i][0] = column Name, String[i][j](j>=1) = condition expression of this column.
- getNewReportName() -
Gets a default name for a new report, which must be unique. The name for the first report in a catalog is report1, after which the following reports will be named report2, report3 and so on.
- delete(Stringhandle) - Deletes an object from its parent node and to returns true if the specified object is removed.
Parameters
- name - The object name.
- type - The object type.
- dataSourceName - The mapping name of the data source in the catalog.
- queryName - The mapping name of the query.
- qryName - The query name.
- importedSQLName - The mapping name of the imported SQL.
- allColumns - Selects all columns in the specified tables.
- DSName - The data source object name, such as Query, SQL, UDS, and Procedure.
- groupBy - The groupBy field.
- handle - The handle of the object that is to be deleted.
Refreshing the reference table of a catalog
You can use the method public boolean refreshReference() to refresh the reference table of a catalog.
Saving a catalog
- save() -
Saves an open catalog and returns a Boolean value: false if it fails, otherwise true.
- saveAs(String path, String name) -
Saves an open catalog as a new catalog file. You can save the catalog as a binary catalog using the extension .cat, or an XML format catalog using the extension .cat.xml.
Catalog API samples
The sample programs TestCatalogAPI.java and TestCatalogBV.java in <install_root>\help\samples\APICatalog demonstrate how to use the Catalog API to create a catalog and to create business views in a catalog.
To compile and run the samples, you should add the required classes to the class path (make sure that the path of the file JREngine.jar is before that of the file report.jar).
For example, you can use the following command to compile and run the sample program TestCatalogAPI.java. After running the program, a new catalog file MyReports.cat will be created in C:\JReport\Designer\Demo\MyReports. Be sure to create this empty directory first.
C:\JReport\Designer\help\samples\APICatalog>javac -classpath "C:\JReport\Designer\lib\JREngine.jar;C:\JReport\Designer\lib\sac-1.3.jar;C:\JReport\Designer\lib\report.jar;C:\JReport\Designer\lib\log4j-core-2.10.0.jar;C:\JReport\Designer\lib\log4j-api-2.10.0.jar;C:\test\classes" TestCatalogAPI.java
C:\JReport\Designer\help\samples\APICatalog>java -classpath "C:\JReport\Designer\lib\jrengine.jar;C:\JReport\Designer\lib\sac-1.3.jar;C:\JReport\Designer\lib\report.jar;C:\JReport\Designer\lib\log4j-core-2.10.0.jar;C:\JReport\Designer\lib\log4j-api-2.10.0.jar;C:\JReport\Designer\help;C:\test\classes" -Dreporthome=C:\JReport\Designer TestCatalogAPI -path=C:\JReport\Designer\Demo\MyReports -catalog=MyReports.cat -log=C:\JReport\Designer\logs\designer.log
Previous Page Next Page