Logging

DsExcel Java provides logging capabilities that can be used to monitor system runtime status and facilitate issue diagnosis and troubleshooting. The logging system is built upon Apache Commons Logging (JCL) as an abstraction layer, enabling seamless integration with mainstream logging frameworks such as Log4j, Logback, and SLF4J. In practical development, it is recommended to use Log4j2 as the preferred logging framework.

You can configure the log level to control the granularity of the log output. The commonly used log levels are debug, info, warn, and error, with the following priority: debug < info < warn < error.

After setting a specific log level, all log messages at that level and above will be recorded, while logs below that level will be ignored. For example, if the log level is set to info, logs at the info, warn, and error levels will be output, while debug logs will be suppressed.

The process for configuring the logging system is illustrated in the diagram below:

Project Dependencies

The logging function of DsExcel depends on JCL as an abstraction layer, which requires commons-logging.jar to be included in the classpath. For Gradle and Maven projects, this dependency is automatically included when you add the DsExcel dependency, and manual addition is not required. The dependencies of DsExcel are as follows, where x.x.x refers to the specific version number of DsExcel you are using.

• Gradle (build.gradle)

  implementation 'com.mescius.documents:dsexcel:x.x.x'

• Maven (pom.xml)

  <dependency>
     <groupId>com.mescius.documents</groupId>
     <artifactId>dsexcel</artifactId>
     <version>x.x.x</version>
  </dependency>

Enable Logging

The logging system of DsExcel is enabled by default, with the log level set to info by default. Log messages will automatically be output to the console without additional configuration.

Configuring Logging

To enable more advanced logging options, such as setting log levels or directing log output to files, it is recommended to use Log4j2 for log management. The steps are as follows:

1. Add the necessary Log4j2 dependencies to your Gradle or Maven project.

• Gradle (build.gradle)

  implementation 'org.apache.logging.log4j:log4j-api:2.17.2'
  implementation 'org.apache.logging.log4j:log4j-core:2.17.2'
  implementation 'org.apache.logging.log4j:log4j-jcl:2.17.2'

• Maven（pom.xml）

  <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-api</artifactId>
      <version>2.17.2</version>
  </dependency>
  <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-core</artifactId>
      <version>2.17.2</version>
  </dependency>
  <dependency>
      <groupId>org.apache.logging.log4j</groupId>
      <artifactId>log4j-jcl</artifactId>
      <version>2.17.2</version>
  </dependency>

2. Add the log configuration file log4j2.xml under the src/main/resources directory of your Gradle or Maven project.

<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
    <Appenders>
        <!-- Console Output --> 
        <Console name="STDOUT" target="SYSTEM_OUT">
            <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
        </Console>
        <!-- File Output -->
        <File name="FILE" fileName="mylog.log">
            <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
        </File>
    </Appenders>
    <Loggers>
        <Logger name="org.apache.fontbox" level="info"/>
        <Logger name="org.apache.pdfbox" level="info"/>
        <Logger name="org.apache.log4j.xml" level="info"/>
        <Root level="debug">
            <AppenderRef ref="STDOUT"/>
            <AppenderRef ref="FILE"/>
        </Root>
    </Loggers>
</Configuration>

Configuration Parameters:

• Appender: Defines the log output destination. Console specifies output to the console. File specifies output to a file. fileName allows you to customize the log file name and path.

• Logger: Sets the log level for a specified package or class.

• Root Logger: The global default logger configuration that determines the default log level and output settings.

The log level configured for a specific package or class (Logger) takes precedence over the global default log configuration (Root Logger). If a package or class defines its own log level, it will be used; otherwise, the Root Logger's global default level will apply.

Log Verification

After completing the above log configuration, you can verify that the logging system is working correctly by following these steps:

1. Execute the following code to export a PDF file.

   // Create a workbook.
   Workbook workbook = new Workbook();
   IWorksheet worksheet = workbook.getActiveSheet();
   
   worksheet.getRange("A1").setValue("This is a test file");
   
   // Save the workbook as a PDF file.
   workbook.save("LoggingSystem.pdf");

2. View logs in the console and the log file (such as mylog.log).

   ...
   2025-07-03 16:26:15,463 DEBUG [main] aX.o (null:-1) - Save pdf of the workbook.
   2025-07-03 16:26:15,466 DEBUG [main] aX.o (null:-1) - Paginate Start(Workbook)
   2025-07-03 16:26:15,538 DEBUG [main] excel.bu (null:-1) - Get instance of MypdfGraphics for fontsFolderPath: null
   2025-07-03 16:26:15,539 DEBUG [main] excel.bu (null:-1) - Get instance of MypdfGraphics(Use cache): com.grapecity.documents.excel.bu@54504ecd
   2025-07-03 16:26:15,542 DEBUG [main] excel.bu (null:-1) - Get instance of MypdfGraphics for fontsFolderPath: null
   2025-07-03 16:26:15,542 DEBUG [main] excel.bu (null:-1) - Get instance of MypdfGraphics(Use cache): com.grapecity.documents.excel.bu@54504ecd
   2025-07-03 16:26:15,573 DEBUG [main] bn.dE (null:-1) - GetDigitWidthOfDefaultStyle GraphicsType: Pdf
   ...