RapidReport 製品ドキュメント

Reportの仕様

Reportは帳票そのものを表すオブジェクトです。

RapidReportを用いたアプリケーションの開発を行うには、 まずはこのReportオブジェクトを生成する必要があります。

Reportオブジェクトの生成

Reportオブジェクトを生成するためには、ReportDesignオブジェクトが必要です。 ReportDesignは帳票定義ファイルの内容を元に作られるオブジェクトで、 以下のコンストラクタで生成することができます。

  // C#
  ReportDesign reportDesign = new ReportDesign(Json.Read("example.rrpt"));
  ReportDesign reportDesign = new ReportDesign(Json.Read("example.rrpt"), reportSetting);
  ' VisualBasic
  Dim reportDesign As New ReportDesign(Json.Read("example.rrpt")) 
  Dim reportDesign As New ReportDesign(Json.Read("example.rrpt"), reportSetting)
  // Java
  ReportDesign reportDesign = new ReportDesign(ReadUtil.readJson("example.json"));
  ReportDesign reportDesign = new ReportDesign(ReadUtil.readJson("example.json"), reportSetting);

1つ目の引数に帳票定義ファイルを読み込んで得たオブジェクトを渡します。

2つ目の引数にはReportSettingというオブジェクトを渡します。 ReportSettingは帳票の設定を行うためのオブジェクトです。その詳細については後述します。 デフォルトの設定のままでよいのであれば、この引数は省略できます。

ReportDesignは、帳票定義JSON内のオブジェクトが持つプロパティに対応したメンバを持ちます。 例えば、ReportDesignオブジェクトには、Caption, Id, Paperなどのメンバがあり、 それぞれに対応するプロパティの値が格納されています。

ReportDesignオブジェクトの内容は動的に変更することもできます。 例えば以下のように書くことで、実行時に余白を変更することができます。

  // C#
  reportDesign.PaperDesign.Margin.Left = 50;
  reportDesign.PaperDesign.Margin.Right = 50;
  ' VisualBasic
  reportDesign.PaperDesign.Margin.Left = 50
  reportDesign.PaperDesign.Margin.Right = 50
  // Java
  reportDesign.paperDesign.margin.left = 50f;
  reportDesign.paperDesign.margin.right = 50f;  

ReportDesignオブジェクトが生成できたらReportオブジェクトを生成します。 コンストラクタは以下のようになります。

  // C#
  Report report = new Report(reportDesign);
  Report report = new Report(reportDesign, customizer);
  ' VisualBasic
  Dim report As New Report(reportDesign)
  Dim report As New Report(reportDesign, customizer)
  // Java
  Report report = new Report(reportDesign);
  Report report = new Report(reportDesign, customizer);

1つ目の引数にreportDesignオブジェクトを渡します。

2つ目の引数にはカスタマイザというオブジェクトを渡します。 カスタマイザは帳票に対して動的変更を加えるためのオブジェクトで、 「カスタマイザの仕様」に詳しい説明があります。 動的なカスタマイズを行わないのであれば、この引数は省略できます。

Reportオブジェクトのコンストラクタには帳票定義JSONのオブジェクトを直接渡すこともできます。

  // C#
  Report report = new Report(Json.Read("example.rrpt"));
  Report report = new Report(Json.Read("example.rrpt"), reportSetting);
  Report report = new Report(Json.Read("example.rrpt"), reportSetting, customizer);
  ' VisualBasic
  Dim report As New Report(Json.Read("example.rrpt"))
  Dim report As New Report(Json.Read("example.rrpt"), reportSetting)
  Dim report As New Report(Json.Read("example.rrpt"), reportSetting, customizer)
  // Java
  Report report = new Report(ReadUtil.readJson("example.json"));
  Report report = new Report(ReadUtil.readJson("example.json"), reportSetting);
  Report report = new Report(ReadUtil.readJson("example.json"), reportSetting, customizer);

このように書いた場合は、Reportコンストラクタの内部でReportDesignオブジェクトが自動的に生成されます。

ReportSetting

先ほどの説明で触れたReportSettingオブジェクトには、 帳票の動作を制御するための設定項目がメンバとして含まれています。 その一覧を以下に示します。

項目 説明
MethodMap 帳票が利用するメソッドオブジェクトを登録するハッシュです
OperatorMap 帳票が利用するオペレータオブジェクトを登録するハッシュです
ElementPreprocessorMap
DefaultElementPreprocessor
帳票が利用するElementプリプロセッサオブジェクトを登録するハッシュです
Elementのtype値に対応するキーがハッシュに含まれていなければ、
DefaultElementPreprocessorに設定されたオブジェクトが利用されます
TextFormatterMap
DefaultTextFormatter
帳票が利用するテキストフォーマッタオブジェクトを登録するハッシュです
Formatterのtype値に対応するキーがハッシュに含まれていなければ、
DefaultTextFormatterに設定されたオブジェクトが利用されます
Logger 帳票出力時に例外が発生した場合に、その情報を収集するためのオブジェクトを指定します
後述するIReportLoggerインターフェースを実装したオブジェクトを指定する必要があります

IReportLogger

RapidReportは、帳票出力の途中でエラーが発生したとしても、 処理の中断をせずに完遂するよう動作します。 例えば、式の記述を誤って文法エラーや間違った列名が含まれていたとしても、 その式の値はNULLとしてそのまま処理を続行します。

出力処理の途中で発生したエラーの情報は、 IReportLoggerというインターフェースの実装クラスを用意し、 ReportSettingに設定することで収集することができます。

IReportLoggerインターフェースは以下のように定義されています。

  ' .NET (VisualBasic)
  Public Interface IReportLogger
  
    Sub EvaluateError(ByVal exp As String, ByVal ex As EvalException)
  
    Sub ElementRenderingError( _
      ByVal contentDesign As ContentDesign, _
      ByVal design As ElementDesign, _
      ByVal ex As Exception)
  
    Sub UnknownFieldError(ByVal ex As UnknownFieldException)
  
  End Interface
  // Java
  public static interface ILogger{
  
    void evaluateError(String exp, EvalException ex);
  
    void elementRenderingError(
      ContentDesign contentDesign,
      ElementDesign elementDesign,
      Throwable ex);
  
    void unknownFieldError(UnknownFieldException ex);
  
  }

EvaluateErrorメソッドは、式の評価中に例外が発生した場合に呼ばれます。

ElementRenderingErrorメソッドは、 ElementRendererによる描画処理中に例外が発生した場合に呼ばれます。

UnknownFieldErrorメソッドは、 データソースに対して不明な列への参照が行われた場合に呼ばれます。 具体的には、データソースのGetメソッド内でUnknownFieldException例外が発生した場合に呼ばれます。

C#でのロガーのサンプルコード

C#で、帳票の出力処理中に発生した例外の内容を、標準出力へ出力するロガーのサンプルコードを以下に示します。

  public class MyReportLogger : IReportLogger
  {
    // 式の評価中に例外が発生すると呼ばれます。
    public void EvaluateError(string exp, EvalException ex)
    {
      Console.Out.WriteLine(ex.GetType().ToString() + " : " + ex.Message);
    }
    // 要素の描画中に例外が発生すると呼ばれます。
    public void ElementRenderingError(
      ContentDesign contentDesign, ElementDesign design, Exception ex)
    {
      Console.Out.WriteLine(ex.GetType().ToString() + " : " + ex.Message);
    }
    // 不明な列への参照が行われると呼ばれます。
    public void UnknownFieldError(UnknownFieldException ex)
    {
      Console.Out.WriteLine(ex.GetType().ToString() + " : " + ex.Message);
    }
  }

このロガーは、Reportオブジェクトを生成する際に以下のように指定することで利用できます。

  ReportSetting setting = new ReportSetting();
  setting.Logger = new MyReportLogger(); // ロガーを設定します。
  Report report = new Report(Json.Read("example.rrpt"), setting);

VisualBasicでのロガーのサンプルコード

VisualBasicで、帳票の出力処理中に発生した例外の内容を、標準出力へ出力するロガーのサンプルコードを以下に示します。

  Public Class MyReportLogger
    Implements IReportLogger
    ' 式の評価中に例外が発生すると呼ばれます。
    Public Sub EvaluateError(exp As String, ex As EvalException) _
        Implements IReportLogger.EvaluateError
      Console.Out.WriteLine(ex.GetType().ToString() & " : " & ex.Message)
    End Sub
    ' 要素の描画中に例外が発生すると呼ばれます。
    Public Sub ElementRenderingError( _
        contentDesign As ContentDesign, design As ElementDesign, ex As Exception) _
        Implements IReportLogger.ElementRenderingError
      Console.Out.WriteLine(ex.GetType().ToString() & " : " & ex.Message)
    End Sub
    ' 不明な列への参照が行われると呼ばれます。
    Public Sub UnknownFieldError(ex As UnknownFieldException) _
        Implements IReportLogger.UnknownFieldError
      Console.Out.WriteLine(ex.GetType().ToString() & " : " & ex.Message)
    End Sub
  End Class

このロガーは、Reportオブジェクトを生成する際に以下のように指定することで利用できます。

  Dim setting As New ReportSetting()
  setting.Logger = New MyReportLogger() ' ロガーを設定します。
  Dim report As New Report(Json.Read("example.rrpt"), setting)

Javaでのロガーのサンプルコード

Javaで、帳票の出力処理中に発生した例外の内容を、標準出力へ出力するロガーのサンプルコードを以下に示します。

  public class MyReportLogger implements IReportLogger
  {
    // 式の評価中に例外が発生すると呼ばれます。
    public void evaluateError(String exp, EvalException ex)
    {
      System.out.println(ex.getClass().toString() + " : " + ex.getMessage());
    }
    // 要素の描画中に例外が発生すると呼ばれます。
    public void elementRenderingError(
      ContentDesign contentDesign, ElementDesign design, Throwable ex)
    {
      System.out.println(ex.getClass().toString() + " : " + ex.getMessage());
    }
    // 不明な列への参照が行われると呼ばれます。
    public void unknownFieldError(UnknownFieldException ex)
    {
      System.out.println(ex.getClass().toString() + " : " + ex.getMessage());        
    }
  }

このロガーは、Reportオブジェクトを生成する際に以下のように指定することで利用できます。

  ReportSetting setting = new ReportSetting();
  setting.Logger = new MyReportLogger(); // ロガーを設定します。
  Report report = new Report(ReadUtil.readJson("example.rrpt"), setting);

GlobalScope

Reportオブジェクトのメンバとして用意されたGlobalScopeというハッシュにデータを登録しておくと、 帳票内のglobal.[キー]という式から得ることができます。

  // C#
  report.GlobalScope.Add("today", DateTime.Today);
  ' VisualBasic
  report.GlobalScope.Add("today", Today)
  // Java
  report.globalScope.put("today", new Date());

上記のように書いた場合、global.todayという式で印刷を実行した日付が得られます。

AddSubPages

AddSubPagesメソッドを呼ぶことで、Reportにサブページを割り当てます。 1つ目の引数にサブページのキー、2つ目の引数にサブページとなるReportPagesオブジェクトを渡します。

  // C#
  ReportPages subPages = subReport.GetPages();
  report.AddSubPages("subpage", subPages);
  report.Fill(new SubPageDataSource(subPages, "group_id", "page1", "page2"));
  ' VisualBasic
  Dim subPages As ReportPages = subReport.GetPages()
  report.AddSubPages("subpage", subPages)
  report.Fill(New SubPageDataSource(subPages, "group_id", "page1", "page2"))  
  // Java
  ReportPages subPages = subReport.getPages();
  report.addSubPages("subpage", subPages);
  report.fill(new SubPageDataSource(subPages, "group_id", "page1", "page2"));

サブページの詳しい利用法については、機能サンプルの「サブページ」をご覧ください。

AddSharedContent

AddSharedContentメソッドはクラスメソッドで、コンテントを共有コンテントへと登録します。 1つ目の引数に共有コンテントのID(識別子)を指定し、2つ目の引数に登録するコンテントを含むReportDesignオブジェクトを渡します。

  // C#
  ReportDesign sharedReport = new ReportDesign(Json.Read("shared.rrpt"));
  Report.AddSharedContent("company_info", sharedReport);
  ' VisualBasic
  Dim sharedReport As New ReportDesign(Json.Read("shared.rrpt"))
  Report.AddSharedContent("company_info", sharedReport)
  // Java
  ReportDesign sharedReport = new ReportDesign(ReadUtil.readJson("shared.rrpt"));
  Report.addSharedContent("company_info", sharedReport);

このメソッドは、指定したReportDesignオブジェクト内から指定したID(識別子)を持つコンテントを検索して見つかった場合、 それを共有コンテントへとIDをキーにして登録します。 すでに存在するIDが指定された場合、登録されるコンテントは上書きされます。

共有コンテントは、コンテントの差し込み機能から利用されます。 共有コンテントの登録は、アプリケーションの開始時に一度だけ行っておけば、帳票出力にてコンテント差し込みが行われるたびに利用されます。

詳しい利用法については、機能サンプルの「コンテントの差し込み」をご覧ください。

Fill

Fillメソッドを呼ぶことで、Reportにデータを渡すことができます。 このメソッドについての詳しい説明は「帳票にデータを渡す方法」にあります。

GetPages

GetPagesメソッドを呼ぶとReportのページ分割が行われます。 このメソッドはFillメソッドの後に呼び出す必要があります。

GetPagesメソッドの戻り値はReportPagesというオブジェクトです。 このオブジェクトについての詳しい説明は「ReportPageの仕様」にあります。


Copyright (c) 2013, SystemBase Co.,Ltd. All rights reserved.