001/*
002 * (C) Copyright 2006-20011 Nuxeo SAS (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Nuxeo - initial API and implementation
016 *
017 */
018
019package org.nuxeo.ecm.platform.reporting.api;
020
021import java.io.IOException;
022import java.util.List;
023import java.util.Map;
024
025import org.eclipse.birt.report.engine.api.IRenderOption;
026import org.nuxeo.ecm.core.api.DocumentModel;
027import org.nuxeo.ecm.platform.reporting.report.ReportParameter;
028
029/**
030 * Represents a report instance that is bound to a model. This interface holds the main methods for managing report
031 * parameter and running the rendering.
032 *
033 * @author Tiry (tdelprat@nuxeo.com)
034 */
035public interface ReportInstance {
036
037    /**
038     * Return the associated {@link ReportModel}
039     *
040     * @return
041     */
042    ReportModel getModel();
043
044    /**
045     * Get report parameters that can be entered by the user. This is used to generate the parameter form at rendering
046     * time.
047     *
048     * @return
049     */
050    List<ReportParameter> getReportUserParameters() throws IOException;
051
052    /**
053     * Get All reports parameters : merging model parameters with instance parameters
054     *
055     * @return
056     */
057    List<ReportParameter> getReportParameters() throws IOException;
058
059    /**
060     * Get parameters as storef in thi resport instance
061     *
062     * @return
063     */
064    Map<String, String> getStoredParameters();
065
066    /**
067     * Sets a parameter
068     *
069     * @param param
070     */
071    void setParameter(ReportParameter param) throws IOException;
072
073    /**
074     * Sets a parameter
075     *
076     * @param name
077     * @param value
078     */
079    void setParameter(String name, Object value) throws IOException;
080
081    /**
082     * Starts the rendering of the report according to {@link IRenderOption}
083     *
084     * @param options
085     * @param parameters
086     */
087    void render(IRenderOption options, Map<String, Object> parameters) throws IOException;
088
089    /**
090     * Gives access to the underlying {@link DocumentModel}
091     *
092     * @return
093     */
094    DocumentModel getDoc();
095
096    /**
097     * Get the key used to uniquely identify the report instance This key is used in REST urls.
098     *
099     * @return
100     */
101    String getReportKey();
102
103    /**
104     * Sets the report key (used from a Core Listener)
105     *
106     * @param key
107     */
108    void setReportKey(String key);
109
110    /**
111     * Initialize the parameters from the associated model
112     */
113    void initParameterList() throws IOException;
114}