.NET Programming Guide. Server

Transcription

1 .NET Programming Guide Server

2 1 Overview Installation Prerequisites Internet Information Server (IIS) API Proxy Global Assembly Cache The.NET Sample Project Architecture Call Sequence Samples Filter Cache EngineFactory PropertiesChecker Further examples Printing Dynamic Properties NET Viewer Example... 19

3 1 Overview i-net Clear Reports.NET is a fully-featured reporting solution. With i-net Clear Reports Server.NET you have the possibility to embed report rendering and printing into your existing.net application. This guide gives a few examples on how to do this. For further information have a look at the API for Clear Reports.NET Page 2

4 2 Installation In order to embed i-net Clear Reports Server.NET into your application, you first need an installation of i-net Clear Reports Server.NET 2011 or higher. You can download the setup file from our website. 2.1 Prerequisites.NET framework 3.0 or higher Windows XP, Vista or Windows 7 Windows 2003 and newer 32-bit and 64-bit compatible about 250MB free disk space 2.2 Internet Information Server (IIS) This is for the case that you are using the IIS for your applications. You can invoke the Clear Reports API from within you web appliction. Additionally you could use the Proxy example if you need a proxy API For using the API for your web projects that run on the IIS it is recommended to install i-net Clear Reports in the Global Assembly Cache (GAC). This improves the startup speed and reduces the needed resources of the IIS. It can also eliminate some problems with security restrictions Proxy There is an example proxy that can be used with the IIS. Find this example in the folder "\client\documentation\samples\asp.net" of the installation Page 3

5 folder. There is a small *.aspx file that forwards the client requests to the i- net Clear Reports service. If you call this script in your aspx application then you can control the report generation with the URL parameters. 2.3 Global Assembly Cache The setup of i-net Clear Reports Server.NET installs all available assemblies to the subfolder 'bin'. Instead of linking the dll files from the installation folder, you can add them to the Global Assembly Cache (GAC). This is done by simply copying the required files into the folder '%SystemRoot%\assembly'. Using the Global Assembly Cache has the following advantages: The loading from GAC needs less overhead and your application will always load the correct versions The assemblies run with full trust by default and therefore will work in every web application 2.4 The.NET Sample Project This project contains all the classes of the samples used in this guide. You will find some more examples in that project. To find the samples go the folder "\client\documentation\samples\" of the Clear-Reports.NET installation folder. When using the sample project, make sure the references link to the installation folder of i-net Clear Reports. By default this is "c:\program Files\inet Clear Reports.NET\bin". If you need to change the references, the easiest is to simple use a text editor and change them manually in the Page 4

6 .csproj File. If dlls from the lib directory are needed, for example the database drivers, the dlls need to be copied to the output directory. To do this add the folder "lib" in Visual Studio project and copy the needed dlls there. Add the dlls to the project and set the property "Build Action" to "Content" and the property "Copy to output directory" to "Copy if newer". Note: Microsoft Visual Studio 2010 was used for the creation of the project. Page 5

7 3 Architecture To help you to understand the possible changes and implementations that can be done, this call sequence shows you the main entry points for an adaption. Most of the named classes and methods can be overwritten to provide own functionality. 3.1 Call Sequence This graph shows the call sequence of a request for static content, the report viewer and the report rendering. It helps to identify the entry points for your own program logic. Page 6

8 Page 7

9 Page 8

10 Page 9

11 4 Samples The following samples are a selection of what is possible with your installation of i-net Clear Reports Server.NET. They only cover the basics to fulfill the given scenario. Have a look at the chapter The.NET Sample Project for the source files. Each sample requires the IKVM assembly files in order to be executed successfully. The following assemblies must be added as references: IKVM.AWT.WinForms.dll IKVM.OpenJDK.Beans.dll IKVM.OpenJDK.Core.dll IKVM.OpenJDK.Jdbc.dll IKVM.OpenJDK.Media.dll IKVM.OpenJDK.Misc.dll IKVM.OpenJDK.Naming.dll IKVM.OpenJDK.Remoting.dll IKVM.OpenJDK.Security.dll IKVM.OpenJDK.SwingAWT.dll IKVM.OpenJDK.Text.dll IKVM.OpenJDK.Util.dll IKVM.OpenJDK.XML.API.dll IKVM.Runtime.dll IKVM.Runtime.JNI.dll If there are further assemblies required, they will be listed in the according sample. Note that the examples in the sample files contain the needed references. 4.1 Filter When using a servlet filter, you have complete control over the Page 10

12 input(javax.servlet.httpservletrequest) and output(javax.servlet.httpservletresponse). Have a look at the class UserInjection.cs in the samples directory for a detailed example. Create a class that extends from the interface javax.servlet.filter. Because it is executed before all other classes the filter has an effect both on the rendering and on the remote access. The important method to implement is: public void dofilter(servletrequest request, ServletResponse response, FilterChain chain){} To add a servlet filter to i-net Clear Reports.NET firstly build it into a dll or a executable and put those into a lib folder that is defined the Category "Customization" in the Configuration Manager. Secondly, add the class name (with namespace) In the category "Customization" in property "Servlet Filter". Now a restart of the server is necessary. 4.2 Cache Reports, rendered by i-net Clear Reports, are stored in a cache mechanism which can be administrated in the Configuration Manager. The available cache types depend on the purchased license. For some output formats like the Applet Viewer or HTML the server will send the rendering result in multiple steps. Therefore it is necessary to cache the results between different requests. Also, with the cache it is possible to share the rendered results between multiple users. Please have a look at the Cache settings in the Confiugration Manager to check your current settings. Page 11

13 This examples shows how to use the cache to execute an existing report file as PDF and retrieve the page data. For further details on the possible cache features, have a look at the Cache API documentation. The following assembly is required for this sample: ClearReports.dll // Get the current cache instance according to the // administrated type Cache cache = Cache.GetCache(); // Define the report and optional properties for rendering. // Note: The report "mysamplereport.rpt" must exist in the current // working directory. Properties reportproperties = new Properties(); reportproperties.put("report", "mysamplereport.rpt"); // Adding the PDF export property as the target format reportproperties.put("export_fmt", "pdf"); // Create a new cache key to the provided properties ReportCacheKey cachekey = cache.getkey(reportproperties); // Now execute the report and return the number of pages. If the // report is already cached, // the method will return immediately. int pagecount = cache.getpagecountandwait(cachekey); // Now iterate through the pages and request the data for // each page for (int pagenumber = 1; pagenumber <= pagecount; pagenumber++) { byte[] pagedata = cache.getpageandwait(cachekey, pagenumber); // Now this page can be processed further... } Page 12

14 You can find more samples for the usage of the Cache API in the Java code samples directory: "<installation directory>/client/documentation/samples/cache". 4.3 EngineFactory The implementation of an own EngineFactory allows the manipulation of the requested properties to generate a cache key or engine with specified parameters. This example shows how to create an own EngineFactory that caches the executed reports independently from the specified parameters (prompts etc.). The created engine uses another report file if the requested report file name ends with "Report1.rpt". More manipulation of the report properties is possible. The easiest way is to extend EngineFactoryImpl and to override the method you want to change. Alternatively the interface EngineFactory must be implemented in its entirety. The Cache class itself allows the setting of the own EngineFactory instance which then is used for each report rendering by the cache API. Have a look at the Cache API documentation and EngineFactory API for further details on what is possible. The following assembly is required for this sample: ClearReports.dll Page 13

15 class MyEngineFactory : EngineFactoryImpl { public override Engine CreateEngine(Properties p) { // Check the report from the properties and replace all // "report1.rpt" files with another report. Object report = p.get("report"); if (report!= null && report.tostring().endswith("report1.rpt")) { p.put("report", "file:/c:/linkedreports/linked1.rpt"); } // Now create the engine and set the report. Engine engine = new Engine(p.get("export_fmt").ToString()); engine.setreportfile(p.get("report").tostring()); // Other properties can be set here to the engine // (prompts and so on) return engine; } public override ReportCacheKey GetKey(Properties p) { String report = p.get("report").tostring(); String exportformat = p.get("export_fmt").tostring(); // Use no parameters for key generation. This will ensure // that the cache's report is independent from the // parameters the user has set. String parameters = null; } } return new ReportCacheKey(report, parameters, exportformat, 0); After the implementation of the EngineFactory, it must be activated with the following code which must be called before the reports are executed. Page 14

16 EngineFactory myfactory = new MyEngineFactory(); Cache.SetEngineFactory(myFactory); 4.4 PropertiesChecker In order to manipulate the properties before executing a report file, the interface PropertiesChecker has be implemented. It allows you to change, remove or add properties at several points in time. Before the report server creates and sends back a HTML page with the viewer embedded. Right before the engine examines the report file. Right after the engine has examined the report file. This example shows how to create your own PropertiesChecker and activate it in the current configuration. See PropertyChecker.cs in the examples. Have a look at the PropertiesChecker API documentation for further details. The following assembly is required for this sample: ClearReports.dll Page 15

17 public class MyPropertyChecker : PropertiesChecker { public void CheckHtmlPageProperties(java.util.Properties p) { // before returning viewer HTML page } public void CheckProperties(java.util.Properties p, object obj) { // before engine check } public void CheckProperties(Engine e, java.util.properties p, object obj) { // after engine check } } After the implementation of the PropertiesChecker, it can be activated with the following code which must be called before the report server is started. Configuration current = ConfigurationManager.GetInstance().Current; current.put("propertychecker", typeof(mypropertychecker).fullname); // Start the server now Listener.Main(null); Page 16

18 5 Further examples 5.1 Printing i-net Clear Reports allows you to embed the printing of a report from your server without showing the viewer window. You need to specify an URL to a running i-net Clear Reports Server with the report parameter set. This example shows how to create the render data instance, configure the printer and start the printing process. A "RenderData" object is created from an HTTP report URL to a report on a i-net Clear Reports Server. The i-net Clear Reports Server is running on the same machine, listening on port To print the report directly, the default printer of the system is used. The paper size, orientation and margins are retrieved from the report settings. The following assembly is required for this sample: CR-Viewer.dll Page 17

19 // create RenderData for the requested report RenderData data = new URLRenderData (" HashPrintRequestAttributeSet attributeset = PrinterJob job = PrinterJob.getPrinterJob(); new HashPrintRequestAttributeSet(); // use default print service job.setprintservice(printservicelookup.lookupdefaultprintservice()) ; // create the viewer print job and start it PrinterJobProgress progress = new PrinterJobProgress (null, job, attributeset, data); progress.startprogress(); The following code sets additional print attributes like paper format, printable area and orientation. There are more attributes available, than currently used. Each attribute is an instance of the class javax.print.attribute.printrequestattribute: Page 18

20 // selecting a paper type attributeset.add(mediasizename.na_letter); // force form print (ignores margins and resize), should be used // for form reports attributeset.add(new FormPrint()); // Changing the margins of the selected paper // (to 1 inch on all sides) MediaSize size = MediaSize.getMediaSizeForName (MediaSizeName.NA_LETTER); float width = size.getx(mediaprintablearea.inch); float height = size.gety(mediaprintablearea.inch); MediaPrintableArea area = new MediaPrintableArea(1, 1, width - 2, height - 2, MediaPrintableArea.INCH); // switching from portrait to landscape attributeset.add(orientationrequested.landscape); 5.2 Dynamic Properties Dynamic Properties are a feature of the Scheduler (Plus license needed) to create property sets via customized code. Please have a look at the guide for the scheduler for more details. 5.3.NET Viewer Example The.NET Viewer shows an example of how you could visualize a report in you.net application. Internally it is using a Web-control to show the reports. Find this example in the samples folder. This example comes with source files. Page 19