diff options
429 files changed, 38111 insertions, 1868 deletions
@@ -1,7 +1,7 @@ # https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features github: - description: "Mirror of Apache POI subversion. The Java API for Microsoft Documents." + description: "Mirror of Apache POI gitbox. The Java API for Microsoft Documents." homepage: https://poi.apache.org/ labels: - poi @@ -14,10 +14,33 @@ github: - powerpoint - visio + dependabot_alerts: true + dependabot_updates: false + features: # Enable wiki for documentation wiki: false # Enable issue management - issues: false + issues: true # Enable projects for project management boards projects: false + # Enable github discussions + discussions: true + + enabled_merge_buttons: + squash: true + merge: false + rebase: true + + protected_branches: + trunk: {} + +notifications: + commits: commits@poi.apache.org + issues: dev@poi.apache.org + pullrequests: dev@poi.apache.org + discussions: dev@poi.apache.org + jobs: dev@poi.apache.org + +publish: + whoami: asf-site diff --git a/README.rst b/README.rst index aa755940ea..8578fbdaac 100644 --- a/README.rst +++ b/README.rst @@ -53,18 +53,16 @@ Bug tracker: Source code: -* Official `Apache Subversion repo`_ at apache.org -* `ViewVC repo browser`_ at apache.org -* `GitHub git mirror`_ at github.com +* Official `Apache Git repo`_ at apache.org Requires Java 1.8 or later. Contributing ------------------ -* Download and install svn or git, Java JDK 1.8+, and Apache Ant 1.8+ or Gradle +* Download and install git, Java JDK 1.8+, and Apache Ant 1.8+ or Gradle -* Check out the code from svn or git +* Check out the code from git * Import the project into Eclipse or your favorite IDE @@ -100,7 +98,5 @@ To build the jar files for poi, poi-ooxml, poi-ooxml-lite, poi-ooxml-full and po .. _Bugzilla: https://bz.apache.org/bugzilla/buglist.cgi?product=POI .. _GitHub pull requests: https://github.com/apache/poi/pulls -.. _Apache Subversion repo: https://svn.apache.org/repos/asf/poi/trunk -.. _ViewVC repo browser: https://svn.apache.org/viewvc/poi/trunk -.. _GitHub git mirror: https://github.com/apache/poi +.. _Apache Git repo: https://github.com/apache/poi .. _How To Build page: http://poi.apache.org/devel/ diff --git a/build.gradle b/build.gradle index 13ea2c604f..95a9f62c3a 100644 --- a/build.gradle +++ b/build.gradle @@ -24,21 +24,21 @@ import javax.xml.xpath.XPathFactory buildscript { repositories { - maven { url 'https://plugins.gradle.org/m2/' } + maven { url = 'https://plugins.gradle.org/m2/' } mavenCentral() } } plugins { id 'base' - id 'com.dorongold.task-tree' version '2.1.1' + id 'com.dorongold.task-tree' version '4.0.1' id 'org.nosphere.apache.rat' version '0.8.1' id 'distribution' - id "com.github.spotbugs" version '6.0.27' - id 'de.thetaphi.forbiddenapis' version '3.8' + id 'com.github.spotbugs' version '6.1.13' // 6.2.0+ requires JDK 11 + id 'de.thetaphi.forbiddenapis' version '3.9' id 'org.sonarqube' version '4.0.0.2929' - id 'org.cyclonedx.bom' version '2.0.0' - id 'com.adarshr.test-logger' version '3.2.0' + id 'org.cyclonedx.bom' version '2.3.1' + id 'com.adarshr.test-logger' version '4.0.0' } repositories { @@ -67,7 +67,7 @@ configurations { } dependencies { - antLibs("org.junit.jupiter:junit-jupiter:5.11.4") + antLibs("org.junit.jupiter:junit-jupiter:5.13.4") antLibs("org.apache.ant:ant-junitlauncher:1.10.15") } @@ -77,20 +77,9 @@ ant.taskdef(name: "junit", wrapper { - gradleVersion = '8.12' + gradleVersion = '8.14.3' } -task adjustWrapperPropertiesFile { - doLast { - ant.replaceregexp(match:'^#.*', replace:'', flags:'g', byline:true) { - fileset(dir: project.projectDir, includes: 'gradle/wrapper/gradle-wrapper.properties') - } - new File(project.projectDir, 'gradle/wrapper/gradle-wrapper.properties').with { it.text = it.readLines().findAll { it }.sort().join('\n') } - ant.fixcrlf(file: 'gradle/wrapper/gradle-wrapper.properties', eol: 'lf') - } -} -wrapper.finalizedBy adjustWrapperPropertiesFile - group = 'org.apache.poi' /** @@ -100,7 +89,7 @@ allprojects { // apply plugin: 'eclipse' apply plugin: 'idea' - version = '5.4.1-SNAPSHOT' + version = '5.5.0-SNAPSHOT' } /** @@ -118,21 +107,21 @@ subprojects { apply plugin: 'com.adarshr.test-logger' ext { - bouncyCastleVersion = '1.80' - commonsCodecVersion = '1.17.2' - commonsCompressVersion = '1.27.1' - commonsIoVersion = '2.18.0' + bouncyCastleVersion = '1.81' + commonsCodecVersion = '1.19.0' + commonsCompressVersion = '1.28.0' + commonsIoVersion = '2.20.0' commonsMathVersion = '3.6.1' - junitVersion = '5.11.4' + junitVersion = '5.13.4' log4jVersion = '2.24.3' mockitoVersion = '4.11.0' hamcrestVersion = '3.0' xmlbeansVersion = '5.3.0' - batikVersion = '1.18' - graphics2dVersion = '3.0.2' - pdfboxVersion = '3.0.3' - saxonVersion = '12.5' - xmlSecVersion = '3.0.5' + batikVersion = '1.19' + graphics2dVersion = '3.0.3' + pdfboxVersion = '3.0.5' + saxonVersion = '12.8' + xmlSecVersion = '3.0.6' apiGuardianVersion = '1.1.2' jdkVersion = (project.properties['jdkVersion'] ?: '8') as int @@ -140,9 +129,9 @@ subprojects { jdkVendor = (project.properties['jdkVendor'] ?: '') as String JAVA9_SRC = 'src/main/java9' - JAVA9_OUT = "${buildDir}/classes/java9/main/" + JAVA9_OUT = layout.buildDirectory.dir('classes/java9/main/').get().asFile.absolutePath TEST9_SRC = 'src/test/java9' - TEST9_OUT = "${buildDir}/classes/java9/test/" + TEST9_OUT = layout.buildDirectory.dir('classes/java9/test/').get().asFile.absolutePath VERSIONS9 = 'META-INF/versions/9' NO_SCRATCHPAD = (findProperty("scratchpad.ignore") == "true") @@ -150,25 +139,25 @@ subprojects { } configurations { - all { + configureEach { resolutionStrategy { force "commons-io:commons-io:${commonsIoVersion}" - force 'org.slf4j:slf4j-api:2.0.16' - force 'com.fasterxml.woodstox:woodstox-core:7.1.0' + force 'org.slf4j:slf4j-api:2.0.17' + force 'com.fasterxml.woodstox:woodstox-core:7.1.1' } } } - tasks.withType(JavaCompile) { + tasks.withType(JavaCompile).configureEach { options.encoding = 'UTF-8' options.compilerArgs += '-Xlint:unchecked' options.deprecation = true options.incremental = true } - tasks.withType(Test) { + tasks.withType(Test).configureEach { systemProperty "file.encoding", "UTF-8" } - tasks.withType(Javadoc) { + tasks.withType(Javadoc).configureEach { options.encoding = 'UTF-8' } tasks.withType(AbstractArchiveTask).configureEach { @@ -182,7 +171,9 @@ subprojects { } dependencies { - testImplementation "org.junit.jupiter:junit-jupiter:${junitVersion}" + testImplementation platform("org.junit:junit-bom:${junitVersion}") + testImplementation 'org.junit.jupiter:junit-jupiter' + testRuntimeOnly 'org.junit.platform:junit-platform-launcher' testImplementation "org.mockito:mockito-core:${mockitoVersion}" testImplementation "org.hamcrest:hamcrest:${hamcrestVersion}" testImplementation "org.apache.logging.log4j:log4j-core:${log4jVersion}" @@ -227,13 +218,13 @@ subprojects { // helper-target to get a directory with all third-party libraries // this is used for mass-regression-testing - task getDeps(type: Copy) { + tasks.register('getDeps', Copy) { from sourceSets.main.runtimeClasspath into 'build/runtime/' } - tasks.withType(Jar) { - duplicatesStrategy = 'fail' + tasks.withType(Jar).configureEach { + duplicatesStrategy = DuplicatesStrategy.FAIL destinationDirectory = file("../build/dist/maven/${project.archivesBaseName}") doLast { @@ -375,10 +366,10 @@ subprojects { ] // detect if running on Jenkins/CI - isCIBuild |= Boolean.valueOf(System.getenv("CI_BUILD")); + isCIBuild |= Boolean.valueOf(System.getenv("CI_BUILD")) if (isCIBuild) { - System.out.println("Run with reduced parallelism for CI build"); + System.out.println("Run with reduced parallelism for CI build") jvmArgs += [ // Strictly serial @@ -432,7 +423,7 @@ subprojects { jvmArgs += [ // see https://github.com/java9-modularity/gradle-modules-plugin/issues/97 // opposed to the recommendation there, it doesn't work to add ... to the dependencies - // testRuntimeOnly 'org.junit.platform:junit-platform-launcher:1.11.0' + // testRuntimeOnly 'org.junit.platform:junit-platform-launcher:1.13.2' // gradles gradle-worker.jar is still not a JPMS module and thus runs as unnamed module '--add-exports','org.junit.platform.commons/org.junit.platform.commons.util=org.apache.poi.poi', '--add-exports','org.junit.platform.commons/org.junit.platform.commons.util=ALL-UNNAMED', @@ -454,7 +445,7 @@ subprojects { } jacoco { - toolVersion = '0.8.12' + toolVersion = '0.8.13' } jacocoTestReport { @@ -500,14 +491,13 @@ subprojects { } forbiddenApisTest { - // forbiddenapis bundled signatures max supported version is 17 - // also see https://github.com/policeman-tools/forbidden-apis/issues/191 - targetCompatibility = (JavaVersion.VERSION_17.isCompatibleWith(JavaVersion.current()) ? JavaVersion.current() : JavaVersion.VERSION_17) + // forbiddenapis:3.8 bundled signatures max supported version is 23 + targetCompatibility = (JavaVersion.VERSION_17.isCompatibleWith(JavaVersion.current()) ? JavaVersion.current() : JavaVersion.VERSION_23) } forbiddenApisMain { signaturesFiles += files('../src/resources/devtools/forbidden-signatures-prod.txt') - targetCompatibility = (JavaVersion.VERSION_17.isCompatibleWith(JavaVersion.current()) ? JavaVersion.current() : JavaVersion.VERSION_17) + targetCompatibility = (JavaVersion.VERSION_17.isCompatibleWith(JavaVersion.current()) ? JavaVersion.current() : JavaVersion.VERSION_23) } publishing { @@ -597,7 +587,7 @@ subprojects { generatePomFileForPOIPublication.destination = "../build/dist/maven/${project.archivesBaseName}/${project.archivesBaseName}-${project.version}.pom" - tasks.withType(GenerateModuleMetadata) { + tasks.withType(GenerateModuleMetadata).configureEach { enabled = false } @@ -625,14 +615,14 @@ subprojects { } // initial try to provide a combined JavaDoc, grouping is still missing here, though! -task allJavaDoc(type: Javadoc) { - var prj = [ project(':poi'), project(':poi-excelant'), project(':poi-ooxml'), project(':poi-scratchpad') ] +tasks.register('allJavaDoc', Javadoc) { + var prj = [project(':poi'), project(':poi-excelant'), project(':poi-ooxml'), project(':poi-scratchpad')] source prj.collect { it.sourceSets.main.allJava } // for possible settings see https://docs.gradle.org/current/dsl/org.gradle.api.tasks.javadoc.Javadoc.html classpath = files(subprojects.collect { it.sourceSets.main.compileClasspath }) - destinationDir = file("${buildDir}/docs/javadoc") - maxMemory="2048M" + destinationDir = layout.buildDirectory.dir('docs/javadoc').get().asFile + maxMemory = "2048M" // for possible options see https://docs.gradle.org/current/javadoc/org/gradle/external/javadoc/StandardJavadocDocletOptions.html options.use = true @@ -647,7 +637,7 @@ task allJavaDoc(type: Javadoc) { options.group('SS - Common Spreadsheet Format', 'org.apache.poi.ss*') options.group('HSSF - Horrible Spreadsheet Format', 'org.apache.poi.hssf*') options.group('XSSF - Open Office XML Spreadsheet Format', 'org.apache.poi.xssf*') - options.group('SL - Common Slideshow Format', 'org.apache.poi.sl*') + options.group('SL - Common Slideshow Format', 'org.apache.poi.sl*') options.group('HSLF - Horrible Slideshow Format', 'org.apache.poi.hslf*', 'org.apache.poi.hwmf*', 'org.apache.poi.hemf*') options.group('XSLF - Open Office XML Slideshow Format', 'org.apache.poi.xslf*') options.group('HWPF - Horrible Word Processor Format', 'org.apache.poi.hwpf*') @@ -725,21 +715,21 @@ rat { } task jenkins(dependsOn: [ - 'replaceVersion', - subprojects.build, - subprojects.check, - subprojects.javadoc, - subprojects.jacocoTestReport, - subprojects.getDeps, - 'srcDistZip', - 'srcDistTar', - rat + 'replaceVersion', + subprojects.build, + subprojects.check, + subprojects.javadoc, + subprojects.jacocoTestReport, + subprojects.getDeps, + 'srcDistZip', + 'srcDistTar', + rat ]) {} task jenkinsLite(dependsOn: [ - 'replaceVersion', - subprojects.build, - subprojects.test + 'replaceVersion', + subprojects.build, + subprojects.test ]) {} /*task downloadJarsToLibs() { @@ -753,14 +743,14 @@ task jenkinsLite(dependsOn: [ //compileJava.dependsOn 'downloadJarsToLibs' -task replaceVersion() { +tasks.register('replaceVersion') { outputs.upToDateWhen { false } var version = subprojects[0].version var tokens = [ - [ 'osgi', 'pom.xml', '(packaging>\\n\\s*<version>)[0-9.]+(?:-SNAPSHOT|-RC\\d+)?', "\\1${version}" ], - [ 'osgi', 'pom.xml', '(<poi.version>)[0-9.]+(?:-SNAPSHOT|-RC\\d+)?', "\\1${version}" ] - // [ '.', 'build.gradle', ' version = \'[0-9.]+(?:-SNAPSHOT)?\'', " version = '${version}'" ] + ['osgi', 'pom.xml', '(packaging>\\n\\s*<version>)[0-9.]+(?:-SNAPSHOT|-RC\\d+)?', "\\1${version}"], + ['osgi', 'pom.xml', '(<poi.version>)[0-9.]+(?:-SNAPSHOT|-RC\\d+)?', "\\1${version}"] + // [ '.', 'build.gradle', ' version = \'[0-9.]+(?:-SNAPSHOT)?\'', " version = '${version}'" ] ] doLast { @@ -784,7 +774,7 @@ task zipJavadocs(type: Zip, dependsOn: allJavaDoc) { archiveExtension = 'jar' } -tasks.withType(Tar) { +tasks.withType(Tar).configureEach { compression = Compression.GZIP archiveExtension = 'tgz' } @@ -843,7 +833,7 @@ distributions { } } -task soLinkCheck() { +tasks.register('soLinkCheck') { doLast { def path = ant.path { fileset(dir: '.', includes: '**/*.java') { @@ -887,7 +877,7 @@ srcDistZip.dependsOn srcDep soLinkCheck.dependsOn srcDep rat.dependsOn soLinkCheck -task fixDistDir { +tasks.register('fixDistDir') { doLast { ant.mkdir(dir: 'build/dist') ant.move(todir: 'build/dist') { @@ -42,7 +42,7 @@ under the License. <description>The Apache POI project Ant build.</description> - <property name="version.id" value="5.4.1-SNAPSHOT"/> + <property name="version.id" value="5.5.0-SNAPSHOT"/> <property name="release.rc" value=""/> <property environment="env"/> @@ -263,30 +263,30 @@ under the License. <!-- jars in the /lib directory, see the fetch-jars target--> - <dependency prefix="main.commons-codec" artifact="commons-codec:commons-codec:1.17.2" usage="main"/> - <dependency prefix="main.commons-collections4" artifact="org.apache.commons:commons-collections4:4.4" usage="main"/> + <dependency prefix="main.commons-codec" artifact="commons-codec:commons-codec:1.19.0" usage="main"/> + <dependency prefix="main.commons-collections4" artifact="org.apache.commons:commons-collections4:4.5.0" usage="main"/> <dependency prefix="main.commons-math3" artifact="org.apache.commons:commons-math3:3.6.1" usage="main"/> - <dependency prefix="main.commons-io" artifact="commons-io:commons-io:2.18.0" usage="main"/> + <dependency prefix="main.commons-io" artifact="commons-io:commons-io:2.20.0" usage="main"/> <dependency prefix="main.com.zaxxer" artifact="com.zaxxer:SparseBitSet:1.3" usage="main"/> <dependency prefix="main.log4j-api" artifact="org.apache.logging.log4j:log4j-api:2.24.3" usage="main"/> - <dependency prefix="main.junit-api" artifact="org.junit.jupiter:junit-jupiter-api:5.11.4" usage="main-tests"/> - <dependency prefix="main.junit-jengine" artifact="org.junit.jupiter:junit-jupiter-engine:5.11.4" usage="main-tests"/> - <dependency prefix="main.junit-params" artifact="org.junit.jupiter:junit-jupiter-params:5.11.4" usage="main-tests"/> + <dependency prefix="main.junit-api" artifact="org.junit.jupiter:junit-jupiter-api:5.13.4" usage="main-tests"/> + <dependency prefix="main.junit-jengine" artifact="org.junit.jupiter:junit-jupiter-engine:5.13.4" usage="main-tests"/> + <dependency prefix="main.junit-params" artifact="org.junit.jupiter:junit-jupiter-params:5.13.4" usage="main-tests"/> <dependency prefix="main.junit-opentest4j" artifact="org.opentest4j:opentest4j:1.2.0" usage="main-tests"/> <dependency prefix="main.junit-apiguardian" artifact="org.apiguardian:apiguardian-api:1.1.2" usage="main-tests"/> - <dependency prefix="main.junit-pcommons" artifact="org.junit.platform:junit-platform-commons:1.11.0" usage="main-tests"/> - <dependency prefix="main.junit-pengine" artifact="org.junit.platform:junit-platform-engine:1.11.0" usage="main-tests"/> - <dependency prefix="main.junit-plauncher" artifact="org.junit.platform:junit-platform-launcher:1.11.0" usage="main-tests"/> + <dependency prefix="main.junit-pcommons" artifact="org.junit.platform:junit-platform-commons:1.13.4" usage="main-tests"/> + <dependency prefix="main.junit-pengine" artifact="org.junit.platform:junit-platform-engine:1.13.4" usage="main-tests"/> + <dependency prefix="main.junit-plauncher" artifact="org.junit.platform:junit-platform-launcher:1.13.4" usage="main-tests"/> <dependency prefix="main.jmh" artifact="org.openjdk.jmh:jmh-core:1.35" usage="main-tests"/> <dependency prefix="main.jmhAnnotation" artifact="org.openjdk.jmh:jmh-generator-annprocess:1.35" usage="main-tests"/> <dependency prefix="main.hamcrest" artifact="org.hamcrest:hamcrest:3.0" usage="main-tests"/> - <dependency prefix="main.xmlunit" artifact="org.xmlunit:xmlunit-core:2.10.0" usage="main-tests"/> + <dependency prefix="main.xmlunit" artifact="org.xmlunit:xmlunit-core:2.10.3" usage="main-tests"/> <dependency prefix="main.mockito" artifact="org.mockito:mockito-core:4.11.0" usage="main-tests"/> - <dependency prefix="main.byte-buddy" artifact="net.bytebuddy:byte-buddy:1.16.1" usage="main-tests"/> - <dependency prefix="main.byte-buddy-agent" artifact="net.bytebuddy:byte-buddy-agent:1.16.1" usage="main-tests"/> + <dependency prefix="main.byte-buddy" artifact="net.bytebuddy:byte-buddy:1.17.5" usage="main-tests"/> + <dependency prefix="main.byte-buddy-agent" artifact="net.bytebuddy:byte-buddy-agent:1.17.5" usage="main-tests"/> <dependency prefix="main.objenesis" artifact="org.objenesis:objenesis:3.1" usage="main-tests"/> <dependency prefix="main.log4j-core" artifact="org.apache.logging.log4j:log4j-core:2.24.3" usage="main-tests"/> <dependency prefix="main.commons-logging" artifact="commons-logging:commons-logging:1.2" usage="main-tests"/> @@ -295,56 +295,57 @@ under the License. <dependency prefix="main.antlauncher" artifact="org.apache.ant:ant-launcher:1.10.15" usage="excelant"/> <!-- xml signature libs - not part of the distribution --> - <dependency prefix="dsig.xmlsec" artifact="org.apache.santuario:xmlsec:3.0.5" usage="ooxml-provided"/> - <dependency prefix="dsig.bouncycastle-prov" artifact="org.bouncycastle:bcprov-jdk18on:1.80" usage="ooxml-provided"/> - <dependency prefix="dsig.bouncycastle-pkix" artifact="org.bouncycastle:bcpkix-jdk18on:1.80" usage="ooxml-provided"/> - <dependency prefix="dsig.bouncycastle-util" artifact="org.bouncycastle:bcutil-jdk18on:1.80" usage="ooxml-provided"/> + <dependency prefix="dsig.xmlsec" artifact="org.apache.santuario:xmlsec:3.0.6" usage="ooxml-provided"/> + <dependency prefix="dsig.bouncycastle-prov" artifact="org.bouncycastle:bcprov-jdk18on:1.81" usage="ooxml-provided"/> + <dependency prefix="dsig.bouncycastle-pkix" artifact="org.bouncycastle:bcpkix-jdk18on:1.81" usage="ooxml-provided"/> + <dependency prefix="dsig.bouncycastle-util" artifact="org.bouncycastle:bcutil-jdk18on:1.81" usage="ooxml-provided"/> <!-- only used for signing the release - not used with the ooxml signatures --> - <dependency prefix="dsig.bouncycastle-bcpg" artifact="org.bouncycastle:bcpg-jdk18on:1.80" usage="util"/> + <dependency prefix="dsig.bouncycastle-bcpg" artifact="org.bouncycastle:bcpg-jdk18on:1.81" usage="util"/> <dependency prefix="ooxml.test.stax2" artifact="org.codehaus.woodstox:stax2-api:4.2.1" usage="ooxml-provided"/> <!-- svg/batik/pdf libs - not part of the distribution - move batik to its own directory because of JPMS module-path issues --> <dependency prefix="svg.xml-apis-ext" artifact="xml-apis:xml-apis-ext:1.3.04" usage="ooxml-batik"/> - <dependency prefix="svg.xmlgraphics-commons" artifact="org.apache.xmlgraphics:xmlgraphics-commons:2.9" usage="ooxml-batik"/> - <dependency prefix="svg.batik-anim" artifact="org.apache.xmlgraphics:batik-anim:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-awt-util" artifact="org.apache.xmlgraphics:batik-awt-util:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-bridge" artifact="org.apache.xmlgraphics:batik-bridge:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-codec" artifact="org.apache.xmlgraphics:batik-codec:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-constants" artifact="org.apache.xmlgraphics:batik-constants:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-css" artifact="org.apache.xmlgraphics:batik-css:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-dom" artifact="org.apache.xmlgraphics:batik-dom:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-ext" artifact="org.apache.xmlgraphics:batik-ext:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-gvt" artifact="org.apache.xmlgraphics:batik-gvt:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-i18n" artifact="org.apache.xmlgraphics:batik-i18n:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-parser" artifact="org.apache.xmlgraphics:batik-parser:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-script" artifact="org.apache.xmlgraphics:batik-script:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-shared-resources" artifact="org.apache.xmlgraphics:batik-shared-resources:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-svg-dom" artifact="org.apache.xmlgraphics:batik-svg-dom:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-svggen" artifact="org.apache.xmlgraphics:batik-svggen:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-svgrasterizer" artifact="org.apache.xmlgraphics:batik-svgrasterizer:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-transcoder" artifact="org.apache.xmlgraphics:batik-transcoder:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-util" artifact="org.apache.xmlgraphics:batik-util:1.18" usage="ooxml-batik"/> - <dependency prefix="svg.batik-xml" artifact="org.apache.xmlgraphics:batik-xml:1.18" usage="ooxml-batik"/> - <dependency prefix="pdf.pdfbox" artifact="org.apache.pdfbox:pdfbox:3.0.3" usage="ooxml-provided"/> - <dependency prefix="pdf.pdfbox.io" artifact="org.apache.pdfbox:pdfbox-io:3.0.3" usage="ooxml-provided"/> - <dependency prefix="pdf.fontbox" artifact="org.apache.pdfbox:fontbox:3.0.3" usage="ooxml-provided"/> - <dependency prefix="pdf.graphics2d" artifact="de.rototor.pdfbox:graphics2d:3.0.2" usage="ooxml-provided"/> + <dependency prefix="svg.xmlgraphics-commons" artifact="org.apache.xmlgraphics:xmlgraphics-commons:2.11" usage="ooxml-batik"/> + <dependency prefix="svg.batik-anim" artifact="org.apache.xmlgraphics:batik-anim:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-awt-util" artifact="org.apache.xmlgraphics:batik-awt-util:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-bridge" artifact="org.apache.xmlgraphics:batik-bridge:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-codec" artifact="org.apache.xmlgraphics:batik-codec:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-constants" artifact="org.apache.xmlgraphics:batik-constants:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-css" artifact="org.apache.xmlgraphics:batik-css:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-dom" artifact="org.apache.xmlgraphics:batik-dom:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-ext" artifact="org.apache.xmlgraphics:batik-ext:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-gvt" artifact="org.apache.xmlgraphics:batik-gvt:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-i18n" artifact="org.apache.xmlgraphics:batik-i18n:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-parser" artifact="org.apache.xmlgraphics:batik-parser:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-script" artifact="org.apache.xmlgraphics:batik-script:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-shared-resources" artifact="org.apache.xmlgraphics:batik-shared-resources:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-svg-dom" artifact="org.apache.xmlgraphics:batik-svg-dom:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-svggen" artifact="org.apache.xmlgraphics:batik-svggen:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-svgrasterizer" artifact="org.apache.xmlgraphics:batik-svgrasterizer:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-transcoder" artifact="org.apache.xmlgraphics:batik-transcoder:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-util" artifact="org.apache.xmlgraphics:batik-util:1.19" usage="ooxml-batik"/> + <dependency prefix="svg.batik-xml" artifact="org.apache.xmlgraphics:batik-xml:1.19" usage="ooxml-batik"/> + <dependency prefix="pdf.pdfbox" artifact="org.apache.pdfbox:pdfbox:3.0.5" usage="ooxml-provided"/> + <dependency prefix="pdf.pdfbox.io" artifact="org.apache.pdfbox:pdfbox-io:3.0.5" usage="ooxml-provided"/> + <dependency prefix="pdf.fontbox" artifact="org.apache.pdfbox:fontbox:3.0.5" usage="ooxml-provided"/> + <dependency prefix="pdf.graphics2d" artifact="de.rototor.pdfbox:graphics2d:3.0.3" usage="ooxml-provided"/> <!-- jars in the ooxml-lib directory, see the fetch-ooxml-jars target--> <dependency prefix="ooxml.curvesapi" artifact="com.github.virtuald:curvesapi:1.08" usage="ooxml"/> <dependency prefix="ooxml.xmlbeans" artifact="org.apache.xmlbeans:xmlbeans:5.3.0" usage="ooxml"/> - <dependency prefix="ooxml.commons-compress" artifact="org.apache.commons:commons-compress:1.27.1" usage="ooxml"/> - <dependency prefix="ooxml.commons-lang3" artifact="org.apache.commons:commons-lang3:3.12.0" usage="ooxml"/> + <dependency prefix="ooxml.commons-compress" artifact="org.apache.commons:commons-compress:1.28.0" usage="ooxml"/> + <dependency prefix="ooxml.commons-lang3" artifact="org.apache.commons:commons-lang3:3.18.0" usage="ooxml"/> <!-- jars in the ooxml-test-lib directory, see the fetch-ooxml-jars target--> <dependency prefix="ooxml.test.reflections" artifact="org.reflections:reflections:0.10.2" usage="ooxml-tests"/> - <dependency prefix="ooxml.test.guava" artifact="com.google.guava:guava:33.3.0-jre" usage="ooxml-tests"/> + <dependency prefix="ooxml.test.guava" artifact="com.google.guava:guava:33.4.8-jre" usage="ooxml-tests"/> + <dependency prefix="ooxml.test.guava.failureaccess" artifact="com.google.guava:failureaccess:1.0.3" usage="ooxml-tests"/> <dependency prefix="ooxml.test.javassist" artifact="org.javassist:javassist:3.27.0-GA" usage="ooxml-tests"/> - <dependency prefix="ooxml.test.slf4j-api" artifact="org.slf4j:slf4j-api:2.0.16" usage="ooxml-tests"/> + <dependency prefix="ooxml.test.slf4j-api" artifact="org.slf4j:slf4j-api:2.0.17" usage="ooxml-tests"/> <dependency prefix="ooxml.test.opczip" artifact="com.github.rzymek:opczip:1.2.0" usage="ooxml-tests"/> <!-- coverage libs --> - <dependency prefix="jacoco" artifact="org.jacoco:jacoco:0.8.12" usage="util" packaging="zip"/> + <dependency prefix="jacoco" artifact="org.jacoco:jacoco:0.8.13" usage="util" packaging="zip"/> <dependency prefix="asm" artifact="org.ow2.asm:asm:9.5" usage="util"/> <dependency prefix="asm-commons" artifact="org.ow2.asm:asm-commons:9.5" usage="util"/> <dependency prefix="asm-tree" artifact="org.ow2.asm:asm-tree:9.5" usage="util"/> @@ -463,6 +464,7 @@ under the License. <path refid="main.classpath"/> <pathelement location="${main.output.dir}"/> <pathelement location="${ooxml.test.guava.jar}"/> + <pathelement location="${ooxml.test.guava.failureaccess.jar}"/> <pathelement location="${ooxml.test.opczip.jar}"/> <!-- classes are omitted on test cases outside the xml-dsign area to avoid classpath poisoning --> <!--path refid="ooxml.xmlsec.classpath"/--> @@ -516,6 +518,7 @@ under the License. <path id="test.ooxml.reflections.classpath"> <pathelement location="${ooxml.test.reflections.jar}"/> <pathelement location="${ooxml.test.guava.jar}"/> + <pathelement location="${ooxml.test.guava.failureaccess.jar}"/> <pathelement location="${ooxml.test.javassist.jar}"/> </path> @@ -698,6 +701,7 @@ under the License. <include name="batik*.jar"/> <include name="slf4j*-1.*.jar"/> <include name="xmlsec-2*.jar"/> + <include name="xmlgraphics-commons-*.jar"/> </fileset> <fileset dir="${basedir}/lib/ooxml-tests"> <include name="guava-20.0.jar"/> @@ -833,6 +837,7 @@ under the License. <available file="${ooxml.commons-lang3.jar}"/> <available file="${ooxml.test.reflections.jar}"/> <available file="${ooxml.test.guava.jar}"/> + <available file="${ooxml.test.guava.failureaccess.jar}"/> <available file="${ooxml.test.javassist.jar}"/> <available file="${ooxml.test.slf4j-api.jar}"/> <available file="${ooxml.test.opczip.jar}"/> @@ -876,6 +881,7 @@ under the License. <downloadfile src="${ooxml.commons-lang3.url}" dest="${ooxml.commons-lang3.jar}"/> <downloadfile src="${ooxml.test.reflections.url}" dest="${ooxml.test.reflections.jar}"/> <downloadfile src="${ooxml.test.guava.url}" dest="${ooxml.test.guava.jar}"/> + <downloadfile src="${ooxml.test.guava.failureaccess.url}" dest="${ooxml.test.guava.failureaccess.jar}"/> <downloadfile src="${ooxml.test.javassist.url}" dest="${ooxml.test.javassist.jar}"/> <downloadfile src="${ooxml.test.slf4j-api.url}" dest="${ooxml.test.slf4j-api.jar}"/> <downloadfile src="${ooxml.test.opczip.url}" dest="${ooxml.test.opczip.jar}"/> @@ -2582,16 +2588,16 @@ under the License. <dependency prefix="spotbugs.dom4j" artifact="org.dom4j:dom4j:2.1.4" usage="${spotbugs.lib}"/> <dependency prefix="spotbugs.jaxen" artifact="jaxen:jaxen:2.0.0" usage="${spotbugs.lib}"/> <dependency prefix="spotbugs.bcel" artifact="org.apache.bcel:bcel:6.9.0" usage="${spotbugs.lib}"/> - <dependency prefix="spotbugs.slf4j-api" artifact="org.slf4j:slf4j-api:2.0.13" usage="${spotbugs.lib}"/> + <dependency prefix="spotbugs.slf4j-api" artifact="org.slf4j:slf4j-api:2.0.17" usage="${spotbugs.lib}"/> <dependency prefix="spotbugs.commons-lang" artifact="org.apache.commons:commons-lang3:3.14.0" usage="${spotbugs.lib}"/> <dependency prefix="spotbugs.commons-text" artifact="org.apache.commons:commons-text:1.10.0" usage="${spotbugs.lib}"/> <dependency prefix="spotbugs.commons-codec" artifact="commons-codec:commons-codec:1.15" usage="${spotbugs.lib}"/> <dependency prefix="spotbugs.commons-logging" artifact="commons-logging:commons-logging:1.2" usage="${spotbugs.lib}"/> <dependency prefix="spotbugs.jcip-annotations" artifact="net.jcip:jcip-annotations:1.0" usage="${spotbugs.lib}"/> <dependency prefix="spotbugs.icu4j" artifact="com.ibm.icu:icu4j:68.2" usage="${spotbugs.lib}" target="icu4j-68.2.jar"/> - <dependency prefix="spotbugs.log4j-api" artifact="org.apache.logging.log4j:log4j-api:2.23.1" usage="${spotbugs.lib}"/> - <dependency prefix="spotbugs.log4j-core" artifact="org.apache.logging.log4j:log4j-core:2.23.1" usage="${spotbugs.lib}"/> - <dependency prefix="spotbugs.log4j-slf4j18-impl" artifact="org.apache.logging.log4j:log4j-slf4j2-impl:2.23.1" usage="${spotbugs.lib}"/> + <dependency prefix="spotbugs.log4j-api" artifact="org.apache.logging.log4j:log4j-api:2.24.3" usage="${spotbugs.lib}"/> + <dependency prefix="spotbugs.log4j-core" artifact="org.apache.logging.log4j:log4j-core:2.24.3" usage="${spotbugs.lib}"/> + <dependency prefix="spotbugs.log4j-slf4j18-impl" artifact="org.apache.logging.log4j:log4j-slf4j2-impl:2.24.3" usage="${spotbugs.lib}"/> <dependency prefix="spotbugs.saxon" artifact="net.sf.saxon:Saxon-HE:12.4" usage="${spotbugs.lib}"/> <dependency prefix="spotbugs.xmlresolver" artifact="org.xmlresolver:xmlresolver:5.2.2" usage="${spotbugs.lib}"/> diff --git a/doap_POI.rdf b/doap_POI.rdf index 88606eb0bd..b80b14848b 100644 --- a/doap_POI.rdf +++ b/doap_POI.rdf @@ -37,6 +37,13 @@ <category rdf:resource="https://projects.apache.org/category/library" /> <release> <Version> + <name>Apache POI 5.4.1</name> + <created>2025-04-06</created> + <revision>5.4.1</revision> + </Version> + </release> + <release> + <Version> <name>Apache POI 5.4.0</name> <created>2025-01-08</created> <revision>5.4.0</revision> @@ -246,10 +253,10 @@ </Version> </release> <repository> - <SVNRepository> - <location rdf:resource="https://svn.apache.org/repos/asf/poi/"/> - <browse rdf:resource="https://svn.apache.org/viewvc/poi/"/> - </SVNRepository> + <GitRepository> + <location rdf:resource="https://github.com/apache/poi.git"/> + <browse rdf:resource="https://github.com/apache/poi/"/> + </GitRepository> </repository> <maintainer> <foaf:Person> diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties index cea7a793a8..d4081da476 100644 --- a/gradle/wrapper/gradle-wrapper.properties +++ b/gradle/wrapper/gradle-wrapper.properties @@ -1,6 +1,6 @@ distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists -distributionUrl=https\://services.gradle.org/distributions/gradle-8.12-bin.zip +distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-bin.zip networkTimeout=10000 validateDistributionUrl=true zipStoreBase=GRADLE_USER_HOME diff --git a/jenkins/create_jobs.groovy b/jenkins/create_jobs.groovy index 7f680ce0bc..980fbebdc5 100644 --- a/jenkins/create_jobs.groovy +++ b/jenkins/create_jobs.groovy @@ -28,18 +28,16 @@ def poijobs = [ ], [ name: 'POI-DSL-1.17', jdk: '1.17', trigger: 'H */12 * * *', skipcigame: true ], - // Jenkins on ci-builds.apache.org does not support spotbugs with a new enough version of asm for Java18+ - [ name: 'POI-DSL-1.21', jdk: '1.21', trigger: 'H */12 * * *', skipcigame: true, skipSpotbugs: true + [ name: 'POI-DSL-1.21', jdk: '1.21', trigger: 'H */12 * * *', skipcigame: true ], - // Jenkins on ci-builds.apache.org does not support spotbugs with a new enough version of asm for Java18+ - [ name: 'POI-DSL-1.22', jdk: '1.22', trigger: triggerSundays, skipcigame: true, skipSpotbugs: true + [ name: 'POI-DSL-1.23', jdk: '1.23', trigger: triggerSundays, skipcigame: true, + // let's save some CPU cycles here, 23 is not an LTS and JDK 24 is out + disabled: true ], - // Jenkins on ci-builds.apache.org does not support spotbugs with a new enough version of asm for Java18+ - [ name: 'POI-DSL-1.23', jdk: '1.23', trigger: triggerSundays, skipcigame: true, skipSpotbugs: true + [ name: 'POI-DSL-1.24', jdk: '1.24', trigger: triggerSundays, skipcigame: true, ], - // Jenkins on ci-builds.apache.org does not support spotbugs with a new enough version of asm for Java18+ - [ name: 'POI-DSL-1.24', jdk: '1.24', trigger: triggerSundays, skipcigame: true, skipSpotbugs: true, - // use Ant for building until Gradle supports JDK 24 + [ name: 'POI-DSL-1.25', jdk: '1.25', trigger: triggerSundays, skipcigame: true, skipSpotbugs: true, + // use Ant for building until Gradle supports JDK 25 // see https://docs.gradle.org/current/userguide/compatibility.html // and https://github.com/gradle/gradle/issues/31625 useAnt: true @@ -84,11 +82,14 @@ def poijobs = [ ], [ name: 'POI-DSL-Windows-1.21', jdk: '1.21', trigger: 'H */12 * * *', windows: true, slaves: 'Windows', skipcigame: true ], - [ name: 'POI-DSL-Windows-1.22', jdk: '1.22', trigger: triggerSundays, windows: true, slaves: 'Windows', skipcigame: true - ], - [ name: 'POI-DSL-Windows-1.23', jdk: '1.23', trigger: triggerSundays, windows: true, slaves: 'Windows', skipcigame: true + [ name: 'POI-DSL-Windows-1.23', jdk: '1.23', trigger: triggerSundays, windows: true, slaves: 'Windows', skipcigame: true, + // let's save some CPU cycles here, 23 is not an LTS and JDK 24 is out + disabled: true ], [ name: 'POI-DSL-Windows-1.24', jdk: '1.24', trigger: triggerSundays, windows: true, slaves: 'Windows', skipcigame: true, + ], + [ name: 'POI-DSL-Windows-1.25', jdk: '1.25', trigger: triggerSundays, windows: true, slaves: 'Windows', skipcigame: true, + skipSpotbugs: true, // use Ant for building until Gradle supports JDK 24 // see https://docs.gradle.org/current/userguide/compatibility.html // and https://github.com/gradle/gradle/issues/31625 @@ -105,31 +106,22 @@ def xmlbeansjobs = [ ], [ name: 'POI-XMLBeans-DSL-1.17', jdk: '1.17', trigger: 'H */12 * * *', skipcigame: true, ], - [ name: 'POI-XMLBeans-DSL-1.18', jdk: '1.18', trigger: triggerSundays, skipcigame: true, - // let's save some CPU cycles here, 18 is not an LTS and JDK 20 is out - disabled: true - ], - [ name: 'POI-XMLBeans-DSL-1.19', jdk: '1.19', trigger: triggerSundays, skipcigame: true, - // let's save some CPU cycles here, 19 is not an LTS - disabled: true + [ name: 'POI-XMLBeans-DSL-1.21', jdk: '1.21', trigger: 'H */12 * * *', skipcigame: true, ], - [ name: 'POI-XMLBeans-DSL-1.20', jdk: '1.20', trigger: triggerSundays, skipcigame: true, - // let's save some CPU cycles here, 20 is not an LTS and JDK 21 is out + [ name: 'POI-XMLBeans-DSL-1.23', jdk: '1.23', trigger: triggerSundays, skipcigame: true, disabled: true ], - [ name: 'POI-XMLBeans-DSL-1.21', jdk: '1.21', trigger: 'H */12 * * *', skipcigame: true, - ], - [ name: 'POI-XMLBeans-DSL-1.22', jdk: '1.22', trigger: triggerSundays, skipcigame: true, + [ name: 'POI-XMLBeans-DSL-1.24', jdk: '1.24', trigger: triggerSundays, skipcigame: true, ], - [ name: 'POI-XMLBeans-DSL-1.23', jdk: '1.23', trigger: triggerSundays, skipcigame: true, + [ name: 'POI-XMLBeans-DSL-1.25', jdk: '1.25', trigger: triggerSundays, skipcigame: true, ], [ name: 'POI-XMLBeans-DSL-Sonar', jdk: '1.17', trigger: triggerSundays, skipcigame: true, sonar: true ] ] -def svnBase = 'https://svn.apache.org/repos/asf/poi/trunk' -def xmlbeansSvnBase = 'https://svn.apache.org/repos/asf/xmlbeans/trunk' +def gitBase = 'https://github.com/apache/poi.git' +def xmlbeansGitBase = 'https://github.com/apache/xmlbeans.git' def defaultJdk = '1.8' def defaultTrigger = 'H/15 * * * *' // check SCM every 60/15 = 4 minutes @@ -144,13 +136,10 @@ def jdkMapping = [ '1.8': [ jenkinsJdk: 'jdk_1.8_latest', jdkVersion: 8, jdkVendor: '' ], '1.11': [ jenkinsJdk: 'jdk_11_latest', jdkVersion: 11, jdkVendor: '' ], '1.17': [ jenkinsJdk: 'jdk_17_latest', jdkVersion: 17, jdkVendor: '' ], - '1.18': [ jenkinsJdk: 'jdk_18_latest', jdkVersion: 18, jdkVendor: '' ], - '1.19': [ jenkinsJdk: 'jdk_19_latest', jdkVersion: 19, jdkVendor: '' ], - '1.20': [ jenkinsJdk: 'jdk_20_latest', jdkVersion: 20, jdkVendor: '' ], '1.21': [ jenkinsJdk: 'jdk_21_latest', jdkVersion: 21, jdkVendor: '' ], - '1.22': [ jenkinsJdk: 'jdk_22_latest', jdkVersion: 22, jdkVendor: '' ], '1.23': [ jenkinsJdk: 'jdk_23_latest', jdkVersion: 23, jdkVendor: '' ], '1.24': [ jenkinsJdk: 'jdk_24_latest', jdkVersion: 24, jdkVendor: '' ], + '1.25': [ jenkinsJdk: 'jdk_25_latest', jdkVersion: 25, jdkVendor: '' ], 'OpenJDK 1.8': [ jenkinsJdk: 'adoptopenjdk_hotspot_8u282', jdkVersion: 8, jdkVendor: 'adoptopenjdk' ], 'IBMJDK': [ jenkinsJdk: 'ibmjdk_1.8.0_261', jdkVersion: 8, jdkVendor: 'ibm' ] ] @@ -170,7 +159,7 @@ Apache POI - the Java API for Microsoft Documents </p> <p> <b>This is an automatically generated Job Config, do not edit it here! -Instead change the Jenkins Job DSL at <a href="https://svn.apache.org/repos/asf/poi/trunk/jenkins">https://svn.apache.org/repos/asf/poi/trunk/jenkins</a>, +Instead change the Jenkins Job DSL at <a href="https://github.com/apache/poi/blob/trunk/jenkins/">https://github.com/apache/poi/blob/trunk/jenkins/</a>, see <a href="https://github.com/jenkinsci/job-dsl-plugin/wiki">https://github.com/jenkinsci/job-dsl-plugin/wiki</a> for more details about the DSL.</b> </p>''' @@ -200,10 +189,9 @@ def shellCmdsUnix = rm -rf examples excelant integrationtest main ooxml ooxml-schema scratchpad build.javacheck.xml # show which files are currently modified in the working copy -svn status || true +git status || true # make sure no changed module-class-files or ooxml-lite-report-files are lingering on -svn revert poi*/src/*/java9/module-info.* || true -svn revert src/resources/ooxml-lite-report.* || true +git reset --hard || true # print out information about which exact version of java we are using echo Java-Home: $JAVA_HOME @@ -236,11 +224,9 @@ exit 0''' def shellCmdsWin = '''@echo off :: show which files are currently modified in the working copy -svn status +git status :: make sure no changed module-class-files are lingering on -svn revert poi*\\src\\*\\java9\\module-info.* -:: also revert some files directly as the wildcard-based revert seems to fail sometimes -svn revert poi\\src\\main\\java9\\module-info.class poi\\src\\test\\java9\\module-info.class poi-examples\\src\\main\\java9\\module-info.class poi-excelant\\src\\main\\java9\\module-info.class poi-excelant\\src\\test\\java9\\module-info.class poi-integration\\src\\test\\java9\\module-info.class poi-ooxml\\src\\main\\java9\\module-info.class poi-ooxml\\src\\test\\java9\\module-info.class poi-ooxml-full\\src\\main\\java9\\module-info.class poi-ooxml-lite\\src\\main\\java9\\module-info.class poi-ooxml-lite\\src\\main\\java9\\module-info.java poi-ooxml-lite-agent\\src\\main\\java9\\module-info.class poi-scratchpad\\src\\main\\java9\\module-info.class poi-scratchpad\\src\\test\\java9\\module-info.class src\\resources\\ooxml-lite-report.clazz src\\resources\\ooxml-lite-report.xsb +git reset --hard :: print out information about which exact version of java we are using echo Java-Home: %JAVA_HOME% @@ -302,9 +288,11 @@ poijobs.each { poijob -> } jdk(jdkMapping.get(jdkKey).jenkinsJdk) scm { - svn(svnBase) { svnNode -> - svnNode / browser(class: 'hudson.scm.browsers.ViewSVN') / - url << 'https://svn.apache.org/viewcvs.cgi/?root=Apache-SVN' + git { + remote { + url(gitBase) + } + branch('*/trunk') } } checkoutRetryCount(3) @@ -493,8 +481,8 @@ xmlbeansjobs.each { xjob -> label(slaves) environmentVariables { env('LANG', 'en_US.UTF-8') - if (jdkKey == '1.11' || jdkKey == '1.17' - || jdkKey == '1.18' || jdkKey == '1.19' || jdkKey == '1.20' || jdkKey == '1.21') { + if (jdkKey == '1.11' || jdkKey == '1.17' || jdkKey == '1.21' + || jdkKey == '1.23' || jdkKey == '1.24' || jdkKey == '1.25') { env('ANT_OPTS', '--add-opens=java.xml/com.sun.org.apache.xerces.internal.util=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED') } // will be needed for forbidden-apis-check: env('ANT_HOME', xjob.windows ? 'f:\\jenkins\\tools\\ant\\latest' : '/usr/share/ant') @@ -517,9 +505,11 @@ xmlbeansjobs.each { xjob -> } jdk(jdkMapping.get(jdkKey).jenkinsJdk) scm { - svn(xmlbeansSvnBase) { svnNode -> - svnNode / browser(class: 'hudson.scm.browsers.ViewSVN') / - url << 'https://svn.apache.org/viewcvs.cgi/?root=Apache-SVN' + git { + remote { + url(xmlbeansGitBase) + } + branch('*/trunk') } } checkoutRetryCount(3) @@ -616,9 +606,10 @@ Unfortunately we often see builds break because of changes/new machines...''') 'jdk_11_latest', 'jdk_17_latest', 'jdk_21_latest', - 'jdk_22_latest', 'jdk_23_latest', 'jdk_24_latest', + 'jdk_25_latest', + 'jdk_26_latest', 'adoptopenjdk_hotspot_8u282', 'ibmjdk_1.8.0_261' ) @@ -634,7 +625,7 @@ Unfortunately we often see builds break because of changes/new machines...''') runner('DontRun') steps { shell( - '''which svn || true + '''which git || true which javac javac -version echo '<?xml version="1.0"?><project name="POI Build" default="test"><target name="test"><echo>Using Ant: ${ant.version} from ${ant.home}</echo></target></project>' > build.xml @@ -676,64 +667,3 @@ echo ^<?xml version=^"1.0^"?^>^<project name=^"POI Build^" default=^"test^"^>^<t } } } - -/* I tried to put the view into a sub-folder/sub-view, but failed, there are multiple related - plugins so this is all a bit confusing :(, see also https://issues.apache.org/jira/browse/INFRA-14002 -dashboardView("P/POI-new") { - columns { - status() - weather() - configureProject() - buildButton() - cronTrigger() - lastBuildConsole() - name() - lastSuccess() - lastFailure() - lastDuration() - //lastSuccessDescription() - jacoco() - } - description("<table>\n" + - " <tr>\n" + - " <td><img src=\"https://poi.apache.org/images/project-header.png\" /></td>\n" + - " <td> \n" + - " <p>Apache POI - the Java API for Microsoft Documents</p>\n" + - " <p><b>Most of the POI Jobs are automatically generated by Jenkins Job DSL\n" + - " at <a href=\"https://svn.apache.org/repos/asf/poi/trunk/jenkins\">https://svn.apache.org/repos/asf/poi/trunk/jenkins</a>,<br/>\n" + - " see <a href=\"https://github.com/jenkinsci/job-dsl-plugin/wiki\">https://github.com/jenkinsci/job-dsl-plugin/wiki</a>\n" + - " for more details about the DSL.</b>\n" + - " </p>\n" + - " <p>\n" + - " <b><a href=\"job/POI-DSL-1.8/lastSuccessfulBuild/findbugsResult/\" target=\"_blank\">Findbugs report of latest build</a></b> -\n" + - " <b><a href=\"https://sonarcloud.io/dashboard?id=poi-parent\" target=\"_blank\">Sonar reports</a></b> -\n" + - " <b><a href=\"job/POI-DSL-1.8/lastSuccessfulBuild/artifact/build/coverage/index.html\" target=\"_blank\">Coverage of latest build</a></b>\n" + - " </p>\n" + - " </td>\n" + - " </tr>\n" + - "</table>") - filterBuildQueue(false) - filterExecutors(false) - - // Job selection - jobs {*/ -//regex(/.*POI.*/) -/*} - -// Layout -topPortlets { - jenkinsJobsList { - displayName('POI jobs') - } -} -leftPortlets { - testStatisticsChart() -} -rightPortlets { - testTrendChart() -} -bottomPortlets { - testStatisticsGrid() - buildStatistics() -} -}*/ diff --git a/lib.stored/adapter-base-1.12.0.jar b/lib.stored/adapter-base-1.12.0.jar Binary files differdeleted file mode 100644 index ebc65db594..0000000000 --- a/lib.stored/adapter-base-1.12.0.jar +++ /dev/null diff --git a/lib.stored/adapter-javahl-1.12.0.jar b/lib.stored/adapter-javahl-1.12.0.jar Binary files differdeleted file mode 100644 index bf37575d8e..0000000000 --- a/lib.stored/adapter-javahl-1.12.0.jar +++ /dev/null diff --git a/lib.stored/adapter-svnkit-1.12.0.jar b/lib.stored/adapter-svnkit-1.12.0.jar Binary files differdeleted file mode 100644 index bd80a88ce9..0000000000 --- a/lib.stored/adapter-svnkit-1.12.0.jar +++ /dev/null diff --git a/lib.stored/svnant-1.3.1.jar b/lib.stored/svnant-1.3.1.jar Binary files differdeleted file mode 100644 index 5d7e44ecba..0000000000 --- a/lib.stored/svnant-1.3.1.jar +++ /dev/null diff --git a/osgi/README.md b/osgi/README.md index bd66279760..d6042126b6 100644 --- a/osgi/README.md +++ b/osgi/README.md @@ -25,11 +25,11 @@ Available in Maven Central: https://mvnrepository.com/artifact/net.sf.saxon/Saxo 3. Apache XML Security for Java, Bouncy Castle and XML Commons Resolver These are required to sign or validate signed Office documents. The OSGi bundles are available in Maven Central: - - Apache XML Security for Java: https://mvnrepository.com/artifact/org.apache.santuario/xmlsec/3.0.4 + - Apache XML Security for Java: https://mvnrepository.com/artifact/org.apache.santuario/xmlsec/3.0.6 - XML Commons Resolver: https://mvnrepository.com/artifact/xml-resolver/xml-resolver/1.2-osgi - - Bouncy Castle: https://mvnrepository.com/artifact/org.bouncycastle/bcprov-ext-jdk18on/1.77, https://mvnrepository.com/artifact/org.bouncycastle/bcpkix-jdk18on/1.77 + - Bouncy Castle: https://mvnrepository.com/artifact/org.bouncycastle/bcprov-ext-jdk18on/1.81, https://mvnrepository.com/artifact/org.bouncycastle/bcpkix-jdk18on/1.81 4. PDFBox and PDFBox Graphics2D Required to render to PDF documents. The required jars can be downloaded from: diff --git a/osgi/pom.xml b/osgi/pom.xml index c4854f4c12..ec71465a4f 100644 --- a/osgi/pom.xml +++ b/osgi/pom.xml @@ -24,12 +24,12 @@ <groupId>org.apache.poi</groupId> <artifactId>poi-bundle</artifactId> <packaging>bundle</packaging> - <version>5.4.1-SNAPSHOT</version> + <version>5.5.0-SNAPSHOT</version> <name>Apache POI OSGi bundle</name> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> - <poi.version>5.4.1-SNAPSHOT</poi.version> + <poi.version>5.5.0-SNAPSHOT</poi.version> <pax.exam.version>4.14.0</pax.exam.version> </properties> diff --git a/poi-examples/build.gradle b/poi-examples/build.gradle index ed6ae97c92..e965b9faa1 100644 --- a/poi-examples/build.gradle +++ b/poi-examples/build.gradle @@ -49,7 +49,7 @@ final String MODULE_NAME = 'org.apache.poi.examples' final Pattern MODULE_REGEX = ~'\\.jar$' final List MODULE_COMPILE_PATH = sourceSets.main.compileClasspath.findAll{ it.path =~ MODULE_REGEX }.collect{ it.parent }.unique() -task compileJava9(type: JavaCompile) { +tasks.register('compileJava9', JavaCompile) { dependsOn 'compileJava', ':poi-ooxml:jar', ':poi-scratchpad:jar' javaCompiler = javaToolchains.compilerFor { @@ -61,8 +61,8 @@ task compileJava9(type: JavaCompile) { source = file(JAVA9_SRC) classpath = files() options.compilerArgs = [ - '--patch-module', "${MODULE_NAME}=${sourceSets.main.output.classesDirs.asPath}", - '--module-path', files(MODULE_COMPILE_PATH).asPath + '--patch-module', "${MODULE_NAME}=${sourceSets.main.output.classesDirs.asPath}", + '--module-path', files(MODULE_COMPILE_PATH).asPath ] } diff --git a/poi-examples/src/main/groovy/build.gradle b/poi-examples/src/main/groovy/build.gradle index 784d5c1378..496ab8cf8f 100644 --- a/poi-examples/src/main/groovy/build.gradle +++ b/poi-examples/src/main/groovy/build.gradle @@ -34,10 +34,10 @@ sourceSets { } // Run out read demo by default -tasks.withType(JavaExec) { - classpath = sourceSets.main.runtimeClasspath +tasks.withType(JavaExec).configureEach { + classpath = sourceSets.main.runtimeClasspath } -task runScript(type: JavaExec) { +tasks.register('runScript', JavaExec) { mainClass = "SpreadSheetDemo" args = ["../../../../test-data/spreadsheet/Simple.xls"] } diff --git a/poi-examples/src/main/java/org/apache/poi/examples/hwpf/Word2Forrest.java b/poi-examples/src/main/java/org/apache/poi/examples/hwpf/Word2Forrest.java index 937da16a33..6547d2e8cc 100644 --- a/poi-examples/src/main/java/org/apache/poi/examples/hwpf/Word2Forrest.java +++ b/poi-examples/src/main/java/org/apache/poi/examples/hwpf/Word2Forrest.java @@ -59,7 +59,7 @@ public final class Word2Forrest { Paragraph p = r.getParagraph (x); String text = p.text (); - if (text.trim ().length () == 0) + if (text.trim().isEmpty()) { continue; } diff --git a/poi-examples/src/main/java/org/apache/poi/examples/ss/ConditionalFormats.java b/poi-examples/src/main/java/org/apache/poi/examples/ss/ConditionalFormats.java index a0a8177e87..5e4d96f0c5 100644 --- a/poi-examples/src/main/java/org/apache/poi/examples/ss/ConditionalFormats.java +++ b/poi-examples/src/main/java/org/apache/poi/examples/ss/ConditionalFormats.java @@ -203,7 +203,7 @@ public final class ConditionalFormats { if (rn%10 == 0) { str = str + "x10 "; } - if (str.length() == 0) { + if (str.isEmpty()) { str = "nothing special..."; } r.createCell(1).setCellValue("It is " + str); diff --git a/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/DeferredGeneration.java b/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/DeferredGeneration.java index 1b98bb26ab..de66e11554 100644 --- a/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/DeferredGeneration.java +++ b/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/DeferredGeneration.java @@ -53,12 +53,13 @@ public class DeferredGeneration { try (FileOutputStream fileOut = new FileOutputStream("DeferredGeneration.xlsx")) { wb.write(fileOut); - //writeAvoidingTempFiles was added as an experimental change in POI 5.1.0 - //wb.writeAvoidingTempFiles(fileOut); - } finally { - //the dispose call is necessary to ensure temp files are removed - wb.dispose(); + // writeAvoidingTempFiles was added as an experimental change in POI 5.1.0 + // wb.writeAvoidingTempFiles(fileOut); } + // finally { + // the dispose call is no longer necessary to ensure temp files are removed + // wb.dispose(); + // } System.out.println("wrote DeferredGeneration.xlsx"); } } diff --git a/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/Outlining.java b/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/Outlining.java index 31b15dcb16..9258790da3 100644 --- a/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/Outlining.java +++ b/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/Outlining.java @@ -46,10 +46,11 @@ public class Outlining { try (FileOutputStream fileOut = new FileOutputStream("outlining_collapsed.xlsx")) { wb2.write(fileOut); - } finally { - //the dispose call is necessary to ensure temp files are removed - wb2.dispose(); } + // finally { + // the dispose call is no longer necessary to ensure temp files are removed + // wb2.dispose(); + // } } } } diff --git a/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/SavePasswordProtectedXlsx.java b/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/SavePasswordProtectedXlsx.java index aabfd5955c..769764aab1 100644 --- a/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/SavePasswordProtectedXlsx.java +++ b/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/SavePasswordProtectedXlsx.java @@ -58,8 +58,7 @@ public final class SavePasswordProtectedXlsx { TempFileUtils.checkTempFiles(); String filename = args[0]; String password = args[1]; - SXSSFWorkbookWithCustomZipEntrySource wb = new SXSSFWorkbookWithCustomZipEntrySource(); - try { + try (SXSSFWorkbookWithCustomZipEntrySource wb = new SXSSFWorkbookWithCustomZipEntrySource()) { for(int i = 0; i < 10; i++) { SXSSFSheet sheet = wb.createSheet("Sheet" + i); for(int r = 0; r < 1000; r++) { @@ -78,10 +77,6 @@ public final class SavePasswordProtectedXlsx { } finally { tempData.dispose(); } - } finally { - wb.close(); - //the dispose call is necessary to ensure temp files are removed - wb.dispose(); } TempFileUtils.checkTempFiles(); } diff --git a/poi-examples/src/main/java/org/apache/poi/examples/xwpf/usermodel/SimpleImages.java b/poi-examples/src/main/java/org/apache/poi/examples/xwpf/usermodel/SimpleImages.java index 1f996cfd1f..0e4c5670c0 100644 --- a/poi-examples/src/main/java/org/apache/poi/examples/xwpf/usermodel/SimpleImages.java +++ b/poi-examples/src/main/java/org/apache/poi/examples/xwpf/usermodel/SimpleImages.java @@ -22,10 +22,10 @@ import java.io.FileInputStream; import java.io.FileOutputStream; import java.io.IOException; +import org.apache.poi.common.usermodel.PictureType; import org.apache.poi.openxml4j.exceptions.InvalidFormatException; import org.apache.poi.util.Units; import org.apache.poi.xwpf.usermodel.BreakType; -import org.apache.poi.xwpf.usermodel.Document; import org.apache.poi.xwpf.usermodel.XWPFDocument; import org.apache.poi.xwpf.usermodel.XWPFParagraph; import org.apache.poi.xwpf.usermodel.XWPFRun; @@ -45,30 +45,30 @@ public final class SimpleImages { XWPFRun r = p.createRun(); for (String imgFile : args) { - int format; + PictureType format; if (imgFile.endsWith(".emf")) { - format = Document.PICTURE_TYPE_EMF; + format = PictureType.EMF; } else if (imgFile.endsWith(".wmf")) { - format = Document.PICTURE_TYPE_WMF; + format = PictureType.WMF; } else if (imgFile.endsWith(".pict")) { - format = Document.PICTURE_TYPE_PICT; + format = PictureType.PICT; } else if (imgFile.endsWith(".jpeg") || imgFile.endsWith(".jpg")) { - format = Document.PICTURE_TYPE_JPEG; + format = PictureType.JPEG; } else if (imgFile.endsWith(".png")) { - format = Document.PICTURE_TYPE_PNG; + format = PictureType.PNG; } else if (imgFile.endsWith(".dib")) { - format = Document.PICTURE_TYPE_DIB; + format = PictureType.DIB; } else if (imgFile.endsWith(".gif")) { - format = Document.PICTURE_TYPE_GIF; + format = PictureType.GIF; } else if (imgFile.endsWith(".tiff")) { - format = Document.PICTURE_TYPE_TIFF; + format = PictureType.TIFF; } else if (imgFile.endsWith(".eps")) { - format = Document.PICTURE_TYPE_EPS; + format = PictureType.EPS; } else if (imgFile.endsWith(".bmp")) { - format = Document.PICTURE_TYPE_BMP; + format = PictureType.BMP; } else if (imgFile.endsWith(".wpg")) { - format = Document.PICTURE_TYPE_WPG; + format = PictureType.WPG; } else { System.err.println("Unsupported picture: " + imgFile + ". Expected emf|wmf|pict|jpeg|png|dib|gif|tiff|eps|bmp|wpg"); diff --git a/poi-examples/src/main/java/org/apache/poi/examples/xwpf/usermodel/UpdateEmbeddedDoc.java b/poi-examples/src/main/java/org/apache/poi/examples/xwpf/usermodel/UpdateEmbeddedDoc.java index faf31b3ded..96a24f591d 100644 --- a/poi-examples/src/main/java/org/apache/poi/examples/xwpf/usermodel/UpdateEmbeddedDoc.java +++ b/poi-examples/src/main/java/org/apache/poi/examples/xwpf/usermodel/UpdateEmbeddedDoc.java @@ -44,7 +44,7 @@ import org.apache.poi.xwpf.usermodel.XWPFDocument; * SpreadsheetML workbook embedded into the document.<p> * * This code was successfully tested with the following file from the POI test collection: - * http://svn.apache.org/repos/asf/poi/trunk/test-data/document/EmbeddedDocument.docx + * test-data/document/EmbeddedDocument.docx */ @SuppressWarnings({"java:S106","java:S4823","java:S1192"}) public class UpdateEmbeddedDoc { diff --git a/poi-excelant/build.gradle b/poi-excelant/build.gradle index 8a458e9aa7..a82cc6d4cf 100644 --- a/poi-excelant/build.gradle +++ b/poi-excelant/build.gradle @@ -41,9 +41,9 @@ dependencies { testImplementation(project(path: ':poi-ooxml', configuration: 'tests')) { exclude group: 'org.apache.poi', module: 'poi-scratchpad' } - testImplementation 'com.google.guava:guava:33.3.0-jre' + testImplementation 'com.google.guava:guava:33.4.8-jre' testImplementation "org.apache.logging.log4j:log4j-slf4j2-impl:${log4jVersion}" - testImplementation 'org.slf4j:slf4j-simple:2.0.16' + testImplementation 'org.slf4j:slf4j-simple:2.0.17' testRuntimeOnly "org.apiguardian:apiguardian-api:${apiGuardianVersion}" } @@ -57,7 +57,7 @@ final String OOXML_LITE_AGENT = "../build/dist/maven/poi-ooxml-lite-agent/poi-oo final String OOXML_LITE_REPORT = '../src/resources/ooxml-lite-report' final String OOXML_LITE_INCLUDES = "^(com/microsoft/schemas|org/(etsi|openxmlformats|w3/)|org/apache/poi/schemas)" -task compileJava9(type: JavaCompile) { +tasks.register('compileJava9', JavaCompile) { dependsOn 'compileJava', ':poi-ooxml:jar', ':poi-scratchpad:jar' javaCompiler = javaToolchains.compilerFor { @@ -69,12 +69,12 @@ task compileJava9(type: JavaCompile) { source = file(JAVA9_SRC) classpath = files() options.compilerArgs = [ - '--patch-module', "${MODULE_NAME}=${sourceSets.main.output.classesDirs.asPath}", - '--module-path', files(MAIN_MODULE_PATH).asPath + '--patch-module', "${MODULE_NAME}=${sourceSets.main.output.classesDirs.asPath}", + '--module-path', files(MAIN_MODULE_PATH).asPath ] } -task compileTest9(type: JavaCompile) { +tasks.register('compileTest9', JavaCompile) { dependsOn 'compileTestJava', ':poi-ooxml:jar', ':poi-scratchpad:jar' javaCompiler = javaToolchains.compilerFor { @@ -85,8 +85,8 @@ task compileTest9(type: JavaCompile) { destinationDirectory = file(TEST9_OUT + VERSIONS9) source = file(TEST9_SRC) options.compilerArgs = [ - '--patch-module', "${MODULE_NAME}=${(sourceSets.main.output.classesDirs + sourceSets.test.output.classesDirs).asPath}", - '--module-path', files(TEST_MODULE_PATH).asPath + '--patch-module', "${MODULE_NAME}=${(sourceSets.main.output.classesDirs + sourceSets.test.output.classesDirs).asPath}", + '--module-path', files(TEST_MODULE_PATH).asPath ] classpath = files() } @@ -123,7 +123,7 @@ task testJar(type: Jar, dependsOn: [ testClasses, compileTest9 ] ) { setArchiveClassifier 'tests' // ignore second module-info.class from main - duplicatesStrategy = 'exclude' + duplicatesStrategy = DuplicatesStrategy.EXCLUDE from sourceSets.test.output + sourceSets.main.output diff --git a/poi-integration/build.gradle b/poi-integration/build.gradle index 0660c6996a..7e4ac20b12 100644 --- a/poi-integration/build.gradle +++ b/poi-integration/build.gradle @@ -1,5 +1,3 @@ -import java.util.regex.Pattern - /* ==================================================================== Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with @@ -17,8 +15,10 @@ import java.util.regex.Pattern limitations under the License. ==================================================================== */ +import java.util.regex.Pattern + final String TEST9_SRC = 'src/test/java9' -final String TEST9_OUT = "${buildDir}/classes/java9/test/" +final String TEST9_OUT = layout.buildDirectory.dir('classes/java9/test/').get().asFile.absolutePath final String VERSIONS9 = 'META-INF/versions/9' final boolean IBMVM = System.getProperty("java.vendor").contains("IBM") @@ -40,8 +40,8 @@ sourceSets { dependencies { testImplementation 'org.apache.ant:ant:1.10.15' - testImplementation 'org.apache.commons:commons-collections4:4.4' - testImplementation 'com.google.guava:guava:33.3.0-jre' + testImplementation 'org.apache.commons:commons-collections4:4.5.0' + testImplementation 'com.google.guava:guava:33.4.8-jre' misc(project(':poi-ooxml')) { capabilities { @@ -76,7 +76,7 @@ dependencies { } testImplementation project(path: ':poi-ooxml-lite-agent', configuration: 'archives') testImplementation "org.apache.logging.log4j:log4j-slf4j2-impl:${log4jVersion}" - testImplementation 'org.slf4j:slf4j-simple:2.0.16' + testImplementation 'org.slf4j:slf4j-simple:2.0.17' testRuntimeOnly "org.apiguardian:apiguardian-api:${apiGuardianVersion}" } @@ -90,7 +90,7 @@ final String OOXML_LITE_AGENT = "../build/dist/maven/poi-ooxml-lite-agent/poi-oo final String OOXML_LITE_REPORT = '../src/resources/ooxml-lite-report' final String OOXML_LITE_INCLUDES = "^(com/microsoft/schemas|org/(etsi|openxmlformats|w3/)|org/apache/poi/schemas)" -task compileTest9(type: JavaCompile) { +tasks.register('compileTest9', JavaCompile) { dependsOn 'compileTestJava', ':poi-ooxml:testJar', ':poi-scratchpad:testJar', ':poi-examples:jar' javaCompiler = javaToolchains.compilerFor { @@ -101,8 +101,8 @@ task compileTest9(type: JavaCompile) { destinationDirectory = file(TEST9_OUT + VERSIONS9) source = file(TEST9_SRC) options.compilerArgs = [ - '--patch-module', "${MODULE_NAME}=${(sourceSets.main.output.classesDirs + sourceSets.test.output.classesDirs).asPath}", - '--module-path', files(MODULE_COMPILE_PATH).asPath + '--patch-module', "${MODULE_NAME}=${(sourceSets.main.output.classesDirs + sourceSets.test.output.classesDirs).asPath}", + '--module-path', files(MODULE_COMPILE_PATH).asPath ] classpath = files() } @@ -123,7 +123,7 @@ task testJar(type: Jar, dependsOn: [ testClasses, compileTest9 ] ) { setArchiveClassifier 'tests' // ignore second module-info.class from main - duplicatesStrategy = 'exclude' + duplicatesStrategy = DuplicatesStrategy.EXCLUDE from sourceSets.test.output + sourceSets.main.output diff --git a/poi-integration/src/test/java/org/apache/poi/stress/TestAllFiles.java b/poi-integration/src/test/java/org/apache/poi/stress/TestAllFiles.java index 8b3baf2b01..8988c8a180 100644 --- a/poi-integration/src/test/java/org/apache/poi/stress/TestAllFiles.java +++ b/poi-integration/src/test/java/org/apache/poi/stress/TestAllFiles.java @@ -97,6 +97,12 @@ public class TestAllFiles { "poifs/60320-protected.xlsx", "poifs/protected_sha512.xlsx", + // stress docs + "document/deep-table-cell.docx", + + // invalid files + "spreadsheet/bug69769.xlsx", + // NOTE: Expected failures should usually be added in file "stress.xls" instead // of being listed here in order to also verify the expected exception details! }; @@ -136,7 +142,9 @@ public class TestAllFiles { "spreadsheet/clusterfuzz-testcase-minimized-POIHSSFFuzzer-4977868385681408.xls", "spreadsheet/clusterfuzz-testcase-minimized-POIHSSFFuzzer-4651309315719168.xls", "document/clusterfuzz-testcase-POIHWPFFuzzer-5696094627495936.doc", - "spreadsheet/clusterfuzz-testcase-minimized-POIHSSFFuzzer-4657005060816896.xls" + "spreadsheet/clusterfuzz-testcase-minimized-POIHSSFFuzzer-4657005060816896.xls", + "diagram/clusterfuzz-testcase-minimized-POIHDGFFuzzer-4913778037489664.vsd", + "diagram/clusterfuzz-testcase-minimized-POIHDGFFuzzer-6478389109981184.vsd" }); private static final Set<String> EXPECTED_FAILURES = StressTestUtils.unmodifiableHashSet( diff --git a/poi-ooxml-full/build.gradle b/poi-ooxml-full/build.gradle index 502dc0c8fe..4495a6c8b4 100644 --- a/poi-ooxml-full/build.gradle +++ b/poi-ooxml-full/build.gradle @@ -1,5 +1,3 @@ -import java.util.regex.Pattern - /* ==================================================================== Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with @@ -17,9 +15,11 @@ import java.util.regex.Pattern limitations under the License. ==================================================================== */ +import java.util.regex.Pattern + final String MODULE_NAME = 'org.apache.poi.ooxml.schemas' -final String BEANS_SRC = "${buildDir}/generated-sources" -final String BEANS_RES = "${buildDir}/generated-resources" +final String BEANS_SRC = layout.buildDirectory.dir('generated-sources').get().asFile.absolutePath +final String BEANS_RES = layout.buildDirectory.dir('generated-resources').get().asFile.absolutePath sourceSets { main { @@ -54,7 +54,7 @@ compileJava { options.forkOptions.jvmArgs += '-Xmx2G' } -task compileJava9(type: JavaCompile) { +tasks.register('compileJava9', JavaCompile) { dependsOn 'compileJava' javaCompiler = javaToolchains.compilerFor { @@ -66,24 +66,24 @@ task compileJava9(type: JavaCompile) { source = file(JAVA9_SRC) classpath = files() options.compilerArgs = [ - '--patch-module', "${MODULE_NAME}=${sourceSets.main.output.asPath}", - '--module-path', files(MAIN_MODULE_PATH).asPath + '--patch-module', "${MODULE_NAME}=${sourceSets.main.output.asPath}", + '--module-path', files(MAIN_MODULE_PATH).asPath ] } -task copy_xsds(type: Copy) { - from ('src/main/xmlschema/org/apache/poi/xdgf') - from ('src/main/xmlschema/org/apache/poi/schemas') { +tasks.register('copy_xsds', Copy) { + from('src/main/xmlschema/org/apache/poi/xdgf') + from('src/main/xmlschema/org/apache/poi/schemas') { include 'XAdES*.xsd', '*.xsdconfig', 'xmldsig*.xsd', 'ooxmlSchemas.xsdconfig', 'markup-compatibility.xsd', 'vmlDrawing.xsd', 'word10.xsd', 'word12.xsd', 'xlThreaded*.xsd', 'dml-drawing.xsd', 'drawing-chart2012.xsd', 'chartEx.xsd' exclude '*.zip' } - from ('src/main/xmlschema/org/apache/poi/poifs/crypt') { + from('src/main/xmlschema/org/apache/poi/poifs/crypt') { include 'signatureInfo.xsd' } - from (zipTree('src/main/xmlschema/org/apache/poi/schemas/OfficeOpenXML-XMLSchema-Transitional.zip')) - from (zipTree('src/main/xmlschema/org/apache/poi/schemas/OpenPackagingConventions-XMLSchema.zip')) { + from(zipTree('src/main/xmlschema/org/apache/poi/schemas/OfficeOpenXML-XMLSchema-Transitional.zip')) + from(zipTree('src/main/xmlschema/org/apache/poi/schemas/OpenPackagingConventions-XMLSchema.zip')) { include 'opc-digSig.xsd', 'opc-relationships.xsd' } into 'build/xsds' @@ -95,30 +95,30 @@ task generate_beans(dependsOn: copy_xsds) { doLast { ant.uptodate( - property: 'xmlbeans_uptodate', - targetfile: 'build/generated-resources/org/apache/poi/schemas/ooxml/system/ooxml/TypeSystemHolder.class' + property: 'xmlbeans_uptodate', + targetfile: 'build/generated-resources/org/apache/poi/schemas/ooxml/system/ooxml/TypeSystemHolder.class' ) { srcFiles(dir: 'build/xsds', includes: '*.xsd') } ant.taskdef( - name: 'xmlbean', - classname: 'org.apache.xmlbeans.impl.tool.XMLBean', - classpath: sourceSets.main.runtimeClasspath.asPath + name: 'xmlbean', + classname: 'org.apache.xmlbeans.impl.tool.XMLBean', + classpath: sourceSets.main.runtimeClasspath.asPath ) if (!ant.properties.xmlbeans_uptodate) { ant.xmlbean( - schema: 'build/xsds', - srcgendir: BEANS_SRC, - classgendir: BEANS_RES, - destfile: 'build/xsds.jar', - srconly: true, - failonerror: true, - fork: true, - memoryMaximumSize: '1536m', - typesystemname: 'ooxml', - repackage: 'org.apache.xmlbeans.metadata:org.apache.poi.schemas.ooxml' + schema: 'build/xsds', + srcgendir: BEANS_SRC, + classgendir: BEANS_RES, + destfile: 'build/xsds.jar', + srconly: true, + failonerror: true, + fork: true, + memoryMaximumSize: '1536m', + typesystemname: 'ooxml', + repackage: 'org.apache.xmlbeans.metadata:org.apache.poi.schemas.ooxml' ) { classpath = sourceSets.main.runtimeClasspath.asPath } @@ -126,7 +126,7 @@ task generate_beans(dependsOn: copy_xsds) { } } -task sourceJar(type: Jar) { +tasks.register('sourceJar', Jar) { setArchiveClassifier 'sources' from sourceSets.main.allJava } diff --git a/poi-ooxml-lite-agent/build.gradle b/poi-ooxml-lite-agent/build.gradle index 3890429320..fef003b327 100644 --- a/poi-ooxml-lite-agent/build.gradle +++ b/poi-ooxml-lite-agent/build.gradle @@ -22,8 +22,8 @@ sourceSets { } dependencies { - api 'net.bytebuddy:byte-buddy:1.16.1' - api 'net.bytebuddy:byte-buddy-agent:1.16.1' + api 'net.bytebuddy:byte-buddy:1.17.5' + api 'net.bytebuddy:byte-buddy-agent:1.17.5' api "org.apache.xmlbeans:xmlbeans:${xmlbeansVersion}" } @@ -36,7 +36,7 @@ java { } } -task compileJava9(type: JavaCompile) { +tasks.register('compileJava9', JavaCompile) { dependsOn 'compileJava' javaCompiler = javaToolchains.compilerFor { @@ -49,8 +49,8 @@ task compileJava9(type: JavaCompile) { classpath = files() doFirst { options.compilerArgs = [ - '--patch-module', "${MODULE_NAME}=${sourceSets.main.output.classesDirs.asPath}", - '--module-path', sourceSets.main.compileClasspath.asPath + '--patch-module', "${MODULE_NAME}=${sourceSets.main.output.classesDirs.asPath}", + '--module-path', sourceSets.main.compileClasspath.asPath ] } } diff --git a/poi-ooxml-lite/build.gradle b/poi-ooxml-lite/build.gradle index e9e046f2c5..655b8fc32c 100644 --- a/poi-ooxml-lite/build.gradle +++ b/poi-ooxml-lite/build.gradle @@ -1,5 +1,3 @@ -import java.util.regex.Pattern - /* ==================================================================== Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with @@ -17,8 +15,10 @@ import java.util.regex.Pattern limitations under the License. ==================================================================== */ -final String BEANS_SRC = "${buildDir}/generated-sources" -final String BEANS_RES = "${buildDir}/generated-resources" +import java.util.regex.Pattern + +final String BEANS_SRC = layout.buildDirectory.dir('generated-sources').get().asFile.absolutePath +final String BEANS_RES = layout.buildDirectory.dir('generated-resources').get().asFile.absolutePath sourceSets { main { @@ -43,7 +43,7 @@ final Pattern MODULE_REGEX = ~'\\.jar$' final List MAIN_MODULE_PATH = sourceSets.main.runtimeClasspath.findAll{ it.path =~ MODULE_REGEX }.collect{ it.parent }.unique() final String OOXML_LITE_REPORT = '../src/resources/ooxml-lite-report' -task generateModuleInfo() { +tasks.register('generateModuleInfo') { File fileIn = file("${OOXML_LITE_REPORT}.clazz") File fileOut = file("src/main/java9/module-info.java") @@ -55,8 +55,8 @@ task generateModuleInfo() { // generate module-info based on exported classes String exports = fileIn. - collect { " exports ${it.replaceAll('[/\\\\][^/\\\\]+$', '').replaceAll('[/\\\\]', '.')};" }. - findAll { !(it =~ /\.impl;$/) }.unique().sort().join('\n') + collect { " exports ${it.replaceAll('[/\\\\][^/\\\\]+$', '').replaceAll('[/\\\\]', '.')};" }. + findAll { !(it =~ /\.impl;$/) }.unique().sort().join('\n') String content = header + '\n' + exports + '\n}' if (fileOut.text != content) { @@ -65,19 +65,19 @@ task generateModuleInfo() { } } -task compileOoxmlLite(type: Copy) { +tasks.register('compileOoxmlLite', Copy) { dependsOn 'generateModuleInfo', ':poi-ooxml-full:generate_beans', ':poi-ooxml-full:compileJava' // This task is currently always executed, because gradle thinks files with two dollar signs // (as in AlternateContentDocument$AlternateContent$Choice.class) are always stale // copy re-/sources to modules own directory to pacify IntelliJ, which doesn't like the same source dir in multiple modules - from(project(':poi-ooxml-full').buildDir) { + from(project(':poi-ooxml-full').layout.buildDirectory.asFile) { include 'generated-sources/**' include 'generated-resources/**' include 'classes/java/main/**' } - into(buildDir) + into(layout.buildDirectory.asFile) } compileJava { @@ -100,8 +100,8 @@ task compileJava9(type: JavaCompile, dependsOn: 'compileJava') { classpath = files() doFirst { options.compilerArgs = [ - '--patch-module', "${MODULE_NAME}=${project(':poi-ooxml-full').sourceSets.main.output.asPath}", - '--module-path', files(MAIN_MODULE_PATH).asPath + '--patch-module', "${MODULE_NAME}=${project(':poi-ooxml-full').sourceSets.main.output.asPath}", + '--module-path', files(MAIN_MODULE_PATH).asPath ] } } @@ -124,7 +124,7 @@ jar { } // ignore second module-info.class from poi-ooxml-full - // duplicatesStrategy = 'exclude' + // duplicatesStrategy = DuplicatesStrategy.EXCLUDE includeEmptyDirs = false manifest { diff --git a/poi-ooxml/build.gradle b/poi-ooxml/build.gradle index 0ec5fda5d6..c2ef234d37 100644 --- a/poi-ooxml/build.gradle +++ b/poi-ooxml/build.gradle @@ -28,7 +28,6 @@ configurations { exclude group: 'xml-apis', module: 'xml-apis' } - broken tests javadocs } @@ -59,12 +58,18 @@ dependencies { api project(':poi-ooxml-full') api project(path: ':poi-ooxml-full', configuration: 'archives') + // Can be very useful in local testing to comment out the 2 poi-ooxml-full lines above + // and uncomment the line below to use a pre-built version of poi-ooxml-full. + // Try to use the last release version of poi-ooxml-full. You might be unlucky if + // recent unreleased changes in poi-ooxml-full are needed. + // api "org.apache.poi:poi-ooxml-full:5.4.1" + api "org.apache.xmlbeans:xmlbeans:${xmlbeansVersion}" api "org.apache.commons:commons-compress:${commonsCompressVersion}" api "commons-io:commons-io:${commonsIoVersion}" api 'com.github.virtuald:curvesapi:1.08' api "org.apache.logging.log4j:log4j-api:${log4jVersion}" - api 'org.apache.commons:commons-collections4:4.4' + api 'org.apache.commons:commons-collections4:4.5.0' signingImplementation "org.apache.santuario:xmlsec:${xmlSecVersion}" signingImplementation "org.bouncycastle:bcpkix-jdk18on:${bouncyCastleVersion}" @@ -89,6 +94,10 @@ dependencies { exclude group: 'xalan', module: 'xalan' exclude group: 'xml-apis', module: 'xml-apis' } + renderImplementation("org.apache.xmlgraphics:batik-script:${batikVersion}") { + exclude group: 'xalan', module: 'xalan' + exclude group: 'xml-apis', module: 'xml-apis' + } rendersignImplementation "org.apache.pdfbox:pdfbox:${pdfboxVersion}" rendersignImplementation "de.rototor.pdfbox:graphics2d:${graphics2dVersion}" @@ -105,7 +114,10 @@ dependencies { exclude group: 'xalan', module: 'xalan' exclude group: 'xml-apis', module: 'xml-apis' } - + rendersignImplementation("org.apache.xmlgraphics:batik-script:${batikVersion}") { + exclude group: 'xalan', module: 'xalan' + exclude group: 'xml-apis', module: 'xml-apis' + } if (!NO_SCRATCHPAD) { testImplementation project(':poi-scratchpad') @@ -114,42 +126,33 @@ dependencies { testImplementation project(path:':poi', configuration:'tests') testImplementation project(path:':poi-ooxml-lite-agent', configuration: 'archives') testRuntimeOnly "org.apiguardian:apiguardian-api:${apiGuardianVersion}" - testImplementation 'org.xmlunit:xmlunit-core:2.10.0' + testImplementation 'org.xmlunit:xmlunit-core:2.10.3' testImplementation 'org.reflections:reflections:0.10.2' testImplementation 'org.openjdk.jmh:jmh-core:1.36' testImplementation 'org.openjdk.jmh:jmh-generator-annprocess:1.36' - testImplementation 'com.google.guava:guava:33.3.0-jre' + testImplementation 'com.google.guava:guava:33.4.8-jre' testImplementation 'com.github.rzymek:opczip:1.2.0' // prevent slf4j warnings coming from xmlsec -> slf4j-api 1.7.x dependency // see https://logging.apache.org/log4j/2.x/log4j-slf4j-impl/ testImplementation "org.apache.logging.log4j:log4j-slf4j2-impl:${log4jVersion}" - testImplementation 'org.slf4j:slf4j-simple:2.0.16' - - broken("org.apache.xmlgraphics:batik-script:${batikVersion}"){ - exclude group: 'xalan', module: 'xalan' - exclude group: 'xml-apis', module: 'xml-apis' - } + testImplementation 'org.slf4j:slf4j-simple:2.0.17' javadocs project(':poi') javadocs project(':poi-scratchpad') } final String MODULE_NAME = 'org.apache.poi.ooxml' -final Pattern MODULE_NOT_REGEX = ~'(poi[/\\\\][^/\\\\]+$|batik-script)' +final Pattern MODULE_NOT_REGEX = ~'(poi[/\\\\][^/\\\\]+$)' final Pattern MODULE_REGEX = ~'\\.jar$' final List MAIN_MODULE_PATH = sourceSets.main.runtimeClasspath.findAll{ it.path =~ MODULE_REGEX }.collect{ it.parent }.unique() -final List TEST_MODULE_PATH = sourceSets.test.runtimeClasspath.findAll{ it.path =~ MODULE_REGEX && !(it.path =~ MODULE_NOT_REGEX) }.collect{ it.parent }.unique() + files("build/brokenJars") +final List TEST_MODULE_PATH = sourceSets.test.runtimeClasspath.findAll{ it.path =~ MODULE_REGEX && !(it.path =~ MODULE_NOT_REGEX) }.collect{ it.parent }.unique() final String OOXML_LITE_AGENT = "../build/dist/maven/poi-ooxml-lite-agent/poi-ooxml-lite-agent-${project.version}.jar" final String OOXML_LITE_REPORT = '../src/resources/ooxml-lite-report' final String OOXML_LITE_INCLUDES = "^(com/microsoft/schemas|org/(etsi|openxmlformats|w3/)|org/apache/poi/schemas)" -compileJava { - dependsOn 'fixBatik', 'cleanupBatik' -} - -task compileJava9(type: JavaCompile) { +tasks.register('compileJava9', JavaCompile) { dependsOn 'compileJava', ':poi:jar' javaCompiler = javaToolchains.compilerFor { @@ -161,12 +164,12 @@ task compileJava9(type: JavaCompile) { source = file(JAVA9_SRC) classpath = files() options.compilerArgs = [ - '--patch-module', "${MODULE_NAME}=${sourceSets.main.output.classesDirs.asPath}", - '--module-path', files(MAIN_MODULE_PATH).asPath + '--patch-module', "${MODULE_NAME}=${sourceSets.main.output.classesDirs.asPath}", + '--module-path', files(MAIN_MODULE_PATH).asPath ] } -task compileTest9(type: JavaCompile) { +tasks.register('compileTest9', JavaCompile) { dependsOn 'compileTestJava', ':poi:testJar' javaCompiler = javaToolchains.compilerFor { @@ -177,8 +180,8 @@ task compileTest9(type: JavaCompile) { destinationDirectory = file(TEST9_OUT + VERSIONS9) source = file(TEST9_SRC) options.compilerArgs = [ - '--patch-module', "${MODULE_NAME}=${(sourceSets.main.output.classesDirs + sourceSets.test.output.classesDirs).asPath}", - '--module-path', files(TEST_MODULE_PATH).asPath + '--patch-module', "${MODULE_NAME}=${(sourceSets.main.output.classesDirs + sourceSets.test.output.classesDirs).asPath}", + '--module-path', files(TEST_MODULE_PATH).asPath ] classpath = files() } @@ -199,7 +202,7 @@ task testJar(type: Jar, dependsOn: testClasses) { setArchiveClassifier 'tests' // ignore second module-info.class from main - duplicatesStrategy = 'exclude' + duplicatesStrategy = DuplicatesStrategy.EXCLUDE from sourceSets.test.output + sourceSets.main.output @@ -208,25 +211,6 @@ task testJar(type: Jar, dependsOn: testClasses) { } } -// based on https://github.com/moditect/moditect-gradle-plugin/issues/12 -task fixBatik(type: Zip) { - ant.mkdir(dir: "${buildDir}/brokenJars") - archiveFileName = "batik-script-${batikVersion}.jar" - destinationDirectory = file("${buildDir}/brokenJars") - from zipTree(configurations.broken.files.find{ f -> f.name.startsWith("batik-script") }) - filesMatching("**/org.apache.batik.script.InterpreterFactory") { - it.filter{ it2 -> it2.contains("Rhino") ? "#" + it2 : it2 } - } -} - -task cleanupBatik(type: Delete) { - // remove older files to avoid build failures because of duplicate modules - delete fileTree("${buildDir}/brokenJars/").matching { - include "*.jar" - exclude "batik*-${batikVersion}.jar" - } -} - javadoc { failOnError = true doFirst { diff --git a/poi-ooxml/src/main/java/org/apache/poi/ooxml/POIXMLException.java b/poi-ooxml/src/main/java/org/apache/poi/ooxml/POIXMLException.java index f949eccb90..be53202057 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/ooxml/POIXMLException.java +++ b/poi-ooxml/src/main/java/org/apache/poi/ooxml/POIXMLException.java @@ -19,7 +19,7 @@ package org.apache.poi.ooxml; /** * Indicates a generic OOXML error. */ -public final class POIXMLException extends RuntimeException{ +public final class POIXMLException extends RuntimeException { /** * Create a new {@code POIXMLException} with no * detail message. diff --git a/poi-ooxml/src/main/java/org/apache/poi/ooxml/POIXMLTypeLoader.java b/poi-ooxml/src/main/java/org/apache/poi/ooxml/POIXMLTypeLoader.java index e848e383cd..5a4ca30c49 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/ooxml/POIXMLTypeLoader.java +++ b/poi-ooxml/src/main/java/org/apache/poi/ooxml/POIXMLTypeLoader.java @@ -43,6 +43,9 @@ public class POIXMLTypeLoader { DEFAULT_XML_OPTIONS.setCharacterEncoding("UTF-8"); DEFAULT_XML_OPTIONS.setDisallowDocTypeDeclaration(true); DEFAULT_XML_OPTIONS.setEntityExpansionLimit(1); + DEFAULT_XML_OPTIONS.setLoadStripProcinsts(true); + DEFAULT_XML_OPTIONS.setLoadStripComments(true); + // JAXP is used for parsing // so only user code using XmlObject/XmlToken.Factory.parse // directly can bypass the entity check, which is probably unlikely (... and not within our responsibility :)) diff --git a/poi-ooxml/src/main/java/org/apache/poi/ooxml/util/NumberHelper.java b/poi-ooxml/src/main/java/org/apache/poi/ooxml/util/NumberHelper.java new file mode 100644 index 0000000000..dbb397c448 --- /dev/null +++ b/poi-ooxml/src/main/java/org/apache/poi/ooxml/util/NumberHelper.java @@ -0,0 +1,49 @@ +/* ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ + +package org.apache.poi.ooxml.util; + +import org.apache.poi.util.Internal; + +/** + * Helper class for number related operations. + * <p>Note: This class is for internal POI usage only.</p> + * + * @since POI 5.5.0 + */ +@Internal +public class NumberHelper { + private NumberHelper() { + // no instances of this class + } + + /** + * @param number the number to convert + * @return the double representation of the number + * @throws IllegalArgumentException if the number cannot be converted + */ + public static double toDouble(Object number) { + if (number instanceof Number) { + return ((Number) number).doubleValue(); + } else if (number instanceof String) { + return Double.parseDouble((String) number); + } + throw new IllegalArgumentException("Cannot convert of class" + number.getClass().getName() + + " to double"); + } + +} diff --git a/poi-ooxml/src/main/java/org/apache/poi/ooxml/util/XPathHelper.java b/poi-ooxml/src/main/java/org/apache/poi/ooxml/util/XPathHelper.java index 26b2b2e737..f4fcf57fe7 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/ooxml/util/XPathHelper.java +++ b/poi-ooxml/src/main/java/org/apache/poi/ooxml/util/XPathHelper.java @@ -80,8 +80,8 @@ public final class XPathHelper { * It returns the first element found - the search order is: * <ul> * <li>searching for a direct child</li> - * <li>searching for a AlternateContent.Choice child</li> - * <li>searching for a AlternateContent.Fallback child</li> + * <li>searching for an AlternateContent.Choice child</li> + * <li>searching for an AlternateContent.Fallback child</li> * </ul> * The factory flag is * a workaround to process files based on a later edition. But it comes with the drawback: diff --git a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/OPCComplianceFlags.java b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/OPCComplianceFlags.java new file mode 100644 index 0000000000..e288c8c022 --- /dev/null +++ b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/OPCComplianceFlags.java @@ -0,0 +1,118 @@ +/* ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ + +package org.apache.poi.openxml4j.opc; + +/** + * Allows disabling specific OPC compliance rules. + * By default, rules M4.2, M4.3, M4.4, and M4.5 are all enforced which will prevent + * non-compliant documents from being parsed. + * + * Consumers may disable these compliance checks individually or as a whole at their + * own discretion to allow certain non-compliant documents to be parsed. + * @since POI 5.4.1 + */ +public class OPCComplianceFlags { + + /* + * Rule M4.2: A format consumer shall consider the use of the Markup + * Compatibility namespace to be an error. + */ + protected boolean ENFORCE_M4_2_FORBID_MARKUP_COMPATIBILITY_NAMESPACE; + + /** + * Rule M4.3: Producers shall not create a document element that contains + * refinements to the Dublin Core elements, except for the two specified in + * the schema: <dcterms:created> and <dcterms:modified> Consumers shall + * consider a document element that violates this constraint to be an error. + */ + protected boolean ENFORCE_M4_3_FORBID_REFINING_DUBLIN_CORE_ELEMENTS; + + /** + * Rule M4.4: Producers shall not create a document element that contains + * the xml:lang attribute. Consumers shall consider a document element that + * violates this constraint to be an error. + */ + protected boolean ENFORCE_M4_4_FORBID_XML_LANG_ATTRIBUTE; + + /* + * Rule M4.5: Producers shall not create a document element that contains + * the xsi:type attribute, except for a <dcterms:created> or + * <dcterms:modified> element where the xsi:type attribute shall be present + * and shall hold the value dcterms:W3CDTF, where dcterms is the namespace + * prefix of the Dublin Core namespace. Consumers shall consider a document + * element that violates this constraint to be an error. + */ + protected boolean ENFORCE_M4_5_RESTRICT_XSI_TYPE_ATTRIBUTE; + + private OPCComplianceFlags( + boolean forbidMarkupCompatibilityNamespace, + boolean forbidRefiningDublinCoreElements, + boolean forbidXmlLangAttribute, + boolean restrictXsiTypeAttribute + ) { + this.ENFORCE_M4_2_FORBID_MARKUP_COMPATIBILITY_NAMESPACE = forbidMarkupCompatibilityNamespace; + this.ENFORCE_M4_3_FORBID_REFINING_DUBLIN_CORE_ELEMENTS = forbidRefiningDublinCoreElements; + this.ENFORCE_M4_4_FORBID_XML_LANG_ATTRIBUTE = forbidXmlLangAttribute; + this.ENFORCE_M4_5_RESTRICT_XSI_TYPE_ATTRIBUTE = restrictXsiTypeAttribute; + } + + public static OPCComplianceFlags enforceAll() { + return new OPCComplianceFlags(true, true, true, true); + } + + public static OPCComplianceFlags disableAll() { + return new OPCComplianceFlags(false, false, false, false); + } + + public OPCComplianceFlags setForbidMarkupCompatibilityNamespace(boolean flag) { + ENFORCE_M4_2_FORBID_MARKUP_COMPATIBILITY_NAMESPACE = flag; + return this; + } + + public OPCComplianceFlags setForbidRefiningDublinCoreElements(boolean flag) { + ENFORCE_M4_3_FORBID_REFINING_DUBLIN_CORE_ELEMENTS = flag; + return this; + } + + public OPCComplianceFlags setForbidXmlLangAttribute(boolean flag) { + ENFORCE_M4_4_FORBID_XML_LANG_ATTRIBUTE = flag; + return this; + } + + public OPCComplianceFlags setRestrictXsiTypeAttribute(boolean flag) { + ENFORCE_M4_5_RESTRICT_XSI_TYPE_ATTRIBUTE = flag; + return this; + } + + public boolean getForbidMarkupCompatibilityNamespace() { + return ENFORCE_M4_2_FORBID_MARKUP_COMPATIBILITY_NAMESPACE; + } + + public boolean getForbidRefiningDublinCoreElements() { + return ENFORCE_M4_3_FORBID_REFINING_DUBLIN_CORE_ELEMENTS; + } + + public boolean getForbidXmlLangAttributes() { + return ENFORCE_M4_4_FORBID_XML_LANG_ATTRIBUTE; + } + + public boolean getRestrictXsiTypeAttribute() { + return ENFORCE_M4_5_RESTRICT_XSI_TYPE_ATTRIBUTE; + } + +} diff --git a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/OPCPackage.java b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/OPCPackage.java index d7680bb616..b02b477825 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/OPCPackage.java +++ b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/OPCPackage.java @@ -141,6 +141,19 @@ public abstract class OPCPackage implements RelationshipSource, Closeable { * @throws OpenXML4JRuntimeException if there are issues creating properties part */ OPCPackage(PackageAccess access) { + this(access, OPCComplianceFlags.enforceAll()); + } + + /** + * Constructor. + * + * @param access Package access. + * @param opcComplianceFlags Enable or disable specific OPC compliance flags. + * This is useful to allow parsing of certain non-compliant documents. + * @throws OpenXML4JRuntimeException if there are issues creating properties part + * @since POI 5.4.1 + */ + OPCPackage(PackageAccess access, OPCComplianceFlags opcComplianceFlags) { if (getClass() != ZipPackage.class) { throw new IllegalArgumentException("PackageBase may not be subclassed"); } @@ -148,7 +161,7 @@ public abstract class OPCPackage implements RelationshipSource, Closeable { final ContentType contentType = newCorePropertiesPart(); // TODO Delocalize specialized marshallers - this.partUnmarshallers.put(contentType, new PackagePropertiesUnmarshaller()); + this.partUnmarshallers.put(contentType, new PackagePropertiesUnmarshaller(opcComplianceFlags)); this.partMarshallers.put(contentType, new ZipPackagePropertiesMarshaller()); } @@ -176,7 +189,24 @@ public abstract class OPCPackage implements RelationshipSource, Closeable { * occur. */ public static OPCPackage open(String path) throws InvalidFormatException { - return open(path, defaultPackageAccess); + return open(path, defaultPackageAccess, OPCComplianceFlags.enforceAll()); + } + + /** + * Open a package with read/write permission. + * + * @param path + * The document path. + * @param opcComplianceFlags + * The level of OPC compliance to enforce when reading the package + * @return A Package object, else <b>null</b>. + * @throws InvalidFormatException + * If the specified file doesn't exist, and a parsing error + * occur. + * @since POI 5.4.1 + */ + public static OPCPackage open(String path, OPCComplianceFlags opcComplianceFlags) throws InvalidFormatException { + return open(path, defaultPackageAccess, opcComplianceFlags); } /** @@ -193,6 +223,23 @@ public abstract class OPCPackage implements RelationshipSource, Closeable { return open(file, defaultPackageAccess); } + /** + * Open a package with read/write permission. + * + * @param file + * The file to open. + * @param opcComplianceFlags + * The level of OPC compliance to enforce when reading the package + * @return A Package object, else <b>null</b>. + * @throws InvalidFormatException + * If the specified file doesn't exist, and a parsing error + * occur. + * @since POI 5.4.1 + */ + public static OPCPackage open(File file, OPCComplianceFlags opcComplianceFlags) throws InvalidFormatException { + return open(file, defaultPackageAccess, opcComplianceFlags); + } + /** * Open a user provided {@link ZipEntrySource} with read-only permission. * This method can be used to stream data into POI. @@ -204,22 +251,39 @@ public abstract class OPCPackage implements RelationshipSource, Closeable { * @throws InvalidFormatException if a parsing error occur. */ public static OPCPackage open(ZipEntrySource zipEntry) throws InvalidFormatException { - OPCPackage pack = new ZipPackage(zipEntry, PackageAccess.READ); - try { - if (pack.partList == null) { - pack.getParts(); - } - // pack.originalPackagePath = file.getAbsolutePath(); - return pack; - } catch (InvalidFormatException | RuntimeException e) { - // use revert() to free resources when the package is opened read-only - pack.revert(); - - throw e; - } + return open(zipEntry, OPCComplianceFlags.enforceAll()); } /** + * Open a user provided {@link ZipEntrySource} with read-only permission. + * This method can be used to stream data into POI. + * Opposed to other open variants, the data is read as-is, e.g. there aren't + * any zip-bomb protection put in place. + * + * @param zipEntry the custom source + * @param opcComplianceFlags + * The level of OPC compliance to enforce when reading the package + * @return A Package object + * @throws InvalidFormatException if a parsing error occur. + * @since POI 5.4.1 + */ + public static OPCPackage open(ZipEntrySource zipEntry, OPCComplianceFlags opcComplianceFlags) throws InvalidFormatException { + OPCPackage pack = new ZipPackage(zipEntry, PackageAccess.READ, opcComplianceFlags); + try { + if (pack.partList == null) { + pack.getParts(); + } + // pack.originalPackagePath = file.getAbsolutePath(); + return pack; + } catch (InvalidFormatException | RuntimeException e) { + // use revert() to free resources when the package is opened read-only + pack.revert(); + + throw e; + } + } + + /** * Open a package. * * @param path @@ -235,6 +299,28 @@ public abstract class OPCPackage implements RelationshipSource, Closeable { */ public static OPCPackage open(String path, PackageAccess access) throws InvalidFormatException, InvalidOperationException { + return open(path, access, OPCComplianceFlags.enforceAll()); + } + + /** + * Open a package. + * + * @param path + * The document path. + * @param access + * PackageBase access. + * @param opcComplianceFlags + * The level of OPC compliance to enforce when reading the package + * @return A PackageBase object, else <b>null</b>. + * @throws InvalidFormatException + * If the specified file doesn't exist, and a parsing error + * occur. + * @throws InvalidOperationException If the zip file cannot be opened. + * @throws InvalidFormatException if the package is not valid. + * @since POI 5.4.1 + */ + public static OPCPackage open(String path, PackageAccess access, OPCComplianceFlags opcComplianceFlags) + throws InvalidFormatException, InvalidOperationException { if (StringUtil.isBlank(path)) { throw new IllegalArgumentException("'path' must be given"); } @@ -244,7 +330,7 @@ public abstract class OPCPackage implements RelationshipSource, Closeable { throw new IllegalArgumentException("path must not be a directory"); } - OPCPackage pack = new ZipPackage(path, access); // NOSONAR + OPCPackage pack = new ZipPackage(path, access, opcComplianceFlags); // NOSONAR boolean success = false; if (pack.partList == null && access != PackageAccess.WRITE) { try { @@ -275,38 +361,58 @@ public abstract class OPCPackage implements RelationshipSource, Closeable { */ public static OPCPackage open(File file, PackageAccess access) throws InvalidFormatException { - if (file == null) { - throw new IllegalArgumentException("'file' must be given"); - } - if (file.exists() && file.isDirectory()) { - throw new IllegalArgumentException("file must not be a directory"); - } - - final OPCPackage pack; - try { - pack = new ZipPackage(file, access); //NOSONAR - } catch (InvalidOperationException e) { - throw new InvalidFormatException(e.getMessage(), e); - } - try { - if (pack.partList == null && access != PackageAccess.WRITE) { - pack.getParts(); - } - pack.originalPackagePath = file.getAbsolutePath(); - return pack; - } catch (InvalidFormatException | RuntimeException e) { - if (access == PackageAccess.READ) { - pack.revert(); - } else { - IOUtils.closeQuietly(pack); - } - throw e; - } + return open(file, access, OPCComplianceFlags.enforceAll()); } /** * Open a package. * + * @param file + * The file to open. + * @param access + * PackageBase access. + * @param opcComplianceFlags + * The level of OPC compliance to enforce when reading the package + * @return A PackageBase object, else <b>null</b>. + * @throws InvalidFormatException + * If the specified file doesn't exist, and a parsing error + * occur. + * @since POI 5.4.1 + */ + public static OPCPackage open(File file, PackageAccess access, OPCComplianceFlags opcComplianceFlags) + throws InvalidFormatException { + if (file == null) { + throw new IllegalArgumentException("'file' must be given"); + } + if (file.exists() && file.isDirectory()) { + throw new IllegalArgumentException("file must not be a directory"); + } + + final OPCPackage pack; + try { + pack = new ZipPackage(file, access, opcComplianceFlags); //NOSONAR + } catch (InvalidOperationException e) { + throw new InvalidFormatException(e.getMessage(), e); + } + try { + if (pack.partList == null && access != PackageAccess.WRITE) { + pack.getParts(); + } + pack.originalPackagePath = file.getAbsolutePath(); + return pack; + } catch (InvalidFormatException | RuntimeException e) { + if (access == PackageAccess.READ) { + pack.revert(); + } else { + IOUtils.closeQuietly(pack); + } + throw e; + } + } + + /** + * Open a package. + * * Note - uses quite a bit more memory than {@link #open(String)}, which * doesn't need to hold the whole zip file in memory, and can take advantage * of native methods @@ -321,9 +427,32 @@ public abstract class OPCPackage implements RelationshipSource, Closeable { */ public static OPCPackage open(InputStream in) throws InvalidFormatException, IOException { + return open(in, OPCComplianceFlags.enforceAll()); + } + + /** + * Open a package. + * + * Note - uses quite a bit more memory than {@link #open(String)}, which + * doesn't need to hold the whole zip file in memory, and can take advantage + * of native methods + * + * @param in + * The InputStream to read the package from. The stream is closed. + * @param opcComplianceFlags + * The level of OPC compliance to enforce when reading the package + * @return A PackageBase object + * + * @throws InvalidFormatException + * Throws if the specified file exist and is not valid. + * @throws IOException If reading the stream fails + * @since POI 5.4.1 + */ + public static OPCPackage open(InputStream in, OPCComplianceFlags opcComplianceFlags) throws InvalidFormatException, + IOException { final OPCPackage pack; try { - pack = new ZipPackage(in, PackageAccess.READ_WRITE); + pack = new ZipPackage(in, PackageAccess.READ_WRITE, opcComplianceFlags); } catch (InvalidZipException e) { throw new InvalidFormatException(e.getMessage(), e); } @@ -358,9 +487,34 @@ public abstract class OPCPackage implements RelationshipSource, Closeable { */ public static OPCPackage open(InputStream in, boolean closeStream) throws InvalidFormatException, IOException { + return open(in, closeStream, OPCComplianceFlags.enforceAll()); + } + + /** + * Open a package. + * + * Note - uses quite a bit more memory than {@link #open(String)}, which + * doesn't need to hold the whole zip file in memory, and can take advantage + * of native methods + * + * @param in + * The InputStream to read the package from. + * @param closeStream + * Whether to close the input stream. + * @param opcComplianceFlags + * The level of OPC compliance to enforce when reading the package + * @return A PackageBase object + * + * @throws InvalidFormatException + * Throws if the specified file exist and is not valid. + * @throws IOException If reading the stream fails + * @since POI 5.4.1 + */ + public static OPCPackage open(InputStream in, boolean closeStream, OPCComplianceFlags opcComplianceFlags) throws InvalidFormatException, + IOException { final OPCPackage pack; try { - pack = new ZipPackage(in, PackageAccess.READ_WRITE, closeStream); + pack = new ZipPackage(in, PackageAccess.READ_WRITE, closeStream, opcComplianceFlags); } catch (InvalidZipException e) { throw new InvalidFormatException(e.getMessage(), e); } diff --git a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/PackagePartName.java b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/PackagePartName.java index 14a1ee56cc..971064db69 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/PackagePartName.java +++ b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/PackagePartName.java @@ -356,7 +356,7 @@ public final class PackagePartName implements Comparable<PackagePartName> { private static void throwExceptionIfPartNameNotStartsWithForwardSlashChar( URI partUri) throws InvalidFormatException { String uriPath = partUri.getPath(); - if (uriPath.length() > 0 + if (!uriPath.isEmpty() && uriPath.charAt(0) != PackagingURIHelper.FORWARD_SLASH_CHAR) { throw new InvalidFormatException( "A part name shall start with a forward slash ('/') character [M1.4]: " @@ -377,7 +377,7 @@ public final class PackagePartName implements Comparable<PackagePartName> { private static void throwExceptionIfPartNameEndsWithForwardSlashChar( URI partUri) throws InvalidFormatException { String uriPath = partUri.getPath(); - if (uriPath.length() > 0 + if (!uriPath.isEmpty() && uriPath.charAt(uriPath.length() - 1) == PackagingURIHelper.FORWARD_SLASH_CHAR) { throw new InvalidFormatException( "A part name shall not have a forward slash as the last character [M1.5]: " @@ -422,7 +422,7 @@ public final class PackagePartName implements Comparable<PackagePartName> { */ public String getExtension() { String fragment = this.partNameURI.getPath(); - if (fragment.length() > 0) { + if (!fragment.isEmpty()) { int i = fragment.lastIndexOf('.'); if (i > -1) { return fragment.substring(i + 1); diff --git a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/PackagingURIHelper.java b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/PackagingURIHelper.java index bb58523580..58718a6f32 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/PackagingURIHelper.java +++ b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/PackagingURIHelper.java @@ -287,7 +287,7 @@ public final class PackagingURIHelper { // form must actually be an absolute URI if(sourceURI.toString().equals("/")) { String path = targetURI.getPath(); - if(msCompatible && path.length() > 0 && path.charAt(0) == '/') { + if(msCompatible && !path.isEmpty() && path.charAt(0) == '/') { try { targetURI = new URI(path.substring(1)); } catch (Exception e) { @@ -701,7 +701,7 @@ public final class PackagingURIHelper { } // trailing white spaces must be url-encoded, see Bugzilla 53282 - if(value.length() > 0 ){ + if(!value.isEmpty()){ StringBuilder b = new StringBuilder(); int idx = value.length() - 1; for(; idx >= 0; idx--){ diff --git a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/ZipPackage.java b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/ZipPackage.java index e4b58a239b..22ef9023d9 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/ZipPackage.java +++ b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/ZipPackage.java @@ -103,7 +103,17 @@ public final class ZipPackage extends OPCPackage { * Constructor. Creates a new, empty ZipPackage. */ public ZipPackage() { - super(defaultPackageAccess); + this(OPCComplianceFlags.enforceAll()); + } + + /** + * Constructor. Creates a new, empty ZipPackage. + * @param opcComplianceFlags + * The level of OPC compliance to enforce when reading the package + * @since POI 5.4.1 + */ + public ZipPackage(OPCComplianceFlags opcComplianceFlags) { + super(defaultPackageAccess, opcComplianceFlags); this.zipArchive = null; try { @@ -128,7 +138,28 @@ public final class ZipPackage extends OPCPackage { * if input stream cannot be opened, read, or closed */ ZipPackage(InputStream in, PackageAccess access) throws IOException { - super(access); + this(in, access, OPCComplianceFlags.enforceAll()); + } + + /** + * Constructor. Opens a Zip based Open XML document from + * an InputStream. The InputStream is closed. + * + * @param in + * Zip input stream to load. + * @param access + * The package access mode. + * @param opcComplianceFlags + * The level of OPC compliance to enforce when reading the package + * @throws IllegalArgumentException + * If the specified input stream is not an instance of + * ZipInputStream. + * @throws IOException + * if input stream cannot be opened, read, or closed + * @since POI 5.4.1 + */ + ZipPackage(InputStream in, PackageAccess access, OPCComplianceFlags opcComplianceFlags) throws IOException { + super(access, opcComplianceFlags); try (ZipArchiveThresholdInputStream zis = ZipHelper.openZipStream(in)) { this.zipArchive = new ZipInputStreamZipEntrySource(zis); } @@ -152,7 +183,30 @@ public final class ZipPackage extends OPCPackage { * @since POI 5.2.5 */ ZipPackage(InputStream in, PackageAccess access, boolean closeStream) throws IOException { - super(access); + this(in, access, closeStream, OPCComplianceFlags.enforceAll()); + } + + /** + * Constructor. Opens a Zip based Open XML document from + * an InputStream. + * + * @param in + * Zip input stream to load. + * @param access + * The package access mode. + * @param closeStream + * Whether to close the input stream. + * @param opcComplianceFlags + * The level of OPC compliance to enforce when reading the package + * @throws IllegalArgumentException + * If the specified input stream is not an instance of + * ZipInputStream. + * @throws IOException + * if input stream cannot be opened, read, or closed + * @since POI 5.4.1 + */ + ZipPackage(InputStream in, PackageAccess access, boolean closeStream, OPCComplianceFlags opcComplianceFlags) throws IOException { + super(access, opcComplianceFlags); try (ZipArchiveThresholdInputStream zis = ZipHelper.openZipStream(in, closeStream)) { this.zipArchive = new ZipInputStreamZipEntrySource(zis); } @@ -168,7 +222,23 @@ public final class ZipPackage extends OPCPackage { * @throws InvalidOperationException If the zip file cannot be opened. */ ZipPackage(String path, PackageAccess access) throws InvalidOperationException { - this(new File(path), access); + this(path, access, OPCComplianceFlags.enforceAll()); + } + + /** + * Constructor. Opens a Zip based Open XML document from a file. + * + * @param path + * The path of the file to open or create. + * @param access + * The package access mode. + * @param opcComplianceFlags + * The level of OPC compliance to enforce when reading the package + * @throws InvalidOperationException If the zip file cannot be opened. + * @since POI 5.4.1 + */ + ZipPackage(String path, PackageAccess access, OPCComplianceFlags opcComplianceFlags) throws InvalidOperationException { + this(new File(path), access, opcComplianceFlags); } /** @@ -181,7 +251,23 @@ public final class ZipPackage extends OPCPackage { * @throws InvalidOperationException If the zip file cannot be opened. */ ZipPackage(File file, PackageAccess access) throws InvalidOperationException { - super(access); + this(file, access, OPCComplianceFlags.enforceAll()); + } + + /** + * Constructor. Opens a Zip based Open XML document from a File. + * + * @param file + * The file to open or create. + * @param access + * The package access mode. + * @param opcComplianceFlags + * The level of OPC compliance to enforce when reading the package + * @throws InvalidOperationException If the zip file cannot be opened. + * @since POI 5.4.1 + */ + ZipPackage(File file, PackageAccess access, OPCComplianceFlags opcComplianceFlags) throws InvalidOperationException { + super(access, opcComplianceFlags); ZipEntrySource ze; try { @@ -248,7 +334,24 @@ public final class ZipPackage extends OPCPackage { * The package access mode. */ ZipPackage(ZipEntrySource zipEntry, PackageAccess access) { - super(access); + this(zipEntry, access, OPCComplianceFlags.enforceAll()); + } + + /** + * Constructor. Opens a Zip based Open XML document from + * a custom ZipEntrySource, typically an open archive + * from another system + * + * @param zipEntry + * Zip data to load. + * @param access + * The package access mode. + * @param access + * The package access mode. + * @since POI 5.4.1 + */ + ZipPackage(ZipEntrySource zipEntry, PackageAccess access, OPCComplianceFlags opcComplianceFlags) { + super(access, opcComplianceFlags); this.zipArchive = zipEntry; } @@ -529,7 +632,7 @@ public final class ZipPackage extends OPCPackage { * * @param outputStream * The stream use to save this package. - * + * @throws OpenXML4JRuntimeException if there is an error while saving the package. * @see #save(OutputStream) */ @Override @@ -568,13 +671,19 @@ public final class ZipPackage extends OPCPackage { // Save content type part. LOG.atDebug().log("Save content types part"); - this.contentTypeManager.save(zos); + if (!this.contentTypeManager.save(zos)) { + throw new OpenXML4JRuntimeException( + "Failed to save: content types part"); + } // Save package relationships part. LOG.atDebug().log("Save package relationships"); - ZipPartMarshaller.marshallRelationshipPart(this.getRelationships(), + if (!ZipPartMarshaller.marshallRelationshipPart(this.getRelationships(), PackagingURIHelper.PACKAGE_RELATIONSHIPS_ROOT_PART_NAME, - zos); + zos)) { + throw new OpenXML4JRuntimeException( + "Failed to save: package relationships part"); + } // Save parts. for (PackagePart part : getParts()) { diff --git a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/internal/ContentTypeManager.java b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/internal/ContentTypeManager.java index 072fc6e283..3b5303d206 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/internal/ContentTypeManager.java +++ b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/internal/ContentTypeManager.java @@ -151,7 +151,7 @@ public abstract class ContentTypeManager { public void addContentType(PackagePartName partName, String contentType) { boolean defaultCTExists = this.defaultContentType.containsValue(contentType); String extension = partName.getExtension().toLowerCase(Locale.ROOT); - if ((extension.length() == 0) || + if (extension.isEmpty() || // check if content-type and extension do match in both directions // some applications create broken files, e.g. extension "jpg" instead of "jpeg" (this.defaultContentType.containsKey(extension) && !defaultCTExists) || diff --git a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/internal/marshallers/ZipPartMarshaller.java b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/internal/marshallers/ZipPartMarshaller.java index 4fd41915e2..b9d878a1af 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/internal/marshallers/ZipPartMarshaller.java +++ b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/internal/marshallers/ZipPartMarshaller.java @@ -104,7 +104,7 @@ public final class ZipPartMarshaller implements PartMarshaller { PackagePartName relationshipPartName = PackagingURIHelper .getRelationshipPartName(part.getPartName()); - marshallRelationshipPart(part.getRelationships(), + return marshallRelationshipPart(part.getRelationships(), relationshipPartName, zos); } diff --git a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/internal/unmarshallers/PackagePropertiesUnmarshaller.java b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/internal/unmarshallers/PackagePropertiesUnmarshaller.java index 58fe525dc4..9ac8083a32 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/internal/unmarshallers/PackagePropertiesUnmarshaller.java +++ b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/opc/internal/unmarshallers/PackagePropertiesUnmarshaller.java @@ -28,6 +28,7 @@ import org.apache.poi.openxml4j.opc.PackageNamespaces; import org.apache.poi.openxml4j.opc.PackagePart; import org.apache.poi.openxml4j.opc.PackageProperties; import org.apache.poi.openxml4j.opc.ZipPackage; +import org.apache.poi.openxml4j.opc.OPCComplianceFlags; import org.apache.poi.openxml4j.opc.internal.PackagePropertiesPart; import org.apache.poi.openxml4j.opc.internal.PartUnmarshaller; import org.apache.poi.openxml4j.opc.internal.ZipHelper; @@ -44,6 +45,23 @@ import org.xml.sax.SAXException; */ public final class PackagePropertiesUnmarshaller implements PartUnmarshaller { + /** + * Whether OPC compliance requirements are checked (e.g., M4.2, M4.3, M4.4, and M4.5) + */ + private OPCComplianceFlags opcComplianceFlags; + + public PackagePropertiesUnmarshaller() { + this(OPCComplianceFlags.enforceAll()); + } + + /** + * @param opcComplianceFlags Overrides the default OPC compliance settings + * @since POI 5.4.1 + */ + public PackagePropertiesUnmarshaller(OPCComplianceFlags opcComplianceFlags) { + this.opcComplianceFlags = opcComplianceFlags; + } + protected static final String KEYWORD_CATEGORY = "category"; protected static final String KEYWORD_CONTENT_STATUS = "contentStatus"; @@ -234,24 +252,28 @@ public final class PackagePropertiesUnmarshaller implements PartUnmarshaller { */ public void checkElementForOPCCompliance(Element el) throws InvalidFormatException { - // Check the current element - NamedNodeMap namedNodeMap = el.getAttributes(); - int namedNodeCount = namedNodeMap.getLength(); - for (int i = 0; i < namedNodeCount; i++) { - Attr attr = (Attr)namedNodeMap.item(0); - - if (attr != null && XMLConstants.XMLNS_ATTRIBUTE_NS_URI.equals(attr.getNamespaceURI())) { - // Rule M4.2 - if (PackageNamespaces.MARKUP_COMPATIBILITY.equals(attr.getValue())) { - throw new InvalidFormatException( - "OPC Compliance error [M4.2]: A format consumer shall consider the use of the Markup Compatibility namespace to be an error."); + + if (opcComplianceFlags.getForbidMarkupCompatibilityNamespace()) { + // Check the current element + NamedNodeMap namedNodeMap = el.getAttributes(); + int namedNodeCount = namedNodeMap.getLength(); + for (int i = 0; i < namedNodeCount; i++) { + Attr attr = (Attr)namedNodeMap.item(0); + + if (attr != null && XMLConstants.XMLNS_ATTRIBUTE_NS_URI.equals(attr.getNamespaceURI())) { + // Rule M4.2 + if (PackageNamespaces.MARKUP_COMPATIBILITY.equals(attr.getValue())) { + throw new InvalidFormatException( + "OPC Compliance error [M4.2]: A format consumer shall consider the use of the Markup Compatibility namespace to be an error."); + } } } } // Rule M4.3 String elName = el.getLocalName(); - if (PackageProperties.NAMESPACE_DCTERMS.equals(el.getNamespaceURI())) { + if (opcComplianceFlags.getForbidRefiningDublinCoreElements() && + PackageProperties.NAMESPACE_DCTERMS.equals(el.getNamespaceURI())) { if (!(KEYWORD_CREATED.equals(elName) || KEYWORD_MODIFIED.equals(elName))) { throw new InvalidFormatException( "OPC Compliance error [M4.3]: Producers shall not create a document element that contains refinements to the Dublin Core elements, except for the two specified in the schema: <dcterms:created> and <dcterms:modified> Consumers shall consider a document element that violates this constraint to be an error."); @@ -259,13 +281,15 @@ public final class PackagePropertiesUnmarshaller implements PartUnmarshaller { } // Rule M4.4 - if (el.getAttributeNodeNS(XMLConstants.XML_NS_URI, "lang") != null) { + if (opcComplianceFlags.getForbidXmlLangAttributes() && + el.getAttributeNodeNS(XMLConstants.XML_NS_URI, "lang") != null) { throw new InvalidFormatException( "OPC Compliance error [M4.4]: Producers shall not create a document element that contains the xml:lang attribute. Consumers shall consider a document element that violates this constraint to be an error."); } // Rule M4.5 - if (PackageProperties.NAMESPACE_DCTERMS.equals(el.getNamespaceURI())) { + if (opcComplianceFlags.getRestrictXsiTypeAttribute() && + PackageProperties.NAMESPACE_DCTERMS.equals(el.getNamespaceURI())) { // DCTerms namespace only use with 'created' and 'modified' elements if (!(elName.equals(KEYWORD_CREATED) || elName.equals(KEYWORD_MODIFIED))) { throw new InvalidFormatException("Namespace error : " + elName diff --git a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/util/ZipArchiveFakeEntry.java b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/util/ZipArchiveFakeEntry.java index a10e43c277..9648476001 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/util/ZipArchiveFakeEntry.java +++ b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/util/ZipArchiveFakeEntry.java @@ -35,7 +35,7 @@ import org.apache.poi.util.TempFile; * close this as soon as you can! * @see ZipInputStreamZipEntrySource#setThresholdBytesForTempFiles(int) */ -/* package */ class ZipArchiveFakeEntry extends ZipArchiveEntry implements Closeable { +public final class ZipArchiveFakeEntry extends ZipArchiveEntry implements Closeable { private static final Logger LOG = PoiLogManager.getLogger(ZipArchiveFakeEntry.class); // how large a single entry in a zip-file should become at max @@ -43,12 +43,22 @@ import org.apache.poi.util.TempFile; private static final int DEFAULT_MAX_ENTRY_SIZE = 100_000_000; private static int MAX_ENTRY_SIZE = DEFAULT_MAX_ENTRY_SIZE; + /** + * Set the maximum size of a single entry in a zip-file. + * @param maxEntrySize number of bytes at which a zip entry is regarded as too large for holding in memory + * - defaults to 100_000_000 (approx 100Mb). A value of -1 means the default value is used. + */ public static void setMaxEntrySize(int maxEntrySize) { - MAX_ENTRY_SIZE = maxEntrySize; + if(maxEntrySize < 0) { + MAX_ENTRY_SIZE = DEFAULT_MAX_ENTRY_SIZE; + } else { + MAX_ENTRY_SIZE = maxEntrySize; + } } public static int getMaxEntrySize() { - return MAX_ENTRY_SIZE; + final int ioMaxSize = IOUtils.getByteArrayMaxOverride(); + return ioMaxSize < 0 ? MAX_ENTRY_SIZE : Math.min(MAX_ENTRY_SIZE, ioMaxSize); } private byte[] data; @@ -61,7 +71,7 @@ import org.apache.poi.util.TempFile; final long entrySize = entry.getSize(); final int threshold = ZipInputStreamZipEntrySource.getThresholdBytesForTempFiles(); - if (threshold >= 0 && entrySize >= threshold) { + if (threshold >= 0 && (entrySize >= threshold || entrySize == -1)) { if (ZipInputStreamZipEntrySource.shouldEncryptTempFiles()) { encryptedTempData = new EncryptedTempData(); try (OutputStream os = encryptedTempData.getOutputStream()) { @@ -80,7 +90,7 @@ import org.apache.poi.util.TempFile; // Grab the de-compressed contents for later data = (entrySize == -1) ? IOUtils.toByteArrayWithMaxLength(inp, getMaxEntrySize()) : - IOUtils.toByteArray(inp, (int)entrySize, getMaxEntrySize()); + IOUtils.toByteArray(inp, entrySize, getMaxEntrySize()); } } diff --git a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/util/ZipArchiveThresholdInputStream.java b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/util/ZipArchiveThresholdInputStream.java index 68c813dbbb..fe6c77150b 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/openxml4j/util/ZipArchiveThresholdInputStream.java +++ b/poi-ooxml/src/main/java/org/apache/poi/openxml4j/util/ZipArchiveThresholdInputStream.java @@ -123,8 +123,8 @@ public class ZipArchiveThresholdInputStream extends FilterInputStream { final String entryName = entry == null ? "not set" : entry.getName(); // check the file size first, in case we are working on uncompressed streams - if (payloadSize > MAX_ENTRY_SIZE) { - throw new IOException(String.format(Locale.ROOT, MAX_ENTRY_SIZE_MSG, payloadSize, rawSize, MAX_ENTRY_SIZE, entryName)); + if (payloadSize > getMaxEntrySize()) { + throw new IOException(String.format(Locale.ROOT, MAX_ENTRY_SIZE_MSG, payloadSize, rawSize, getMaxEntrySize(), entryName)); } // don't alert for small expanded size diff --git a/poi-ooxml/src/main/java/org/apache/poi/poifs/crypt/dsig/SignatureInfo.java b/poi-ooxml/src/main/java/org/apache/poi/poifs/crypt/dsig/SignatureInfo.java index 4b487fcc9e..2e6f7aa99f 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/poifs/crypt/dsig/SignatureInfo.java +++ b/poi-ooxml/src/main/java/org/apache/poi/poifs/crypt/dsig/SignatureInfo.java @@ -154,7 +154,7 @@ import org.w3c.dom.events.MutationEvent; * <p>To use SignatureInfo and its sibling classes, you'll need to have the following libs * in the classpath:</p> * <ul> - * <li>BouncyCastle bcpkix and bcprov (tested against 1.80)</li> + * <li>BouncyCastle bcpkix and bcprov (tested against 1.81)</li> * <li>Apache Santuario "xmlsec" (tested against 3.0.x)</li> * <li>and log4j-api (tested against 2.22.x)</li> * </ul> diff --git a/poi-ooxml/src/main/java/org/apache/poi/poifs/crypt/dsig/services/TimeStampSimpleHttpClient.java b/poi-ooxml/src/main/java/org/apache/poi/poifs/crypt/dsig/services/TimeStampSimpleHttpClient.java index f7e3b9aeb1..74a0138aa9 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/poifs/crypt/dsig/services/TimeStampSimpleHttpClient.java +++ b/poi-ooxml/src/main/java/org/apache/poi/poifs/crypt/dsig/services/TimeStampSimpleHttpClient.java @@ -24,6 +24,8 @@ import java.net.HttpURLConnection; import java.net.InetAddress; import java.net.InetSocketAddress; import java.net.Proxy; +import java.net.URI; +import java.net.URISyntaxException; import java.net.URL; import java.nio.charset.StandardCharsets; import java.security.GeneralSecurityException; @@ -72,7 +74,8 @@ public class TimeStampSimpleHttpClient implements TimeStampHttpClient { * @return the max timestamp response size allowed */ public static int getMaxTimestampResponseSize() { - return MAX_TIMESTAMP_RESPONSE_SIZE; + final int ioMaxSize = IOUtils.getByteArrayMaxOverride(); + return ioMaxSize < 0 ? MAX_TIMESTAMP_RESPONSE_SIZE : Math.min(MAX_TIMESTAMP_RESPONSE_SIZE, ioMaxSize); } @@ -126,11 +129,11 @@ public class TimeStampSimpleHttpClient implements TimeStampHttpClient { proxy = Proxy.NO_PROXY; } else { try { - URL pUrl = new URL(proxyUrl); + URL pUrl = new URI(proxyUrl).toURL(); String host = pUrl.getHost(); int port = pUrl.getPort(); proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress(InetAddress.getByName(host), (port == -1 ? 80 : port))); - } catch (IOException ignored) { + } catch (IOException | URISyntaxException ignored) { } } } @@ -204,7 +207,12 @@ public class TimeStampSimpleHttpClient implements TimeStampHttpClient { } protected TimeStampHttpClientResponse handleRedirect(String url, MethodHandler handler, boolean followRedirect) throws IOException { - HttpURLConnection huc = (HttpURLConnection)new URL(url).openConnection(proxy); + final HttpURLConnection huc; + try { + huc = (HttpURLConnection)new URI(url).toURL().openConnection(proxy); + } catch (URISyntaxException e) { + throw new IOException(e); + } if (ignoreHttpsCertificates) { recklessConnection(huc); } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xddf/usermodel/chart/XDDFChart.java b/poi-ooxml/src/main/java/org/apache/poi/xddf/usermodel/chart/XDDFChart.java index bfbb775296..4bfb948589 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xddf/usermodel/chart/XDDFChart.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xddf/usermodel/chart/XDDFChart.java @@ -688,7 +688,7 @@ public abstract class XDDFChart extends POIXMLDocumentPart implements TextContai if (axes.isEmpty() && hasAxes()) { parseAxes(); } - return axes; + return Collections.unmodifiableList(axes); } private boolean hasAxes() { diff --git a/poi-ooxml/src/main/java/org/apache/poi/xddf/usermodel/chart/XDDFChartData.java b/poi-ooxml/src/main/java/org/apache/poi/xddf/usermodel/chart/XDDFChartData.java index 1dc47d47a4..983ef4f138 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xddf/usermodel/chart/XDDFChartData.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xddf/usermodel/chart/XDDFChartData.java @@ -28,7 +28,6 @@ import org.apache.poi.logging.PoiLogManager; import org.apache.poi.ss.util.CellReference; import org.apache.poi.util.Beta; import org.apache.poi.util.Internal; -import org.apache.poi.util.Removal; import org.apache.poi.xddf.usermodel.XDDFFillProperties; import org.apache.poi.xddf.usermodel.XDDFLineProperties; import org.apache.poi.xddf.usermodel.XDDFShapeProperties; @@ -85,27 +84,6 @@ public abstract class XDDFChartData { return valueAxes; } - /** - * Calls to {@code getSeries().add(series)} or to {@code getSeries().remove(series)} - * may corrupt the workbook. - * - * <p> - * Instead, use the following methods: - * <ul> - * <li>{@link #getSeriesCount()}</li> - * <li>{@link #getSeries(int)}</li> - * <li>{@link #addSeries(XDDFDataSource,XDDFNumericalDataSource)}</li> - * <li>{@link #removeSeries(int)}</li> - * </ul> - * - * @deprecated since POI 4.1.1 - */ - @Deprecated - @Removal(version = "5.3") - public List<Series> getSeries() { - return Collections.unmodifiableList(series); - } - public final int getSeriesCount() { return series.size(); } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xddf/usermodel/text/XDDFTextParagraph.java b/poi-ooxml/src/main/java/org/apache/poi/xddf/usermodel/text/XDDFTextParagraph.java index 2fad9ddbbe..9f8b581c80 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xddf/usermodel/text/XDDFTextParagraph.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xddf/usermodel/text/XDDFTextParagraph.java @@ -113,7 +113,7 @@ public class XDDFTextParagraph implements Iterable<XDDFTextRun> { } public List<XDDFTextRun> getTextRuns() { - return _runs; + return Collections.unmodifiableList(_runs); } @Override diff --git a/poi-ooxml/src/main/java/org/apache/poi/xdgf/usermodel/XDGFShape.java b/poi-ooxml/src/main/java/org/apache/poi/xdgf/usermodel/XDGFShape.java index 25b3af8f93..02f05ad1c5 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xdgf/usermodel/XDGFShape.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xdgf/usermodel/XDGFShape.java @@ -27,6 +27,7 @@ import java.awt.geom.Path2D; import java.awt.geom.Rectangle2D; import java.util.ArrayList; import java.util.Collection; +import java.util.Collections; import java.util.List; import java.util.Map.Entry; @@ -307,7 +308,7 @@ public class XDGFShape extends XDGFSheet { */ // -> May be null public List<XDGFShape> getShapes() { - return _shapes; + return _shapes == null ? null : Collections.unmodifiableList(_shapes); } // unique to this shape on the page? diff --git a/poi-ooxml/src/main/java/org/apache/poi/xdgf/usermodel/XDGFText.java b/poi-ooxml/src/main/java/org/apache/poi/xdgf/usermodel/XDGFText.java index c823bb343d..c2fc839d39 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xdgf/usermodel/XDGFText.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xdgf/usermodel/XDGFText.java @@ -110,7 +110,7 @@ public class XDGFText { public void draw(Graphics2D graphics) { String textContent = getTextContent(); - if (textContent.length() == 0) { + if (textContent.isEmpty()) { return; } @@ -148,7 +148,7 @@ public class XDGFText { float nextY = 0; for (String line : lines) { - if (line.length() == 0) { + if (line.isEmpty()) { continue; } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XMLSlideShow.java b/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XMLSlideShow.java index 3f7e0df090..0def14f8ce 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XMLSlideShow.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XMLSlideShow.java @@ -30,12 +30,14 @@ import java.util.Arrays; import java.util.Collections; import java.util.HashMap; import java.util.List; +import java.util.Locale; import java.util.Map; import java.util.OptionalLong; import java.util.regex.Pattern; import java.util.stream.Stream; import org.apache.logging.log4j.Logger; +import org.apache.poi.POIException; import org.apache.poi.logging.PoiLogManager; import org.apache.poi.ooxml.POIXMLDocument; import org.apache.poi.ooxml.POIXMLDocumentPart; @@ -55,6 +57,7 @@ import org.apache.poi.util.LittleEndian; import org.apache.poi.util.LittleEndianConsts; import org.apache.poi.util.NotImplemented; import org.apache.poi.util.Units; +import org.apache.poi.util.XMLHelper; import org.apache.xmlbeans.XmlException; import org.openxmlformats.schemas.presentationml.x2006.main.CTNotesMasterIdList; import org.openxmlformats.schemas.presentationml.x2006.main.CTNotesMasterIdListEntry; @@ -78,6 +81,7 @@ public class XMLSlideShow extends POIXMLDocument //arbitrarily selected; may need to increase private static final int DEFAULT_MAX_RECORD_LENGTH = 1_000_000; private static int MAX_RECORD_LENGTH = DEFAULT_MAX_RECORD_LENGTH; + private static final int MAX_NODE_DEPTH = 1000; private static final Pattern GET_ALL_EMBEDDED_PARTS_PATTERN = Pattern.compile("/ppt/embeddings/.*?"); private static final Pattern GET_PICTURE_DATA_PATTERN = Pattern.compile("/ppt/media/.*?"); @@ -174,6 +178,13 @@ public class XMLSlideShow extends POIXMLDocument PresentationDocument doc = PresentationDocument.Factory.parse(stream, DEFAULT_XML_OPTIONS); _presentation = doc.getPresentation(); } + final int nodeDepth = XMLHelper.getDepthOfChildNodes(_presentation.getDomNode(), MAX_NODE_DEPTH); + if (nodeDepth > MAX_NODE_DEPTH) { + throw new IOException(String.format(Locale.ROOT, + "The document is too complex, it has a node depth of %s, which exceeds the maximum allowed of %s", + nodeDepth, + MAX_NODE_DEPTH)); + } Map<String, XSLFSlideMaster> masterMap = new HashMap<>(); Map<String, XSLFSlide> shIdMap = new HashMap<>(); @@ -219,6 +230,8 @@ public class XMLSlideShow extends POIXMLDocument } }); } + } catch (POIException e) { + throw new IOException(e); } catch (XmlException e) { throw new POIXMLException(e); } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XSLFPictureData.java b/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XSLFPictureData.java index 60ef156abe..82daee8dbe 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XSLFPictureData.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XSLFPictureData.java @@ -58,7 +58,8 @@ public final class XSLFPictureData extends POIXMLDocumentPart implements Picture * @return the max image size allowed for XSLF pictures */ public static int getMaxImageSize() { - return MAX_IMAGE_SIZE; + final int ioMaxSize = IOUtils.getByteArrayMaxOverride(); + return ioMaxSize < 0 ? MAX_IMAGE_SIZE : Math.min(MAX_IMAGE_SIZE, ioMaxSize); } private Long checksum; diff --git a/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XSLFTextParagraph.java b/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XSLFTextParagraph.java index 635200e12e..4563ee0278 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XSLFTextParagraph.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xslf/usermodel/XSLFTextParagraph.java @@ -952,7 +952,7 @@ public class XSLFTextParagraph implements TextParagraph<XSLFShape,XSLFTextParagr } else if (ostyle instanceof String) { setBulletFont((String)ostyle); } else if (ostyle instanceof AutoNumberingScheme) { - setBulletAutoNumber((AutoNumberingScheme)ostyle, 0); + setBulletAutoNumber((AutoNumberingScheme)ostyle, 1); } } } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/binary/XSSFBHeaderFooter.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/binary/XSSFBHeaderFooter.java index 4b0a599974..5a67148221 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/binary/XSSFBHeaderFooter.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/binary/XSSFBHeaderFooter.java @@ -51,16 +51,16 @@ class XSSFBHeaderFooter { String left = HEADER_FOOTER_HELPER.getLeftSection(rawString); String center = HEADER_FOOTER_HELPER.getCenterSection(rawString); String right = HEADER_FOOTER_HELPER.getRightSection(rawString); - if (left != null && left.length() > 0) { + if (left != null && !left.isEmpty()) { sb.append(left); } - if (center != null && center.length() > 0) { + if (center != null && !center.isEmpty()) { if (sb.length() > 0) { sb.append(' '); } sb.append(center); } - if (right != null && right.length() > 0) { + if (right != null && !right.isEmpty()) { if (sb.length() > 0) { sb.append(' '); } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/binary/XSSFBHyperlinksTable.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/binary/XSSFBHyperlinksTable.java index b89e0ac943..e77308db6e 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/binary/XSSFBHyperlinksTable.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/binary/XSSFBHyperlinksTable.java @@ -152,7 +152,7 @@ public class XSSFBHyperlinksTable { CellRangeAddress cellRangeAddress = new CellRangeAddress(hyperlinkCellRange.firstRow, hyperlinkCellRange.lastRow, hyperlinkCellRange.firstCol, hyperlinkCellRange.lastCol); String url = relIdToHyperlink.get(relId); - if (location.length() == 0) { + if (location.isEmpty()) { location = url; } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/binary/XSSFBParser.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/binary/XSSFBParser.java index 8822053180..c56f8ac713 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/binary/XSSFBParser.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/binary/XSSFBParser.java @@ -107,7 +107,7 @@ public abstract class XSSFBParser { } if (records == null || records.get(recordId)) { - byte[] buff = IOUtils.safelyAllocate(recordLength, MAX_RECORD_LENGTH); + byte[] buff = IOUtils.safelyAllocate(recordLength, getMaxRecordLength()); is.readFully(buff); handleRecord(recordId, buff); } else { diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/eventusermodel/XSSFReader.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/eventusermodel/XSSFReader.java index 0910795230..09e4c1df77 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/eventusermodel/XSSFReader.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/eventusermodel/XSSFReader.java @@ -178,7 +178,7 @@ public class XSSFReader { // Create the Styles Table, and associate the Themes if present StylesTable styles = new StylesTable(parts.get(0)); parts = pkg.getPartsByContentType(XSSFRelation.THEME.getContentType()); - if (parts.size() != 0) { + if (!parts.isEmpty()) { styles.setTheme(new ThemesTable(parts.get(0))); } return styles; @@ -359,7 +359,7 @@ public class XSSFReader { for (XSSFSheetRef xssfSheetRef : xmlSheetRefReader.getSheetRefs()) { //if there's no relationship id, silently skip the sheet String sheetId = xssfSheetRef.getId(); - if (sheetId != null && sheetId.length() > 0) { + if (sheetId != null && !sheetId.isEmpty()) { validSheets.add(xssfSheetRef); } } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/eventusermodel/XSSFSheetXMLHandler.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/eventusermodel/XSSFSheetXMLHandler.java index b5cc39728b..110d343d7b 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/eventusermodel/XSSFSheetXMLHandler.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/eventusermodel/XSSFSheetXMLHandler.java @@ -253,7 +253,7 @@ public class XSSFSheetXMLHandler extends DefaultHandler { } else if ("row".equals(localName)) { String rowNumStr = attributes.getValue("r"); if (rowNumStr != null) { - rowNum = Integer.parseInt(rowNumStr) - 1; + rowNum = parseInt(rowNumStr) - 1; } else { rowNum = nextRowNum; } @@ -284,7 +284,7 @@ public class XSSFSheetXMLHandler extends DefaultHandler { XSSFCellStyle style = null; if (stylesTable != null) { if (cellStyleStr != null) { - int styleIndex = Integer.parseInt(cellStyleStr); + int styleIndex = parseInt(cellStyleStr); style = stylesTable.getStyleAt(styleIndex); } else if (stylesTable.getNumCellStyles() > 0) { style = stylesTable.getStyleAt(0); @@ -392,7 +392,7 @@ public class XSSFSheetXMLHandler extends DefaultHandler { if (this.formatString != null) { try { // Try to use the value as a formattable number - double d = Double.parseDouble(fv); + double d = parseDouble(fv); thisStr = formatter.formatRawCellContents(d, this.formatIndex, this.formatString); } catch (Exception e) { // Formula is a String result not a Numeric one @@ -416,10 +416,10 @@ public class XSSFSheetXMLHandler extends DefaultHandler { break; case SST_STRING: - String sstIndex = value.toString(); - if (sstIndex.length() > 0) { + String sstIndex = value.toString().trim(); + if (!sstIndex.isEmpty()) { try { - int idx = Integer.parseInt(sstIndex); + int idx = parseInt(sstIndex); RichTextString rtss = sharedStringsTable.getItemAt(idx); thisStr = rtss.toString(); } catch (NumberFormatException ex) { @@ -430,10 +430,10 @@ public class XSSFSheetXMLHandler extends DefaultHandler { case NUMBER: String n = value.toString(); - if (this.formatString != null && n.length() > 0) { + if (this.formatString != null && !n.isEmpty()) { try { thisStr = formatter.formatRawCellContents( - Double.parseDouble(n), this.formatIndex, this.formatString); + parseDouble(n), this.formatIndex, this.formatString); } catch (Exception e) { LOG.atInfo().log( "Error formatting cell '{}' - will use its raw value instead (format '{}')", @@ -515,7 +515,6 @@ public class XSSFSheetXMLHandler extends DefaultHandler { } } - /** * Output an empty-cell comment. */ @@ -524,6 +523,14 @@ public class XSSFSheetXMLHandler extends DefaultHandler { output.cell(cellRef.formatAsString(), null, comment); } + private static int parseInt(String value) throws NumberFormatException { + return Integer.parseInt(value.trim()); + } + + private static double parseDouble(String value) throws NumberFormatException { + return Double.parseDouble(value.trim()); + } + private enum EmptyCellCommentsCheckType { CELL, END_OF_ROW, diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/extractor/XSSFEventBasedExcelExtractor.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/extractor/XSSFEventBasedExcelExtractor.java index 2cf729307f..aabd090432 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/extractor/XSSFEventBasedExcelExtractor.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/extractor/XSSFEventBasedExcelExtractor.java @@ -302,7 +302,7 @@ public class XSSFEventBasedExcelExtractor for (XSSFShape shape : shapes) { if (shape instanceof XSSFSimpleShape) { String sText = ((XSSFSimpleShape) shape).getText(); - if (sText != null && sText.length() > 0) { + if (sText != null && !sText.isEmpty()) { text.append(sText).append('\n'); } } @@ -384,7 +384,7 @@ public class XSSFEventBasedExcelExtractor */ private void appendHeaderFooterText(StringBuilder buffer, String name) { String text = headerFooterMap.get(name); - if (text != null && text.length() > 0) { + if (text != null && !text.isEmpty()) { // this is a naive way of handling the left, center, and right // header and footer delimiters, but it seems to be as good as // the method used by XSSFExcelExtractor diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/extractor/XSSFExcelExtractor.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/extractor/XSSFExcelExtractor.java index da03c669d5..855c5ee3ba 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/extractor/XSSFExcelExtractor.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/extractor/XSSFExcelExtractor.java @@ -192,7 +192,7 @@ public class XSSFExcelExtractor for (XSSFShape shape : drawing.getShapes()){ if (shape instanceof XSSFSimpleShape){ String boxText = ((XSSFSimpleShape)shape).getText(); - if (boxText.length() > 0){ + if (!boxText.isEmpty()){ text.append(boxText); text.append('\n'); } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/model/ThemesTable.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/model/ThemesTable.java index 7bd391a06b..4d6655d5fc 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/model/ThemesTable.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/model/ThemesTable.java @@ -36,32 +36,34 @@ import org.openxmlformats.schemas.drawingml.x2006.main.ThemeDocument; * colors and fonts. */ public class ThemesTable extends POIXMLDocumentPart implements Themes { - public enum ThemeElement { - LT1(0, "Lt1"), - DK1(1,"Dk1"), - LT2(2,"Lt2"), - DK2(3,"Dk2"), - ACCENT1(4,"Accent1"), - ACCENT2(5,"Accent2"), - ACCENT3(6,"Accent3"), - ACCENT4(7,"Accent4"), - ACCENT5(8,"Accent5"), - ACCENT6(9,"Accent6"), - HLINK(10,"Hlink"), - FOLHLINK(11,"FolHlink"), - UNKNOWN(-1,null); - - public static ThemeElement byId(int idx) { - if (idx >= values().length || idx < 0) return UNKNOWN; - return values()[idx]; - } - ThemeElement(int idx, String name) { - this.idx = idx; - this.name = name; - } - public final int idx; - public final String name; - } + public enum ThemeElement { + LT1(0, "Lt1"), + DK1(1, "Dk1"), + LT2(2, "Lt2"), + DK2(3, "Dk2"), + ACCENT1(4, "Accent1"), + ACCENT2(5, "Accent2"), + ACCENT3(6, "Accent3"), + ACCENT4(7, "Accent4"), + ACCENT5(8, "Accent5"), + ACCENT6(9, "Accent6"), + HLINK(10, "Hlink"), + FOLHLINK(11, "FolHlink"), + UNKNOWN(-1, null); + + public static ThemeElement byId(int idx) { + if (idx >= values().length || idx < 0) return UNKNOWN; + return values()[idx]; + } + + ThemeElement(int idx, String name) { + this.idx = idx; + this.name = name; + } + + public final int idx; + public final String name; + } private IndexedColorMap colorMap; private ThemeDocument theme; diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/OpcOutputStream.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/OpcOutputStream.java index 2079746f94..c3fc63eebb 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/OpcOutputStream.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/OpcOutputStream.java @@ -37,7 +37,7 @@ class OpcOutputStream extends DeflaterOutputStream { private final List<Entry> entries = new ArrayList<>(); private final CRC32 crc = new CRC32(); private Entry current; - private int written = 0; + private long written = 0; private boolean finished = false; /** @@ -84,7 +84,7 @@ class OpcOutputStream extends DeflaterOutputStream { } current.size = def.getBytesRead(); - current.compressedSize = Math.toIntExact(def.getBytesWritten()); + current.compressedSize = def.getBytesWritten(); current.crc = crc.getValue(); written += current.compressedSize; @@ -106,7 +106,7 @@ class OpcOutputStream extends DeflaterOutputStream { if(current != null) { closeEntry(); } - int offset = written; + long offset = written; for (Entry entry : entries) { written += spec.writeCEN(entry); } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/SXSSFCell.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/SXSSFCell.java index 4861a09b5d..76c966f8bd 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/SXSSFCell.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/SXSSFCell.java @@ -17,8 +17,6 @@ package org.apache.poi.xssf.streaming; -import java.text.DateFormat; -import java.text.SimpleDateFormat; import java.time.LocalDateTime; import java.util.Calendar; import java.util.Date; @@ -32,6 +30,7 @@ import org.apache.poi.ss.usermodel.CellBase; import org.apache.poi.ss.usermodel.CellStyle; import org.apache.poi.ss.usermodel.CellType; import org.apache.poi.ss.usermodel.Comment; +import org.apache.poi.ss.usermodel.DataFormatter; import org.apache.poi.ss.usermodel.DateUtil; import org.apache.poi.ss.usermodel.FormulaError; import org.apache.poi.ss.usermodel.Hyperlink; @@ -743,11 +742,11 @@ public class SXSSFCell extends CellBase { return getCellFormula(); case NUMERIC: if (DateUtil.isCellDateFormatted(this)) { - DateFormat sdf = new SimpleDateFormat("dd-MMM-yyyy", LocaleUtil.getUserLocale()); - sdf.setTimeZone(LocaleUtil.getUserTimeZone()); - return sdf.format(getDateCellValue()); + DataFormatter df = new DataFormatter(); + df.setUseCachedValuesForFormulaCells(true); + return df.formatCellValue(this); } - return getNumericCellValue() + ""; + return Double.toString(getNumericCellValue()); case STRING: return getRichStringCellValue().toString(); default: @@ -948,7 +947,7 @@ public class SXSSFCell extends CellBase { } } -//COPIED FROM https://svn.apache.org/repos/asf/poi/trunk/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFCell.java since the functions are declared private there +//COPIED FROM XSSFCell.java since the functions are declared private there /** * Used to help format error messages */ diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/SXSSFSheet.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/SXSSFSheet.java index fc5462620e..bdb87f1bad 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/SXSSFSheet.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/SXSSFSheet.java @@ -1814,7 +1814,7 @@ public class SXSSFSheet implements Sheet, OoxmlSheetExtensions { } /** - * Remove a Array Formula from this sheet. All cells contained in the Array Formula range are removed as well + * Remove an Array Formula from this sheet. All cells contained in the Array Formula range are removed as well * * @param cell any cell within Array Formula range * @return the {@link CellRange} of cells affected by this change diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/SheetDataWriter.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/SheetDataWriter.java index 1017686091..dcd8294271 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/SheetDataWriter.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/SheetDataWriter.java @@ -33,8 +33,6 @@ import java.nio.charset.StandardCharsets; import java.util.Iterator; import java.util.PrimitiveIterator; -import org.apache.logging.log4j.Logger; -import org.apache.poi.logging.PoiLogManager; import org.apache.poi.ss.usermodel.Cell; import org.apache.poi.ss.usermodel.CellStyle; import org.apache.poi.ss.usermodel.CellType; @@ -54,7 +52,6 @@ import org.openxmlformats.schemas.spreadsheetml.x2006.main.STCellType; * so that it was renamed to "SheetDataWriter" */ public class SheetDataWriter implements Closeable { - private static final Logger LOG = PoiLogManager.getLogger(SheetDataWriter.class); private final File _fd; protected final Writer _out; @@ -385,7 +382,7 @@ public class SheetDataWriter implements Closeable { * need to be preserved with the xml:space=\"preserve\" attribute */ boolean hasLeadingTrailingSpaces(String str) { - if (str != null && str.length() > 0) { + if (str != null && !str.isEmpty()) { char firstChar = str.charAt(0); char lastChar = str.charAt(str.length() - 1); return Character.isWhitespace(firstChar) || Character.isWhitespace(lastChar) ; @@ -394,7 +391,7 @@ public class SheetDataWriter implements Closeable { } protected void outputEscapedString(String s) throws IOException { - if (s == null || s.length() == 0) { + if (s == null || s.isEmpty()) { return; } @@ -463,7 +460,7 @@ public class SheetDataWriter implements Closeable { try { _out.close(); } finally { - ret = _fd.delete(); + ret = _fd == null || _fd.delete(); } return ret; } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/StreamingSheetWriter.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/StreamingSheetWriter.java index 382eb114dd..1398c57abc 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/StreamingSheetWriter.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/StreamingSheetWriter.java @@ -29,6 +29,7 @@ import java.nio.charset.StandardCharsets; import org.apache.logging.log4j.Logger; import org.apache.poi.logging.PoiLogManager; import org.apache.poi.util.Beta; +import org.apache.poi.util.Removal; /** * Unlike SheetDataWriter, this writer does not create a temporary file, it writes data directly @@ -40,6 +41,11 @@ public class StreamingSheetWriter extends SheetDataWriter { private static final Logger LOG = PoiLogManager.getLogger(StreamingSheetWriter.class); private boolean closed = false; + /** + * @throws IOException always thrown, use the constructor with an OutputStream + * @deprecated use {@link #StreamingSheetWriter(OutputStream)} + */ + @Removal(version = "6.0.0") public StreamingSheetWriter() throws IOException { throw new IllegalStateException("StreamingSheetWriter requires OutputStream"); } @@ -49,11 +55,17 @@ public class StreamingSheetWriter extends SheetDataWriter { LOG.atDebug().log("Preparing SXSSF sheet writer"); } + /** + * @throws IllegalStateException always thrown - not supported + */ @Override public File createTempFile() throws IOException { throw new IllegalStateException("Not supported with StreamingSheetWriter"); } + /** + * @throws IllegalStateException always thrown - not supported + */ @Override public Writer createWriter(File fd) throws IOException { throw new IllegalStateException("Not supported with StreamingSheetWriter"); @@ -75,6 +87,9 @@ public class StreamingSheetWriter extends SheetDataWriter { } } + /** + * @throws IllegalStateException always thrown - not supported + */ @Override public InputStream getWorksheetXMLInputStream() throws IOException { throw new IllegalStateException("Not supported with StreamingSheetWriter"); diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/Zip64Impl.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/Zip64Impl.java index d2e00f56ed..647d94d436 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/Zip64Impl.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/streaming/Zip64Impl.java @@ -46,8 +46,8 @@ class Zip64Impl { final String filename; long crc; long size; - int compressedSize; - int offset; + long compressedSize; + long offset; Entry(String filename) { this.filename = filename; @@ -128,7 +128,7 @@ class Zip64Impl { /** * Write End of central directory record (EOCD) */ - int writeEND(int entriesCount, int offset, int length) throws IOException { + int writeEND(int entriesCount, long offset, long length) throws IOException { written = 0; writeInt(PK0506); // "PK\005\006" writeShort(0); // number of this disk diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/BaseXSSFEvaluationWorkbook.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/BaseXSSFEvaluationWorkbook.java index c21f0593de..c4a4673571 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/BaseXSSFEvaluationWorkbook.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/BaseXSSFEvaluationWorkbook.java @@ -109,7 +109,7 @@ public abstract class BaseXSSFEvaluationWorkbook implements FormulaRenderingWork } catch (NumberFormatException e) {} // Look up an External Link Table for this name - List<ExternalLinksTable> tables = _uBook.getExternalLinksTable(); + List<ExternalLinksTable> tables = _uBook.getExternalLinksTables(); int index = findExternalLinkIndex(bookName, tables); if (index != -1) return index; @@ -126,7 +126,7 @@ public abstract class BaseXSSFEvaluationWorkbook implements FormulaRenderingWork // So, add the missing reference and return // Note - this is really rather nasty... ExternalLinksTable fakeLinkTable = new FakeExternalLinksTable(relBookName); - tables.add(fakeLinkTable); + _uBook.addExternalLinksTable(fakeLinkTable); return tables.size(); // 1 based results, 0 = current workbook } @@ -193,7 +193,7 @@ public abstract class BaseXSSFEvaluationWorkbook implements FormulaRenderingWork if (externalWorkbookNumber > 0) { // External reference - reference is 1 based, link table is 0 based int linkNumber = externalWorkbookNumber - 1; - ExternalLinksTable linkTable = _uBook.getExternalLinksTable().get(linkNumber); + ExternalLinksTable linkTable = _uBook.getExternalLinksTable(linkNumber); for (org.apache.poi.ss.usermodel.Name name : linkTable.getDefinedNames()) { if (name.getNameName().equals(nameName)) { @@ -300,7 +300,7 @@ public abstract class BaseXSSFEvaluationWorkbook implements FormulaRenderingWork if (externalWorkbookNumber > 0) { // External reference - reference is 1 based, link table is 0 based int linkNumber = externalWorkbookNumber - 1; - ExternalLinksTable linkTable = _uBook.getExternalLinksTable().get(linkNumber); + ExternalLinksTable linkTable = _uBook.getExternalLinksTable(linkNumber); workbookName = linkTable.getLinkedFileName(); } else { // Internal reference @@ -428,7 +428,7 @@ public abstract class BaseXSSFEvaluationWorkbook implements FormulaRenderingWork // TODO - no idea if this is right CTDefinedName ctn = _nameRecord.getCTName(); String strVal = ctn.getStringValue(); - return !ctn.getFunction() && strVal != null && strVal.length() > 0; + return !ctn.getFunction() && strVal != null && !strVal.isEmpty(); } @Override diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/BaseXSSFFormulaEvaluator.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/BaseXSSFFormulaEvaluator.java index 3145e3f43c..b5674ada8e 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/BaseXSSFFormulaEvaluator.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/BaseXSSFFormulaEvaluator.java @@ -128,7 +128,7 @@ public abstract class BaseXSSFFormulaEvaluator extends BaseFormulaEvaluator { XSSFWorkbook xssfWorkbook = xssfCell.getSheet().getWorkbook(); XSSFWorkbook externalWorkbook = (XSSFWorkbook) xssfWorkbook.getCreationHelper() .getReferencedWorkbooks().get(externalSheet.getWorkbookName()); - ExternalLinksTable externalLinksTable = xssfWorkbook.getExternalLinksTable().get(area3DPxg.getExternalWorkbookNumber() - 1); + ExternalLinksTable externalLinksTable = xssfWorkbook.getExternalLinksTable(area3DPxg.getExternalWorkbookNumber() - 1); if (externalWorkbook != null && externalLinksTable != null) { int firstSheet = externalWorkbook.getSheetIndex(area3DPxg.getSheetName()); diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFCell.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFCell.java index 20b7a2cbf4..d23375fda5 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFCell.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFCell.java @@ -17,12 +17,12 @@ package org.apache.poi.xssf.usermodel; -import java.text.DateFormat; -import java.text.SimpleDateFormat; import java.time.LocalDateTime; import java.util.Calendar; import java.util.Date; +import org.apache.logging.log4j.Logger; +import org.apache.poi.logging.PoiLogManager; import org.apache.poi.ss.SpreadsheetVersion; import org.apache.poi.ss.formula.FormulaParser; import org.apache.poi.ss.formula.FormulaRenderer; @@ -51,7 +51,6 @@ import org.apache.poi.ss.util.CellUtil; import org.apache.poi.util.Beta; import org.apache.poi.util.ExceptionUtil; import org.apache.poi.util.Internal; -import org.apache.poi.util.LocaleUtil; import org.apache.poi.xssf.model.CalculationChain; import org.apache.poi.xssf.model.SharedStringsTable; import org.apache.poi.xssf.model.StylesTable; @@ -76,6 +75,7 @@ import org.openxmlformats.schemas.spreadsheetml.x2006.main.STCellType; */ public final class XSSFCell extends CellBase { + private static final Logger LOG = PoiLogManager.getLogger(XSSFCell.class); private static final String FALSE_AS_STRING = "0"; private static final String TRUE_AS_STRING = "1"; private static final String FALSE = "FALSE"; @@ -247,7 +247,7 @@ public final class XSSFCell extends CellBase { return 0.0; } try { - return Double.parseDouble(v); + return parseDouble(v); } catch(NumberFormatException e) { throw typeMismatch(CellType.NUMERIC, CellType.STRING, false); } @@ -333,12 +333,13 @@ public final class XSSFCell extends CellBase { } else { if (_cell.isSetV()) { try { - int idx = Integer.parseInt(_cell.getV()); + int idx = parseInt(_cell.getV()); rt = (XSSFRichTextString)_sharedStringSource.getItemAt(idx); } catch (Throwable t) { if (ExceptionUtil.isFatal(t)) { ExceptionUtil.rethrow(t); } + LOG.atError().withThrowable(t).log("Failed to parse SST index '{}'", _cell.getV()); rt = new XSSFRichTextString(""); } } else { @@ -779,6 +780,7 @@ public final class XSSFCell extends CellBase { return _cell.getV(); } + /** * Get the value of the cell as an error code. * <p> @@ -939,9 +941,9 @@ public final class XSSFCell extends CellBase { switch (getCellType()) { case NUMERIC: if (DateUtil.isCellDateFormatted(this)) { - DateFormat sdf = new SimpleDateFormat("dd-MMM-yyyy", LocaleUtil.getUserLocale()); - sdf.setTimeZone(LocaleUtil.getUserTimeZone()); - return sdf.format(getDateCellValue()); + DataFormatter df = new DataFormatter(); + df.setUseCachedValuesForFormulaCells(true); + return df.formatCellValue(this); } return Double.toString(getNumericCellValue()); case STRING: @@ -1124,12 +1126,12 @@ public final class XSSFCell extends CellBase { case BOOLEAN: return TRUE_AS_STRING.equals(_cell.getV()); case STRING: - int sstIndex = Integer.parseInt(_cell.getV()); + int sstIndex = parseInt(_cell.getV()); RichTextString rt = _sharedStringSource.getItemAt(sstIndex); String text = rt.getString(); return Boolean.parseBoolean(text); case NUMERIC: - return Double.parseDouble(_cell.getV()) != 0; + return parseDouble(_cell.getV()) != 0; case ERROR: // fall-through @@ -1151,13 +1153,14 @@ public final class XSSFCell extends CellBase { return TRUE_AS_STRING.equals(_cell.getV()) ? TRUE : FALSE; case STRING: try { - int sstIndex = Integer.parseInt(_cell.getV()); + int sstIndex = parseInt(_cell.getV()); RichTextString rt = _sharedStringSource.getItemAt(sstIndex); return rt.getString(); } catch (Throwable t) { if (ExceptionUtil.isFatal(t)) { ExceptionUtil.rethrow(t); } + LOG.atError().withThrowable(t).log("Failed to parse SST index '{}'", _cell.getV()); return ""; } case NUMERIC: @@ -1229,4 +1232,12 @@ public final class XSSFCell extends CellBase { ctCell.setR(r); } + private static int parseInt(String value) throws NumberFormatException { + return Integer.parseInt(value.trim()); + } + + private static double parseDouble(String value) throws NumberFormatException { + return Double.parseDouble(value.trim()); + } + } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFCellStyle.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFCellStyle.java index a9d1c76ad3..3c4252b65e 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFCellStyle.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFCellStyle.java @@ -29,6 +29,7 @@ import org.apache.poi.ss.usermodel.HorizontalAlignment; import org.apache.poi.ss.usermodel.IndexedColors; import org.apache.poi.ss.usermodel.ReadingOrder; import org.apache.poi.ss.usermodel.VerticalAlignment; +import org.apache.poi.ss.util.CellUtil; import org.apache.poi.util.Internal; import org.apache.poi.util.Removal; import org.apache.poi.xssf.model.StylesTable; @@ -202,7 +203,7 @@ public class XSSFCellStyle implements CellStyle, Duplicatable { _font = null; _cellAlignment = null; } else { - throw new IllegalArgumentException("Can only clone from one XSSFCellStyle to another, not between HSSFCellStyle and XSSFCellStyle"); + CellUtil.cloneStyle(source, this, null); } } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFColor.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFColor.java index d7324431ba..849235a11d 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFColor.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFColor.java @@ -33,7 +33,7 @@ public class XSSFColor extends ExtendedColor { /** * @param color The ooxml color object to use - * @param map The IndexedColorMap to use instead of the default one (can be null) + * @param map The IndexedColorMap to use instead of the default one (can be null) * @return null if color is null, new instance otherwise */ public static XSSFColor from(CTColor color, IndexedColorMap map) { @@ -63,6 +63,7 @@ public class XSSFColor extends ExtendedColor { /** * new color with the given indexed color map + * * @param colorMap The IndexedColorMap to use instead of the default one (can be null) */ public XSSFColor(IndexedColorMap colorMap) { @@ -71,6 +72,7 @@ public class XSSFColor extends ExtendedColor { /** * TEST ONLY + * * @param clr awt Color * @param map The IndexedColorMap to use instead of the default one (can be null) */ @@ -80,7 +82,7 @@ public class XSSFColor extends ExtendedColor { } /** - * @param rgb The RGB-byte-values for the Color + * @param rgb The RGB-byte-values for the Color * @param colorMap The IndexedColorMap to use instead of the default one (can be null) */ public XSSFColor(byte[] rgb, IndexedColorMap colorMap) { @@ -98,7 +100,7 @@ public class XSSFColor extends ExtendedColor { /** * @param indexedColor color index (Enum named for default colors) - * @param colorMap The IndexedColorMap to use instead of the default one + * @param colorMap The IndexedColorMap to use instead of the default one */ public XSSFColor(IndexedColors indexedColor, IndexedColorMap colorMap) { this(CTColor.Factory.newInstance(), colorMap); @@ -163,8 +165,9 @@ public class XSSFColor extends ExtendedColor { */ @Override public short getIndex() { - return (short)ctColor.getIndexed(); + return (short) ctColor.getIndexed(); } + /** * @return Indexed ctColor value. Only used for backwards compatibility. References a ctColor in indexedColors. */ @@ -174,82 +177,84 @@ public class XSSFColor extends ExtendedColor { /** * Indexed ctColor value. Only used for backwards compatibility. References a ctColor in indexedColors. + * * @param indexed color index */ public void setIndexed(int indexed) { ctColor.setIndexed(indexed); } - /** - * Standard Red Green Blue ctColor value (RGB). - * If there was an A (Alpha) value, it will be stripped. - */ - @Override - public byte[] getRGB() { - byte[] rgb = getRGBOrARGB(); - if(rgb == null) { - return null; - } - - // Need to trim off the alpha - return rgb.length == 4 ? Arrays.copyOfRange(rgb, 1, 4) : rgb; - } - - /** - * Standard Alpha Red Green Blue ctColor value (ARGB). - */ - @Override - public byte[] getARGB() { - byte[] rgb = getRGBOrARGB(); - if(rgb == null) { - return null; - } - - if(rgb.length == 3) { - // Pad with the default Alpha - byte[] tmp = new byte[4]; - tmp[0] = -1; - System.arraycopy(rgb, 0, tmp, 1, 3); - return tmp; - } else { - return rgb; - } - } - - @Override - protected byte[] getStoredRGB() { - return ctColor.getRgb(); - } - - @Override - protected byte[] getIndexedRGB() { - if (isIndexed()) { - if (indexedColorMap != null) return indexedColorMap.getRGB(getIndex()); - return DefaultIndexedColorMap.getDefaultRGB(getIndex()); - } - return null; - } + /** + * Standard Red Green Blue ctColor value (RGB). + * If there was an A (Alpha) value, it will be stripped. + */ + @Override + public byte[] getRGB() { + byte[] rgb = getRGBOrARGB(); + if (rgb == null) { + return null; + } + + // Need to trim off the alpha + return rgb.length == 4 ? Arrays.copyOfRange(rgb, 1, 4) : rgb; + } /** * Standard Alpha Red Green Blue ctColor value (ARGB). */ - @Override + @Override + public byte[] getARGB() { + byte[] rgb = getRGBOrARGB(); + if (rgb == null) { + return null; + } + + if (rgb.length == 3) { + // Pad with the default Alpha + byte[] tmp = new byte[4]; + tmp[0] = -1; + System.arraycopy(rgb, 0, tmp, 1, 3); + return tmp; + } else { + return rgb; + } + } + + @Override + protected byte[] getStoredRGB() { + return ctColor.getRgb(); + } + + @Override + protected byte[] getIndexedRGB() { + if (isIndexed()) { + if (indexedColorMap != null) return indexedColorMap.getRGB(getIndex()); + return DefaultIndexedColorMap.getDefaultRGB(getIndex()); + } + return null; + } + + /** + * Standard Alpha Red Green Blue ctColor value (ARGB). + */ + @Override public void setRGB(byte[] rgb) { - ctColor.setRgb(rgb); + ctColor.setRgb(rgb); } /** - * Index into the {@code clrScheme} collection, referencing a particular {@code sysClr} or + * Index into the {@code cslrScheme} collection, referencing a particular {@code sysClr} or * {@code srgbClr} value expressed in the Theme part. */ - @Override - public int getTheme() { - return (int)ctColor.getTheme(); + @Override + public int getTheme() { + return (int) ctColor.getTheme(); } /** * Index into the {@code clrScheme} collection, referencing a particular {@code sysClr} or * {@code srgbClr} value expressed in the Theme part. + * * @param theme index */ public void setTheme(int theme) { @@ -354,7 +359,7 @@ public class XSSFColor extends ExtendedColor { * @return the underlying XML bean */ @Internal - public CTColor getCTColor(){ + public CTColor getCTColor() { return ctColor; } @@ -372,11 +377,11 @@ public class XSSFColor extends ExtendedColor { if (color != null && !(color instanceof XSSFColor)) { throw new IllegalArgumentException("Only XSSFColor objects are supported, but had " + color.getClass()); } - return (XSSFColor)color; + return (XSSFColor) color; } @Override - public int hashCode(){ + public int hashCode() { return ctColor.toString().hashCode(); } @@ -387,35 +392,39 @@ public class XSSFColor extends ExtendedColor { } return false; } + private boolean sameARGB(XSSFColor other) { if (isRGB() == other.isRGB()) { return !isRGB() || Arrays.equals(getARGB(), other.getARGB()); } return false; } + private boolean sameTheme(XSSFColor other) { if (isThemed() == other.isThemed()) { return !isThemed() || getTheme() == other.getTheme(); } return false; } + private boolean sameTint(XSSFColor other) { if (hasTint() == other.hasTint()) { return !hasTint() || getTint() == other.getTint(); } return false; } + private boolean sameAuto(XSSFColor other) { return isAuto() == other.isAuto(); } @Override - public boolean equals(Object o){ - if(!(o instanceof XSSFColor)) { + public boolean equals(Object o) { + if (!(o instanceof XSSFColor)) { return false; } - XSSFColor other = (XSSFColor)o; + XSSFColor other = (XSSFColor) o; // Compare each field in ctColor. // Cannot compare ctColor's XML string representation because equivalent diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFName.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFName.java index 1e9047009e..476671a48a 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFName.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFName.java @@ -390,7 +390,7 @@ public final class XSSFName implements Name { */ private static void validateName(String name) { - if (name.length() == 0) { + if (name.isEmpty()) { throw new IllegalArgumentException("Name cannot be blank"); } if (name.length() > 255) { diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFPictureData.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFPictureData.java index 9a2c1d02e1..b3f68f6988 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFPictureData.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFPictureData.java @@ -48,7 +48,8 @@ public class XSSFPictureData extends POIXMLDocumentPart implements PictureData { * @return the max image size allowed for XSSF pictures */ public static int getMaxImageSize() { - return MAX_IMAGE_SIZE; + final int ioMaxSize = IOUtils.getByteArrayMaxOverride(); + return ioMaxSize < 0 ? MAX_IMAGE_SIZE : Math.min(MAX_IMAGE_SIZE, ioMaxSize); } /** diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFRichTextString.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFRichTextString.java index fe3e27b10d..f8c1c54a24 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFRichTextString.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFRichTextString.java @@ -390,7 +390,7 @@ public class XSSFRichTextString implements RichTextString { * Return a copy of the font in use at a particular index. * * @param index The index. - * @return A copy of the font that's currently being applied at that + * @return A copy of the font that's currently being applied at that * index or null if no font is being applied or the * index is out of range. */ @@ -485,7 +485,7 @@ public class XSSFRichTextString implements RichTextString { */ protected static void preserveSpaces(STXstring xs) { String text = xs.getStringValue(); - if (text != null && text.length() > 0) { + if (text != null && !text.isEmpty()) { char firstChar = text.charAt(0); char lastChar = text.charAt(text.length() - 1); if(Character.isWhitespace(firstChar) || Character.isWhitespace(lastChar)) { diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFRow.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFRow.java index 5144729fa3..5e6bd25c46 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFRow.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFRow.java @@ -608,7 +608,7 @@ public class XSSFRow implements Row, Comparable<XSSFRow> { } // remove any remaining illegal references in _rows.cArray - while(_row.getCArray().length > _cells.size()) { + while(_row.sizeOfCArray() > _cells.size()) { _row.removeC(_cells.size()); } } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFSheet.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFSheet.java index 8c3c487db3..59cf488993 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFSheet.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFSheet.java @@ -104,6 +104,7 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx private final XSSFDataValidationHelper dataValidationHelper; private XSSFVMLDrawing xssfvmlDrawing; private CellRangeAddress dimensionOverride; + private double arbitraryExtraWidth = 0.0; /** * Creates new XSSFSheet - called by XSSFWorkbook to create a sheet from scratch. @@ -171,7 +172,7 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx tables.put( rp.getRelationship().getId(), (XSSFTable)p ); } if(p instanceof XSSFPivotTable) { - getWorkbook().getPivotTables().add((XSSFPivotTable) p); + getWorkbook().addPivotTable((XSSFPivotTable) p); } } @@ -498,6 +499,7 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx if (width != -1) { width *= 256; + width += arbitraryExtraWidth; int maxColumnWidth = 255*256; // The maximum column width for an individual cell is 255 characters if (width > maxColumnWidth) { width = maxColumnWidth; @@ -508,6 +510,30 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx } /** + * Set the extra width added to the best-fit column width (default 0.0). + * <p> + * Only applied to auto-sized columns. + * </p> + * @param arbitraryExtraWidth the extra width added to the best-fit column width + * @since 5.4.1 + */ + public void setArbitraryExtraWidth(final double arbitraryExtraWidth) { + this.arbitraryExtraWidth = arbitraryExtraWidth; + } + + /** + * Get the extra width added to the best-fit column width. + * <p> + * Only applied to auto-sized columns. + * </p> + * @return the extra width added to the best-fit column width + * @since 5.4.0 + */ + public double getArbitraryExtraWidth() { + return arbitraryExtraWidth; + } + + /** * Return the sheet's existing drawing, or null if there isn't yet one. * * Use {@link #createDrawingPatriarch()} to get or create @@ -1982,6 +2008,7 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx assert(0 <= index && index < size); if (size > 1) { ctMergeCells.removeMergeCell(index); + ctMergeCells.setCount(ctMergeCells.getCount() - 1); } else { worksheet.unsetMergeCells(); } @@ -2017,6 +2044,7 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx } else { CTMergeCell[] newMergeCellsArray = new CTMergeCell[newMergeCells.size()]; ctMergeCells.setMergeCellArray(newMergeCells.toArray(newMergeCellsArray)); + ctMergeCells.setCount(newMergeCells.size()); } } @@ -2900,7 +2928,6 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx dsv.setZoomScale(scale); } - /** * copyRows rows from srcRows to this sheet starting at destStartRow * @@ -2916,6 +2943,27 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx */ @Beta public void copyRows(List<? extends Row> srcRows, int destStartRow, CellCopyPolicy policy) { + copyRows(srcRows, destStartRow, policy, new CellCopyContext()); + } + + /** + * copyRows rows from srcRows to this sheet starting at destStartRow + * + * Additionally copies merged regions that are completely defined in these + * rows (ie. merged 2 cells on a row to be shifted). + * @param srcRows the rows to copy. Formulas will be offset by the difference + * in the row number of the first row in srcRows and destStartRow (even if srcRows + * are from a different sheet). + * @param destStartRow the row in this sheet to paste the first row of srcRows + * the remainder of srcRows will be pasted below destStartRow per the cell copy policy + * @param policy is the cell copy policy, which can be used to merge the source and destination + * when the source is blank, copy styles only, paste as value, etc + * @param context the context - see {@link CellCopyContext} + * @since POI 5.4.1 + */ + @Beta + public void copyRows(List<? extends Row> srcRows, int destStartRow, + CellCopyPolicy policy, CellCopyContext context) { if (srcRows == null || srcRows.isEmpty()) { throw new IllegalArgumentException("No rows to copy"); } @@ -2972,7 +3020,7 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx } //removeRow(destRowNum); //this probably clears all external formula references to destRow, causing unwanted #REF! errors final XSSFRow destRow = createRow(destRowNum); - destRow.copyRowFrom(srcRow, options); + destRow.copyRowFrom(srcRow, options, context); } // ====================== @@ -3008,8 +3056,27 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx */ @Beta public void copyRows(int srcStartRow, int srcEndRow, int destStartRow, CellCopyPolicy cellCopyPolicy) { + copyRows(srcStartRow, srcEndRow, destStartRow, cellCopyPolicy, new CellCopyContext()); + } + + /** + * Copies rows between srcStartRow and srcEndRow to the same sheet, starting at destStartRow + * Convenience function for {@link #copyRows(List, int, CellCopyPolicy, CellCopyContext)} + * + * Equivalent to copyRows(getRows(srcStartRow, srcEndRow, false), destStartRow, cellCopyPolicy) + * + * @param srcStartRow the index of the first row to copy the cells from in this sheet + * @param srcEndRow the index of the last row to copy the cells from in this sheet + * @param destStartRow the index of the first row to copy the cells to in this sheet + * @param cellCopyPolicy the policy to use to determine how cells are copied + * @param context the context - see {@link CellCopyContext} + * @since POI 5.4.1 + */ + @Beta + public void copyRows(int srcStartRow, int srcEndRow, int destStartRow, + CellCopyPolicy cellCopyPolicy, CellCopyContext context) { final List<XSSFRow> srcRows = getRows(srcStartRow, srcEndRow, false); //FIXME: should be false, no need to create rows where src is only to copy them to dest - copyRows(srcRows, destStartRow, cellCopyPolicy); + copyRows(srcRows, destStartRow, cellCopyPolicy, context); } /** @@ -3861,7 +3928,15 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx if(minCell != Integer.MAX_VALUE) { cellRangeAddress = new CellRangeAddress(getFirstRowNum(), getLastRowNum(), minCell, maxCell); } + } else { + // sort columns + for(Map.Entry<Integer, XSSFRow> entry : _rows.entrySet()) { + XSSFRow row = entry.getValue(); + // sorting happens in XSSFRow.fixupCTCells + row.onDocumentWrite(); + } } + if (cellRangeAddress != null) { if (worksheet.isSetDimension()) { worksheet.getDimension().setRef(cellRangeAddress.formatAsString()); @@ -4579,7 +4654,7 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx StringBuilder rng = new StringBuilder(); rng.append(c); - if(rng.length() > 0 && r.length() > 0) { + if(rng.length() > 0 && !r.isEmpty()) { rng.append(','); } rng.append(r); @@ -4630,13 +4705,12 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx @Beta private XSSFPivotTable createPivotTable() { XSSFWorkbook wb = getWorkbook(); - List<XSSFPivotTable> pivotTables = wb.getPivotTables(); int tableId = getWorkbook().getPivotTables().size()+1; //Create relationship between pivotTable and the worksheet XSSFPivotTable pivotTable = (XSSFPivotTable) createRelationship(XSSFRelation.PIVOT_TABLE, getWorkbook().getXssfFactory(), tableId); pivotTable.setParentSheet(this); - pivotTables.add(pivotTable); + wb.addPivotTable(pivotTable); XSSFWorkbook workbook = getWorkbook(); //Create relationship between the pivot cache definition and the workbook @@ -4660,8 +4734,6 @@ public class XSSFSheet extends POIXMLDocumentPart implements Sheet, OoxmlSheetEx //Set relationships id for pivotCacheDefinition to pivotCacheRecords pivotTable.getPivotCacheDefinition().getCTPivotCacheDefinition().setId(pivotCacheDefinition.getRelationId(pivotCacheRecords)); - wb.setPivotTables(pivotTables); - return pivotTable; } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFSimpleShape.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFSimpleShape.java index bc60130c76..a95d3659a3 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFSimpleShape.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFSimpleShape.java @@ -199,7 +199,8 @@ public class XSSFSimpleShape extends XSSFShape implements Iterable<XSSFTextParag } XSSFTextParagraph p = _paragraphs.get(i); - if (p.isBullet() && p.getText().length() > 0) { + final String pText = p.getText(); + if (p.isBullet() && !pText.isEmpty()) { int level = Math.min(p.getLevel(), MAX_LEVELS - 1); @@ -211,11 +212,11 @@ public class XSSFSimpleShape extends XSSFShape implements Iterable<XSSFTextParag out.append('\t'); } String character = p.getBulletCharacter(); - out.append(character.length() > 0 ? character + " " : "- "); - out.append(p.getText()); + out.append(!character.isEmpty() ? character + " " : "- "); + out.append(pText); } } else { - out.append(p.getText()); + out.append(pText); // this paragraph is not a bullet, so reset the count array for (int k = 0; k < MAX_LEVELS; k++) { @@ -254,9 +255,10 @@ public class XSSFSimpleShape extends XSSFShape implements Iterable<XSSFTextParag for (int j = 0; j < level; j++) { out.append('\t'); } - if (p.getText().length() > 0) { + final String pText = p.getText(); + if (!pText.isEmpty()) { out.append(getBulletPrefix(scheme, levelCount.get(level))); - out.append(p.getText()); + out.append(pText); } while (true) { XSSFTextParagraph nextp = (index + 1) == _paragraphs.size() ? null : _paragraphs.get(index + 1); @@ -291,11 +293,12 @@ public class XSSFSimpleShape extends XSSFShape implements Iterable<XSSFTextParag } // check for empty text - only output a bullet if there is text, // but it is still part of the group - if (nextp.getText().length() > 0) { + final String npText = nextp.getText(); + if (!npText.isEmpty()) { // increment the count for this level levelCount.set(level, levelCount.get(level) + 1); out.append(getBulletPrefix(nextScheme, levelCount.get(level))); - out.append(nextp.getText()); + out.append(npText); } } else { // something doesn't match so stop diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFTextParagraph.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFTextParagraph.java index 55e52db3d8..7f81c7dc77 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFTextParagraph.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFTextParagraph.java @@ -19,9 +19,11 @@ package org.apache.poi.xssf.usermodel; import java.awt.Color; import java.util.ArrayList; +import java.util.Collections; import java.util.Iterator; import java.util.List; +import org.apache.poi.ooxml.util.NumberHelper; import org.apache.poi.ooxml.util.POIXMLUnits; import org.apache.poi.util.Internal; import org.apache.poi.util.Units; @@ -64,7 +66,7 @@ public class XSSFTextParagraph implements Iterable<XSSFTextRun>{ } } - public String getText(){ + public String getText() { StringBuilder out = new StringBuilder(); for (XSSFTextRun r : _runs) { out.append(r.getText()); @@ -83,7 +85,7 @@ public class XSSFTextParagraph implements Iterable<XSSFTextRun>{ } public List<XSSFTextRun> getTextRuns(){ - return _runs; + return Collections.unmodifiableList(_runs); } public Iterator<XSSFTextRun> iterator(){ @@ -252,14 +254,30 @@ public class XSSFTextParagraph implements Iterable<XSSFTextRun>{ * @return the color of bullet characters within a given paragraph. * A <code>null</code> value means to use the text font color. */ - public Color getBulletFontColor(){ - ParagraphPropertyFetcher<Color> fetcher = new ParagraphPropertyFetcher<Color>(getLevel()){ + public Color getBulletFontColor() { + byte[] bytes = getBulletFontColorAsBytes(); + if (bytes == null) { + return null; + } else if (bytes.length == 3) { + return new Color(bytes[0] & 0xFF, bytes[1] & 0xFF, bytes[2] & 0xFF); + } else { + return new Color(0xFF & bytes[1], 0xFF & bytes[2], 0xFF & bytes[3], 0xFF & bytes[0]); + } + } + + /** + * + * @return the color of bullet characters within a given paragraph. + * A <code>null</code> value means to use the text font color. + * @since POI 5.5.0 + */ + public byte[] getBulletFontColorAsBytes() { + ParagraphPropertyFetcher<byte[]> fetcher = new ParagraphPropertyFetcher<byte[]>(getLevel()) { public boolean fetch(CTTextParagraphProperties props){ if(props.isSetBuClr()){ if(props.getBuClr().isSetSrgbClr()){ CTSRgbColor clr = props.getBuClr().getSrgbClr(); - byte[] rgb = clr.getVal(); - setValue(new Color(0xFF & rgb[0], 0xFF & rgb[1], 0xFF & rgb[2])); + setValue(clr.getVal()); return true; } } @@ -275,11 +293,21 @@ public class XSSFTextParagraph implements Iterable<XSSFTextRun>{ * * @param color the bullet color */ - public void setBulletFontColor(Color color){ + public void setBulletFontColor(Color color) { + setBulletFontColor(new byte[]{(byte) color.getRed(), (byte) color.getGreen(), (byte) color.getBlue()}); + } + + /** + * Set the color to be used on bullet characters within a given paragraph. + * + * @param colorArray the bullet color (as byte array) + * @since POI 5.5.0 + */ + public void setBulletFontColor(byte[] colorArray) { CTTextParagraphProperties pr = _p.isSetPPr() ? _p.getPPr() : _p.addNewPPr(); CTColor c = pr.isSetBuClr() ? pr.getBuClr() : pr.addNewBuClr(); CTSRgbColor clr = c.isSetSrgbClr() ? c.getSrgbClr() : c.addNewSrgbClr(); - clr.setVal(new byte[]{(byte) color.getRed(), (byte) color.getGreen(), (byte) color.getBlue()}); + clr.setVal(colorArray); } /** @@ -552,8 +580,8 @@ public class XSSFTextParagraph implements Iterable<XSSFTextRun>{ if(lnSpc > 0) { // check if the percentage value is scaled CTTextNormalAutofit normAutofit = _shape.getTxBody().getBodyPr().getNormAutofit(); - if(normAutofit != null) { - double scale = 1 - (double)normAutofit.getLnSpcReduction() / 100000; + if(normAutofit != null && normAutofit.isSetLnSpcReduction()) { + double scale = 1 - NumberHelper.toDouble(normAutofit.getLnSpcReduction()) / 100000; lnSpc *= scale; } } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFTextRun.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFTextRun.java index c525167e90..3789335a16 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFTextRun.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFTextRun.java @@ -16,8 +16,7 @@ ==================================================================== */ package org.apache.poi.xssf.usermodel; -import java.awt.Color; - +import org.apache.poi.ooxml.util.NumberHelper; import org.apache.poi.ooxml.util.POIXMLUnits; import org.apache.poi.util.Units; import org.openxmlformats.schemas.drawingml.x2006.main.CTRegularTextRun; @@ -58,38 +57,53 @@ public class XSSFTextRun { return _r; } - public void setFontColor(Color color){ + public void setFontColor(java.awt.Color color) { + setFontColor(new byte[]{(byte)color.getRed(), (byte)color.getGreen(), (byte)color.getBlue()}); + } + + /** + * @param rgb + * @since POI 5.5.0 + */ + public void setFontColor(byte[] rgb) { CTTextCharacterProperties rPr = getRPr(); CTSolidColorFillProperties fill = rPr.isSetSolidFill() ? rPr.getSolidFill() : rPr.addNewSolidFill(); CTSRgbColor clr = fill.isSetSrgbClr() ? fill.getSrgbClr() : fill.addNewSrgbClr(); - clr.setVal(new byte[]{(byte)color.getRed(), (byte)color.getGreen(), (byte)color.getBlue()}); + clr.setVal(rgb); if(fill.isSetHslClr()) fill.unsetHslClr(); if(fill.isSetPrstClr()) fill.unsetPrstClr(); if(fill.isSetSchemeClr()) fill.unsetSchemeClr(); if(fill.isSetScrgbClr()) fill.unsetScrgbClr(); if(fill.isSetSysClr()) fill.unsetSysClr(); + } + public java.awt.Color getFontColor() { + final byte[] rgb = getFontColorAsBytes(); + if (rgb.length == 3) { + return new java.awt.Color(0xFF & rgb[0], 0xFF & rgb[1], 0xFF & rgb[2]); + } else { + return new java.awt.Color(0xFF & rgb[1], 0xFF & rgb[2], 0xFF & rgb[3], 0xFF & rgb[0]); + } } - public Color getFontColor(){ + /** + * @return the font color as a byte array. + * @since POI 5.5.0 + */ + public byte[] getFontColorAsBytes() { - CTTextCharacterProperties rPr = getRPr(); - if(rPr.isSetSolidFill()){ + CTTextCharacterProperties rPr = getRPrOrNull(); + if (rPr != null && rPr.isSetSolidFill()) { CTSolidColorFillProperties fill = rPr.getSolidFill(); if(fill.isSetSrgbClr()){ CTSRgbColor clr = fill.getSrgbClr(); - byte[] rgb = clr.getVal(); - if (rgb.length == 3) { - return new Color(0xFF & rgb[0], 0xFF & rgb[1], 0xFF & rgb[2]); - } else { - return new Color(0xFF & rgb[1], 0xFF & rgb[2], 0xFF & rgb[3], 0xFF & rgb[0]); - } + return clr.getVal(); } } - return new Color(0, 0, 0); + return new byte[]{0, 0, 0}; } /** @@ -97,7 +111,7 @@ public class XSSFTextRun { * @param fontSize font size in points. * The value of {@code -1} unsets the Sz attribute from the underlying xml bean */ - public void setFontSize(double fontSize){ + public void setFontSize(double fontSize) { CTTextCharacterProperties rPr = getRPr(); if(fontSize == -1.0) { if(rPr.isSetSz()) rPr.unsetSz(); @@ -113,14 +127,16 @@ public class XSSFTextRun { /** * @return font size in points or -1 if font size is not set. */ - public double getFontSize(){ + public double getFontSize() { double scale = 1; double size = XSSFFont.DEFAULT_FONT_SIZE; // default font size CTTextNormalAutofit afit = getParentParagraph().getParentShape().getTxBody().getBodyPr().getNormAutofit(); - if(afit != null) scale = (double)afit.getFontScale() / 100000; + if (afit != null && afit.isSetFontScale()) { + scale = NumberHelper.toDouble(afit.getFontScale()) / 100000; + } - CTTextCharacterProperties rPr = getRPr(); - if(rPr.isSetSz()){ + CTTextCharacterProperties rPr = getRPrOrNull(); + if(rPr != null && rPr.isSetSz()){ size = rPr.getSz()*0.01; } @@ -133,8 +149,8 @@ public class XSSFTextRun { * If this attribute is omitted then a value of 0 or no adjustment is assumed. */ public double getCharacterSpacing(){ - CTTextCharacterProperties rPr = getRPr(); - if(rPr.isSetSpc()){ + CTTextCharacterProperties rPr = getRPrOrNull(); + if(rPr != null && rPr.isSetSpc()){ return Units.toPoints(POIXMLUnits.parseLength(rPr.xgetSpc())); } return 0; @@ -192,19 +208,23 @@ public class XSSFTextRun { * @return font family or null if not set */ public String getFontFamily(){ - CTTextCharacterProperties rPr = getRPr(); - CTTextFont font = rPr.getLatin(); - if(font != null){ - return font.getTypeface(); + CTTextCharacterProperties rPr = getRPrOrNull(); + if (rPr != null) { + CTTextFont font = rPr.getLatin(); + if(font != null) { + return font.getTypeface(); + } } return XSSFFont.DEFAULT_FONT_NAME; } - public byte getPitchAndFamily(){ - CTTextCharacterProperties rPr = getRPr(); - CTTextFont font = rPr.getLatin(); - if(font != null){ - return font.getPitchFamily(); + public byte getPitchAndFamily() { + CTTextCharacterProperties rPr = getRPrOrNull(); + if (rPr != null) { + CTTextFont font = rPr.getLatin(); + if(font != null) { + return font.getPitchFamily(); + } } return 0; } @@ -222,8 +242,8 @@ public class XSSFTextRun { * @return whether a run of text will be formatted as strikethrough text. Default is false. */ public boolean isStrikethrough() { - CTTextCharacterProperties rPr = getRPr(); - if(rPr.isSetStrike()){ + CTTextCharacterProperties rPr = getRPrOrNull(); + if (rPr != null && rPr.isSetStrike()){ return rPr.getStrike() != STTextStrikeType.NO_STRIKE; } return false; @@ -233,8 +253,8 @@ public class XSSFTextRun { * @return whether a run of text will be formatted as a superscript text. Default is false. */ public boolean isSuperscript() { - CTTextCharacterProperties rPr = getRPr(); - if(rPr.isSetBaseline()){ + CTTextCharacterProperties rPr = getRPrOrNull(); + if (rPr != null && rPr.isSetBaseline()){ return POIXMLUnits.parsePercent(rPr.xgetBaseline()) > 0; } return false; @@ -274,8 +294,8 @@ public class XSSFTextRun { * @return whether a run of text will be formatted as a superscript text. Default is false. */ public boolean isSubscript() { - CTTextCharacterProperties rPr = getRPr(); - if(rPr.isSetBaseline()){ + CTTextCharacterProperties rPr = getRPrOrNull(); + if (rPr != null && rPr.isSetBaseline()){ return POIXMLUnits.parsePercent(rPr.xgetBaseline()) < 0; } return false; @@ -285,8 +305,8 @@ public class XSSFTextRun { * @return whether a run of text will be formatted as a superscript text. Default is false. */ public TextCap getTextCap() { - CTTextCharacterProperties rPr = getRPr(); - if(rPr.isSetCap()){ + CTTextCharacterProperties rPr = getRPrOrNull(); + if (rPr != null && rPr.isSetCap()) { return TextCap.values()[rPr.getCap().intValue() - 1]; } return TextCap.NONE; @@ -305,8 +325,8 @@ public class XSSFTextRun { * @return whether this run of text is formatted as bold text */ public boolean isBold(){ - CTTextCharacterProperties rPr = getRPr(); - if(rPr.isSetB()){ + CTTextCharacterProperties rPr = getRPrOrNull(); + if (rPr != null && rPr.isSetB()){ return rPr.getB(); } return false; @@ -323,8 +343,8 @@ public class XSSFTextRun { * @return whether this run of text is formatted as italic text */ public boolean isItalic(){ - CTTextCharacterProperties rPr = getRPr(); - if(rPr.isSetI()){ + CTTextCharacterProperties rPr = getRPrOrNull(); + if (rPr != null && rPr.isSetI()){ return rPr.getI(); } return false; @@ -341,17 +361,21 @@ public class XSSFTextRun { * @return whether this run of text is formatted as underlined text */ public boolean isUnderline(){ - CTTextCharacterProperties rPr = getRPr(); - if(rPr.isSetU()){ + CTTextCharacterProperties rPr = getRPrOrNull(); + if (rPr != null && rPr.isSetU()){ return rPr.getU() != STTextUnderlineType.NONE; } return false; } - protected CTTextCharacterProperties getRPr(){ + protected CTTextCharacterProperties getRPr() { return _r.isSetRPr() ? _r.getRPr() : _r.addNewRPr(); } + private CTTextCharacterProperties getRPrOrNull() { + return _r.isSetRPr() ? _r.getRPr() : null; + } + @Override public String toString(){ return "[" + getClass() + "]" + getText(); diff --git a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java index 0c8ddce4a0..2565b12b9a 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xssf/usermodel/XSSFWorkbook.java @@ -45,6 +45,7 @@ import org.apache.commons.collections4.ListValuedMap; import org.apache.commons.collections4.multimap.ArrayListValuedHashMap; import org.apache.commons.io.output.UnsynchronizedByteArrayOutputStream; import org.apache.logging.log4j.Logger; +import org.apache.poi.POIException; import org.apache.poi.logging.PoiLogManager; import org.apache.poi.hpsf.ClassIDPredefined; import org.apache.poi.ooxml.HyperlinkRelationship; @@ -89,6 +90,7 @@ import org.apache.poi.util.IOUtils; import org.apache.poi.util.Internal; import org.apache.poi.util.NotImplemented; import org.apache.poi.util.Removal; +import org.apache.poi.util.XMLHelper; import org.apache.poi.xssf.XLSBUnsupportedException; import org.apache.poi.xssf.model.CalculationChain; import org.apache.poi.xssf.model.ExternalLinksTable; @@ -110,6 +112,7 @@ import org.openxmlformats.schemas.spreadsheetml.x2006.main.*; public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Support { private static final Pattern COMMA_PATTERN = Pattern.compile(","); private static final Pattern GET_ALL_PICTURES_PATTERN = Pattern.compile("/xl/media/.*?"); + private static final int MAX_NODE_DEPTH = 1000; /** * Images formats supported by XSSF but not by HSSF @@ -205,7 +208,7 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su /** * List of all pivot tables in workbook */ - private List<XSSFPivotTable> pivotTables; + private final List<XSSFPivotTable> pivotTables = new ArrayList<>(); private List<CTPivotCache> pivotCaches; private final XSSFFactory xssfFactory; @@ -386,7 +389,6 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su } // Create arrays for parts attached to the workbook itself - pivotTables = new ArrayList<>(); pivotCaches = new ArrayList<>(); } @@ -397,6 +399,13 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su WorkbookDocument doc = WorkbookDocument.Factory.parse(stream, DEFAULT_XML_OPTIONS); this.workbook = doc.getWorkbook(); } + final int nodeDepth = XMLHelper.getDepthOfChildNodes(this.workbook.getDomNode(), MAX_NODE_DEPTH); + if (nodeDepth > MAX_NODE_DEPTH) { + throw new IOException(String.format(Locale.ROOT, + "The document is too complex, it has a node depth of %s, which exceeds the maximum allowed of %s", + nodeDepth, + MAX_NODE_DEPTH)); + } ThemesTable theme = null; Map<String, XSSFSheet> shIdMap = new HashMap<>(); @@ -477,6 +486,8 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su // Process the named ranges reprocessNamedRanges(); + } catch (POIException e) { + throw new IOException(e); } catch (XmlException e) { throw new POIXMLException(e); } @@ -524,7 +535,6 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su namedRanges = new ArrayList<>(); namedRangesByName = new ArrayListValuedHashMap<>(); sheets = new ArrayList<>(); - pivotTables = new ArrayList<>(); externalLinks = new ArrayList<>(); } @@ -1042,14 +1052,14 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su */ @Override public List<XSSFPictureData> getAllPictures() { - if(pictures == null){ + if (pictures == null) { List<PackagePart> mediaParts = getPackage().getPartsByName(GET_ALL_PICTURES_PATTERN); pictures = new ArrayList<>(mediaParts.size()); for(PackagePart part : mediaParts){ pictures.add(new XSSFPictureData(part)); } } - return pictures; //YK: should return Collections.unmodifiableList(pictures); + return Collections.unmodifiableList(pictures); } /** @@ -2079,11 +2089,46 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su * @return the {@code ExternalLinksTable} list, which may be empty */ @Internal + public List<ExternalLinksTable> getExternalLinksTables() { + // needs to be the live copy because unfortunately we don't have APIs to + // add and remove external links (this method is annotated @Internal) + return externalLinks; + } + + @Deprecated // use getExternalLinksTables() instead + @Removal(version = "7.0.0") + @Internal public List<ExternalLinksTable> getExternalLinksTable() { + // needs to be the live copy because unfortunately we don't have APIs to + // add and remove external links (this method is annotated @Internal) return externalLinks; } /** + * Adds an External Links Table to the workbook. + * + * @param externalLinksTable the External Links Table to add + * @since POI 5.5.0 + */ + @Internal + public void addExternalLinksTable(ExternalLinksTable externalLinksTable) { + if (externalLinks == null) { + externalLinks = new ArrayList<>(); + } + externalLinks.add(externalLinksTable); + } + + /** + * @param index the index at which to add the External Links Table + * @return externalLinksTable the External Links Table to add + * @since POI 5.5.0 + */ + @Internal + public ExternalLinksTable getExternalLinksTable(int index) { + return externalLinks == null ? null : externalLinks.get(index); + } + + /** * * @return a collection of custom XML mappings defined in this workbook */ @@ -2125,7 +2170,7 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su POIXMLDocumentPart.RelationPart rp = this.createRelationship(XSSFRelation.EXTERNAL_LINKS, xssfFactory, externalLinkIdx, false); ExternalLinksTable linksTable = rp.getDocumentPart(); linksTable.setLinkedFileName(name); - this.getExternalLinksTable().add(linksTable); + this.addExternalLinksTable(linksTable); CTExternalReference ctExternalReference = this.getCTWorkbook().addNewExternalReferences().addNewExternalReference(); ctExternalReference.setId(rp.getRelationship().getId()); @@ -2385,7 +2430,7 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su } CTPivotCache cache = caches.addNewPivotCache(); - int tableId = getPivotTables().size()+1; + final int tableId = pivotTables.size() + 1; cache.setCacheId(tableId); cache.setId(rId); if(pivotCaches == null) { @@ -2397,12 +2442,14 @@ public class XSSFWorkbook extends POIXMLDocument implements Workbook, Date1904Su @Beta public List<XSSFPivotTable> getPivotTables() { + // needs to be the live copy because unfortunately we don't have APIs to + // add and remove external links (this method is annotated @Beta) return pivotTables; } - @Beta - protected void setPivotTables(List<XSSFPivotTable> pivotTables) { - this.pivotTables = pivotTables; + @Internal + public void addPivotTable(XSSFPivotTable pivotTable) { + pivotTables.add(pivotTable); } public XSSFWorkbookType getWorkbookType() { diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/extractor/XWPFWordExtractor.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/extractor/XWPFWordExtractor.java index 0673aee02d..3ef53d636a 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/extractor/XWPFWordExtractor.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/extractor/XWPFWordExtractor.java @@ -144,13 +144,13 @@ public class XWPFWordExtractor implements POIXMLTextExtractor { // Add comments XWPFCommentsDecorator decorator = new XWPFCommentsDecorator(paragraph, null); String commentText = decorator.getCommentText(); - if (commentText.length() > 0) { + if (!commentText.isEmpty()) { text.append(commentText).append('\n'); } // Do endnotes and footnotes String footnameText = paragraph.getFootnoteText(); - if (footnameText != null && footnameText.length() > 0) { + if (footnameText != null && !footnameText.isEmpty()) { text.append(footnameText).append('\n'); } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/TableRowAlign.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/TableRowAlign.java index 06653cdb33..fa03dd4998 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/TableRowAlign.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/TableRowAlign.java @@ -26,10 +26,12 @@ import java.util.Map; * Sets alignment values allowed for Tables and Table Rows */ public enum TableRowAlign { - - LEFT(STJcTable.INT_START), + + LEFT(STJcTable.INT_LEFT), + START(STJcTable.INT_START), CENTER(STJcTable.INT_CENTER), - RIGHT(STJcTable.INT_END); + RIGHT(STJcTable.INT_RIGHT), + END(STJcTable.INT_END); private static final Map<Integer, TableRowAlign> imap; diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFAbstractFootnoteEndnote.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFAbstractFootnoteEndnote.java index d924dcfef7..443aa598b9 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFAbstractFootnoteEndnote.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFAbstractFootnoteEndnote.java @@ -18,6 +18,7 @@ package org.apache.poi.xwpf.usermodel; import java.math.BigInteger; import java.util.ArrayList; +import java.util.Collections; import java.util.Iterator; import java.util.List; import java.util.Spliterator; @@ -101,7 +102,7 @@ public abstract class XWPFAbstractFootnoteEndnote implements Iterable<XWPFParag */ @Override public List<XWPFParagraph> getParagraphs() { - return paragraphs; + return Collections.unmodifiableList(paragraphs); } /** @@ -130,7 +131,7 @@ public abstract class XWPFAbstractFootnoteEndnote implements Iterable<XWPFParag */ @Override public List<XWPFTable> getTables() { - return tables; + return Collections.unmodifiableList(tables); } /** @@ -138,7 +139,7 @@ public abstract class XWPFAbstractFootnoteEndnote implements Iterable<XWPFParag * @return List of pictures */ public List<XWPFPictureData> getPictures() { - return pictures; + return Collections.unmodifiableList(pictures); } /** @@ -147,7 +148,7 @@ public abstract class XWPFAbstractFootnoteEndnote implements Iterable<XWPFParag */ @Override public List<IBodyElement> getBodyElements() { - return bodyElements; + return Collections.unmodifiableList(bodyElements); } /** diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFAbstractSDT.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFAbstractSDT.java index 434d857f2c..78ed571886 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFAbstractSDT.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFAbstractSDT.java @@ -30,12 +30,13 @@ public abstract class XWPFAbstractSDT implements ISDTContents { private final String title; private final String tag; private final IBody part; + private final XWPFDocument xwpfDocument; public XWPFAbstractSDT(CTSdtPr pr, IBody part) { title = (pr != null && pr.isSetAlias()) ? pr.getAlias().getVal() : ""; tag = (pr != null && pr.isSetTag()) ? pr.getTag().getVal() : ""; this.part = part; - + this.xwpfDocument = part.getXWPFDocument(); } /** @@ -86,6 +87,6 @@ public abstract class XWPFAbstractSDT implements ISDTContents { } public XWPFDocument getDocument() { - return part.getXWPFDocument(); + return xwpfDocument; } } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFComments.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFComments.java index 1aff90af29..5cbba917eb 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFComments.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFComments.java @@ -25,6 +25,7 @@ import org.apache.poi.openxml4j.exceptions.InvalidFormatException; import org.apache.poi.openxml4j.opc.PackagePart; import org.apache.poi.util.IOUtils; import org.apache.poi.util.Internal; +import org.apache.poi.util.Removal; import org.apache.xmlbeans.XmlException; import org.apache.xmlbeans.XmlOptions; import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTComment; @@ -141,7 +142,10 @@ public class XWPFComments extends POIXMLDocumentPart { * @return the index to this picture (0 based), the added picture can be * obtained from {@link #getAllPictures()} . * @throws InvalidFormatException If the format of the picture is not known. + * @deprecated use {@link #addPictureData(byte[], PictureType)} instead. */ + @Deprecated + @Removal(version = "7.0.0") public String addPictureData(byte[] pictureData, int format) throws InvalidFormatException { return addPictureData(pictureData, PictureType.findByOoxmlId(format)); } @@ -233,7 +237,7 @@ public class XWPFComments extends POIXMLDocumentPart { * Get the list of {@link XWPFComment} in the Comments part. */ public List<XWPFComment> getComments() { - return comments; + return Collections.unmodifiableList(comments); } /** diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFDocument.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFDocument.java index 36d1350d59..56db1b0420 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFDocument.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFDocument.java @@ -23,22 +23,11 @@ import static org.apache.poi.ooxml.POIXMLTypeLoader.DEFAULT_XML_OPTIONS; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; -import java.util.ArrayList; -import java.util.Arrays; -import java.util.Collection; -import java.util.Collections; -import java.util.Deque; -import java.util.HashMap; -import java.util.Iterator; -import java.util.LinkedList; -import java.util.List; -import java.util.Map; -import java.util.NoSuchElementException; -import java.util.Optional; -import java.util.Spliterator; +import java.util.*; import javax.xml.namespace.QName; import org.apache.commons.io.output.UnsynchronizedByteArrayOutputStream; import org.apache.logging.log4j.Logger; +import org.apache.poi.POIException; import org.apache.poi.logging.PoiLogManager; import org.apache.poi.common.usermodel.PictureType; import org.apache.poi.ooxml.POIXMLDocument; @@ -60,6 +49,8 @@ import org.apache.poi.openxml4j.opc.TargetMode; import org.apache.poi.poifs.crypt.HashAlgorithm; import org.apache.poi.util.IOUtils; import org.apache.poi.util.Internal; +import org.apache.poi.util.Removal; +import org.apache.poi.util.XMLHelper; import org.apache.poi.wp.usermodel.HeaderFooterType; import org.apache.poi.xddf.usermodel.chart.XDDFChart; import org.apache.poi.xwpf.model.XWPFHeaderFooterPolicy; @@ -104,6 +95,7 @@ import org.openxmlformats.schemas.wordprocessingml.x2006.main.StylesDocument; @SuppressWarnings("unused") public class XWPFDocument extends POIXMLDocument implements Document, IBody { private static final Logger LOG = PoiLogManager.getLogger(XWPFDocument.class); + private static final int MAX_NODE_DEPTH = 1000; protected List<XWPFFooter> footers = new ArrayList<>(); protected List<XWPFHeader> headers = new ArrayList<>(); @@ -213,6 +205,13 @@ public class XWPFDocument extends POIXMLDocument implements Document, IBody { doc = DocumentDocument.Factory.parse(stream, DEFAULT_XML_OPTIONS); ctDocument = doc.getDocument(); } + final int nodeDepth = XMLHelper.getDepthOfChildNodes(ctDocument.getDomNode(), MAX_NODE_DEPTH); + if (nodeDepth > MAX_NODE_DEPTH) { + throw new IOException(String.format(Locale.ROOT, + "The document is too complex, it has a node depth of %s, which exceeds the maximum allowed of %s", + nodeDepth, + MAX_NODE_DEPTH)); + } initFootnotes(); @@ -303,6 +302,8 @@ public class XWPFDocument extends POIXMLDocument implements Document, IBody { } } initHyperlinks(); + } catch (POIException e) { + throw new IOException(e); } catch (XmlException e) { throw new POIXMLException(e); } @@ -1155,7 +1156,7 @@ public class XWPFDocument extends POIXMLDocument implements Document, IBody { * @return the LastParagraph of the document */ public XWPFParagraph getLastParagraph() { - int lastPos = paragraphs.toArray().length - 1; + final int lastPos = paragraphs.size() - 1; return paragraphs.get(lastPos); } @@ -1724,7 +1725,10 @@ public class XWPFDocument extends POIXMLDocument implements Document, IBody { * @return the next free ImageNumber * @throws InvalidFormatException If the format of the picture is not known. * @see #getNextPicNameNumber(PictureType) + * @deprecated use {@link #getNextPicNameNumber(PictureType)} instead. */ + @Deprecated + @Removal(version = "7.0.0") public int getNextPicNameNumber(int format) throws InvalidFormatException { return getNextPicNameNumber(PictureType.findByOoxmlId(format)); } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFHeaderFooter.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFHeaderFooter.java index 225a8f496e..3c80d26a0a 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFHeaderFooter.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFHeaderFooter.java @@ -31,6 +31,7 @@ import org.apache.poi.openxml4j.exceptions.InvalidFormatException; import org.apache.poi.openxml4j.opc.PackagePart; import org.apache.poi.util.IOUtils; import org.apache.poi.util.Internal; +import org.apache.poi.util.Removal; import org.apache.xmlbeans.XmlCursor; import org.apache.xmlbeans.XmlObject; import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTHdrFtr; @@ -210,7 +211,7 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo * @return a list of {@link XWPFParagraph} */ public List<XWPFParagraph> getListParagraph() { - return paragraphs; + return Collections.unmodifiableList(paragraphs); } public List<XWPFPictureData> getAllPictures() { @@ -235,7 +236,10 @@ public abstract class XWPFHeaderFooter extends POIXMLDocumentPart implements IBo * @return the index to this picture (0 based), the added picture can be obtained from {@link #getAllPictures()} . * @throws InvalidFormatException If the format of the picture is not known. * @see #addPictureData(byte[], PictureType) + * @deprecated Use {@link #addPictureData(byte[], PictureType)} instead. */ + @Deprecated + @Removal(version = "7.0.0") public String addPictureData(byte[] pictureData, int format) throws InvalidFormatException { return addPictureData(pictureData, PictureType.findByOoxmlId(format)); } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFParagraph.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFParagraph.java index 044ce9a400..d572da627e 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFParagraph.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFParagraph.java @@ -58,7 +58,7 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para this.document = part.getXWPFDocument(); if (document == null) { - throw new NullPointerException(); + throw new NullPointerException("null document in XWPFParagraph"); } // Build up the character runs @@ -109,14 +109,13 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para * sub-paragraph that correspond to character text * runs, and builds the appropriate runs for these. */ - @SuppressWarnings("deprecation") private void buildRunsInOrderFromXml(XmlObject object) { try (XmlCursor c = object.newCursor()) { c.selectPath("child::*"); while (c.toNextSelection()) { XmlObject o = c.getObject(); if (o instanceof CTR) { - XWPFRun r = new XWPFRun((CTR) o, this); + XWPFRun r = new XWPFRun((CTR) o, (IRunBody) this); runs.add(r); iruns.add(r); } @@ -145,23 +144,22 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para iruns.add(cc); } if (o instanceof CTRunTrackChange) { - for (CTR r : ((CTRunTrackChange) o).getRArray()) { - XWPFRun cr = new XWPFRun(r, this); + final CTRunTrackChange parentRecord = (CTRunTrackChange) o; + for (CTR r : parentRecord.getRArray()) { + XWPFRun cr = new XWPFRun(r, (IRunBody) this); runs.add(cr); iruns.add(cr); } + // add all the insertions as text + for (CTRunTrackChange change : parentRecord.getInsArray()) { + buildRunsInOrderFromXml(change); + } } if (o instanceof CTSmartTagRun) { // Smart Tags can be nested many times. // This implementation does not preserve the tagging information buildRunsInOrderFromXml(o); } - if (o instanceof CTRunTrackChange) { - // add all the insertions as text - for (CTRunTrackChange change : ((CTRunTrackChange) o).getInsArray()) { - buildRunsInOrderFromXml(change); - } - } } } } @@ -205,7 +203,7 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para if (run instanceof XWPFRun) { XWPFRun xRun = (XWPFRun) run; // don't include the text if reviewing is enabled and this is a deleted run - if (xRun.getCTR().getDelTextArray().length == 0) { + if (xRun.getCTR().sizeOfDelTextArray() == 0) { out.append(xRun); } } else if (run instanceof XWPFSDT) { @@ -484,16 +482,19 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para * Returns the paragraph alignment which shall be applied to text in this * paragraph. * <p> - * If this element is not set on a given paragraph, its value is determined + * If this element is not set on a given paragraph, this function returns + * ParagraphAlignment.LEFT as a placeholder value, and isAlignmentSet() + * returns false. In such case, the alignment value must be determined * by the setting previously set at any level of the style hierarchy (i.e. * that previous setting remains unchanged). If this setting is never * specified in the style hierarchy, then no alignment is applied to the * paragraph. * + * @see #isAlignmentSet() * @return the paragraph alignment of this paragraph. */ public ParagraphAlignment getAlignment() { - CTPPr pr = getCTPPr(); + CTPPr pr = getCTPPr(false); return pr == null || !pr.isSetJc() ? ParagraphAlignment.LEFT : ParagraphAlignment.valueOf(pr.getJc().getVal().intValue()); } @@ -508,13 +509,32 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para * specified in the style hierarchy, then no alignment is applied to the * paragraph. * - * @param align the paragraph alignment to apply to this paragraph. + * @param align the paragraph alignment to apply to this paragraph. It can + * be null to unset it and fall back to the style hierarchy. */ public void setAlignment(ParagraphAlignment align) { - CTPPr pr = getCTPPr(); - CTJc jc = pr.isSetJc() ? pr.getJc() : pr.addNewJc(); - STJc.Enum en = STJc.Enum.forInt(align.getValue()); - jc.setVal(en); + if (align == null) { + CTPPr pr = getCTPPr(false); + if (pr != null) + pr.unsetJc(); + } else { + CTPPr pr = getCTPPr(true); + CTJc jc = pr.isSetJc() ? pr.getJc() : pr.addNewJc(); + STJc.Enum en = STJc.Enum.forInt(align.getValue()); + jc.setVal(en); + } + } + + /** + * Returns true if the paragraph has a paragraph alignment value of its own + * or false in case it should fall back to the alignment value set by the + * paragraph style. + * + * @return boolean + */ + public boolean isAlignmentSet() { + CTPPr pr = getCTPPr(false); + return pr != null && pr.isSetJc(); } /** @@ -550,7 +570,7 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para * @return the vertical alignment of this paragraph. */ public TextAlignment getVerticalAlignment() { - CTPPr pr = getCTPPr(); + CTPPr pr = getCTPPr(false); return (pr == null || !pr.isSetTextAlignment()) ? TextAlignment.AUTO : TextAlignment.valueOf(pr.getTextAlignment().getVal() .intValue()); @@ -866,7 +886,10 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para * @return boolean - if page break is set */ public boolean isPageBreak() { - final CTPPr ppr = getCTPPr(); + final CTPPr ppr = getCTPPr(false); + if (ppr == null) { + return false; + } final CTOnOff ctPageBreak = ppr.isSetPageBreakBefore() ? ppr.getPageBreakBefore() : null; if (ctPageBreak == null) { return false; @@ -1355,7 +1378,8 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para */ @Override public boolean isWordWrapped() { - return getCTPPr().isSetWordWrap() && POIXMLUnits.parseOnOff(getCTPPr().getWordWrap()); + CTPPr ppr = getCTPPr(false); + return ppr != null && ppr.isSetWordWrap() && POIXMLUnits.parseOnOff(ppr.getWordWrap()); } /** @@ -1392,7 +1416,10 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para * @return the style of the paragraph */ public String getStyle() { - CTPPr pr = getCTPPr(); + CTPPr pr = getCTPPr(false); + if (pr == null) { + return null; + } CTString style = pr.isSetPStyle() ? pr.getPStyle() : null; return style != null ? style.getVal() : null; } @@ -1413,7 +1440,10 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para * a new instance. */ private CTPBdr getCTPBrd(boolean create) { - CTPPr pr = getCTPPr(); + CTPPr pr = getCTPPr(create); + if (pr == null) { + return null; + } CTPBdr ct = pr.isSetPBdr() ? pr.getPBdr() : null; if (create && ct == null) { ct = pr.addNewPBdr(); @@ -1426,7 +1456,7 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para * return a new instance. */ private CTSpacing getCTSpacing(boolean create) { - CTPPr pr = getCTPPr(); + CTPPr pr = getCTPPr(create); CTSpacing ct = pr.getSpacing(); if (create && ct == null) { ct = pr.addNewSpacing(); @@ -1439,7 +1469,10 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para * a new instance. */ private CTInd getCTInd(boolean create) { - CTPPr pr = getCTPPr(); + CTPPr pr = getCTPPr(create); + if (pr == null) { + return null; + } CTInd ct = pr.getInd(); if (create && ct == null) { ct = pr.addNewInd(); @@ -1453,8 +1486,18 @@ public class XWPFParagraph implements IBodyElement, IRunBody, ISDTContents, Para */ @Internal public CTPPr getCTPPr() { - return paragraph.getPPr() == null ? paragraph.addNewPPr() - : paragraph.getPPr(); + return getCTPPr(true); + } + + /** + * Get a <b>copy</b> of the currently used CTPPr. If none is used, return + * a new instance when create is true, or null when create is false. + * + * @param create create a new instance if none exists. + */ + private CTPPr getCTPPr(final boolean create) { + return (paragraph.isSetPPr() || !create) ? paragraph.getPPr() + : paragraph.addNewPPr(); } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFPictureData.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFPictureData.java index d74440fcc9..7749977f01 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFPictureData.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFPictureData.java @@ -28,6 +28,7 @@ import org.apache.poi.ooxml.POIXMLRelation; import org.apache.poi.openxml4j.opc.OPCPackage; import org.apache.poi.openxml4j.opc.PackagePart; import org.apache.poi.util.IOUtils; +import org.apache.poi.util.Removal; /** * Raw picture data, normally attached to a WordprocessingML Drawing. @@ -49,7 +50,8 @@ public class XWPFPictureData extends POIXMLDocumentPart { * @return the max image size allowed for XSSF pictures */ public static int getMaxImageSize() { - return MAX_IMAGE_SIZE; + final int ioMaxSize = IOUtils.getByteArrayMaxOverride(); + return ioMaxSize < 0 ? MAX_IMAGE_SIZE : Math.min(MAX_IMAGE_SIZE, ioMaxSize); } /** @@ -151,8 +153,10 @@ public class XWPFPictureData extends POIXMLDocumentPart { * @see org.apache.poi.xwpf.usermodel.Document#PICTURE_TYPE_GIF * @see org.apache.poi.xwpf.usermodel.Document#PICTURE_TYPE_DIB * @see org.apache.poi.xwpf.usermodel.Document#PICTURE_TYPE_SVG - * @see #getPictureTypeEnum() + * @deprecated use #getPictureTypeEnum() */ + @Deprecated + @Removal(version = "7.0.0") // repurpose to return PictureType public int getPictureType() { String contentType = getPackagePart().getContentType(); for (int i = 0; i < RELATIONS.length; i++) { diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFRun.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFRun.java index ca95740fe8..645373e042 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFRun.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFRun.java @@ -26,11 +26,13 @@ import java.math.BigInteger; import java.math.RoundingMode; import java.util.ArrayList; import java.util.Arrays; +import java.util.Collections; import java.util.List; import javax.xml.namespace.QName; import org.apache.poi.common.usermodel.PictureType; +import org.apache.poi.ooxml.POIXMLDocumentPart; import org.apache.poi.ooxml.POIXMLException; import org.apache.poi.ooxml.util.DocumentHelper; import org.apache.poi.ooxml.util.POIXMLUnits; @@ -41,6 +43,7 @@ import org.apache.poi.xssf.usermodel.XSSFRelation; import org.apache.xmlbeans.*; import org.apache.xmlbeans.impl.values.XmlAnyTypeImpl; import org.openxmlformats.schemas.drawingml.x2006.chart.CTChart; +import org.openxmlformats.schemas.drawingml.x2006.chart.CTRelId; import org.openxmlformats.schemas.drawingml.x2006.main.CTBlip; import org.openxmlformats.schemas.drawingml.x2006.main.CTBlipFillProperties; import org.openxmlformats.schemas.drawingml.x2006.main.CTGraphicalObject; @@ -75,6 +78,7 @@ public class XWPFRun implements ISDTContents, IRunElement, CharacterRun { private final String pictureText; private final IRunBody parent; private final List<XWPFPicture> pictures; + private final List<XWPFChart> charts; /** * @param r the CTR bean which holds the run attributes @@ -122,14 +126,25 @@ public class XWPFRun implements ISDTContents, IRunElement, CharacterRun { } pictureText = text.toString(); - // Do we have any embedded pictures? - // (They're a different CTPicture, under the drawingml namespace) + // Do we have any embedded pictures or charts? + // Pictures are a different CTPicture, under the drawingml namespace. + // Charts are relations and use the CTRelId type. pictures = new ArrayList<>(); + charts = new ArrayList<>(); for (XmlObject o : pictTextObjs) { for (CTPicture pict : getCTPictures(o)) { XWPFPicture picture = new XWPFPicture(pict, this); pictures.add(picture); } + XmlObject[] chartRels = o.selectPath("declare namespace c='" + CTChart.type.getName().getNamespaceURI() + "' .//*/c:chart"); + for (XmlObject chartRel : chartRels) { + if (chartRel instanceof CTRelId) { + POIXMLDocumentPart chart = getDocument().getRelationById(((CTRelId) chartRel).getId()); + if (chart instanceof XWPFChart) { + charts.add((XWPFChart) chart); + } + } + } } } @@ -137,6 +152,7 @@ public class XWPFRun implements ISDTContents, IRunElement, CharacterRun { * @deprecated Use {@link XWPFRun#XWPFRun(CTR, IRunBody)} */ @Deprecated + @Removal(version = "7.0.0") public XWPFRun(CTR r, XWPFParagraph p) { this(r, (IRunBody) p); } @@ -148,7 +164,7 @@ public class XWPFRun implements ISDTContents, IRunElement, CharacterRun { */ static void preserveSpaces(XmlString xs) { String text = xs.getStringValue(); - if (text != null && text.length() >= 1 + if (text != null && !text.isEmpty() && (Character.isWhitespace(text.charAt(0)) || Character.isWhitespace(text.charAt(text.length()-1)))) { try (XmlCursor c = xs.newCursor()) { c.toNextToken(); @@ -359,6 +375,16 @@ public class XWPFRun implements ISDTContents, IRunElement, CharacterRun { } /** + * Returns number of text element + * + * @return number of text elements + * @since POI 5.4.1 + */ + public int getNumberOfTexts() { + return run.sizeOfTArray(); + } + + /** * Return the string content of this text run * * @return the text of this text run or {@code null} if not set @@ -523,7 +549,10 @@ public class XWPFRun implements ISDTContents, IRunElement, CharacterRun { * @return The underline, or null create is false and there is no underline. */ private CTUnderline getCTUnderline(boolean create) { - CTRPr pr = getRunProperties(true); + CTRPr pr = getRunProperties(create); + if (pr == null) { + return null; + } return pr.sizeOfUArray() > 0 ? pr.getUArray(0) : (create ? pr.addNewU() : null); } @@ -582,20 +611,21 @@ public class XWPFRun implements ISDTContents, IRunElement, CharacterRun { /** * Get the underline color for the run's underline, if any. * - * @return The RGB color value as as a string of hexadecimal digits (e.g., "A0B2F1") or "auto". + * @return The RGB color value as a string of hexadecimal digits (e.g., "A0B2F1") or "auto". * @since 4.0.0 */ public String getUnderlineColor() { - CTUnderline underline = getCTUnderline(true); - assert(underline != null); String colorName = "auto"; - Object rawValue = underline.getColor(); - if (rawValue != null) { - if (rawValue instanceof String) { - colorName = (String)rawValue; - } else { - byte[] rgbColor = (byte[])rawValue; - colorName = HexDump.toHex(rgbColor[0]) + HexDump.toHex(rgbColor[1]) + HexDump.toHex(rgbColor[2]); + CTUnderline underline = getCTUnderline(false); + if (underline != null) { + Object rawValue = underline.getColor(); + if (rawValue != null) { + if (rawValue instanceof String) { + colorName = (String) rawValue; + } else { + byte[] rgbColor = (byte[]) rawValue; + colorName = HexDump.toHex(rgbColor[0]) + HexDump.toHex(rgbColor[1]) + HexDump.toHex(rgbColor[2]); + } } } return colorName; @@ -1208,8 +1238,10 @@ public class XWPFRun implements ISDTContents, IRunElement, CharacterRun { * @see org.apache.poi.xwpf.usermodel.Document#PICTURE_TYPE_GIF * @see org.apache.poi.xwpf.usermodel.Document#PICTURE_TYPE_DIB * @see org.apache.poi.xwpf.usermodel.Document#PICTURE_TYPE_SVG - * @see #addPicture(InputStream, PictureType, String, int, int) + * @deprecated use #addPicture(InputStream, PictureType, String, int, int) */ + @Deprecated + @Removal(version = "7.0.0") public XWPFPicture addPicture(InputStream pictureData, int pictureType, String filename, int width, int height) throws InvalidFormatException, IOException { return addPicture(pictureData, PictureType.findByOoxmlId(pictureType), filename, width, height); @@ -1343,6 +1375,11 @@ public class XWPFRun implements ISDTContents, IRunElement, CharacterRun { @Internal public CTInline addChart(String chartRelId) throws InvalidFormatException, IOException { try { + POIXMLDocumentPart chart = getDocument().getRelationById(chartRelId); + if (chart instanceof XWPFChart) { + charts.add((XWPFChart) chart); + } + CTInline inline = run.addNewDrawing().addNewInline(); //xml part of chart in document @@ -1384,7 +1421,7 @@ public class XWPFRun implements ISDTContents, IRunElement, CharacterRun { * embedded picture image such as a .png or .jpg */ public List<XWPFPicture> getEmbeddedPictures() { - return pictures; + return Collections.unmodifiableList(pictures); } /** @@ -1424,7 +1461,7 @@ public class XWPFRun implements ISDTContents, IRunElement, CharacterRun { @Override public String toString() { String phonetic = getPhonetic(); - if (phonetic.length() > 0) { + if (!phonetic.isEmpty()) { return text() + " (" + phonetic + ")"; } else { return text(); @@ -1472,7 +1509,7 @@ public class XWPFRun implements ISDTContents, IRunElement, CharacterRun { } } // Any picture text? - if (pictureText != null && pictureText.length() > 0) { + if (pictureText != null && !pictureText.isEmpty()) { text.append("\n").append(pictureText).append("\n"); } } @@ -1802,4 +1839,12 @@ public class XWPFRun implements ISDTContents, IRunElement, CharacterRun { return pr; } + /** + * Returns the charts embedded in the run. + * @return A list of the XWPFChart objects embedded in the run. + * @since POI 5.5.0 + */ + public List<XWPFChart> getEmbeddedCharts() { + return Collections.unmodifiableList(charts); + } } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFSDTCell.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFSDTCell.java index 5589287263..132fa95e11 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFSDTCell.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFSDTCell.java @@ -29,9 +29,11 @@ import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTSdtCell; */ public class XWPFSDTCell extends XWPFAbstractSDT implements ICell { private final XWPFSDTContentCell cellContent; + private final CTSdtCell sdtCell; public XWPFSDTCell(CTSdtCell sdtCell, XWPFTableRow xwpfTableRow, IBody part) { super(sdtCell.getSdtPr(), part); + this.sdtCell = sdtCell; cellContent = new XWPFSDTContentCell(sdtCell.getSdtContent(), xwpfTableRow, part); } @@ -40,4 +42,12 @@ public class XWPFSDTCell extends XWPFAbstractSDT implements ICell { return cellContent; } + /** + * Return the underlying XML bean. + * @return the underlying CTSdtCell bean. + * @since POI 5.5.0 + */ + public CTSdtCell getCTSdtCell() { + return sdtCell; + } } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFSDTContentCell.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFSDTContentCell.java index d43e24fc43..3da8b87b9a 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFSDTContentCell.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFSDTContentCell.java @@ -40,14 +40,19 @@ public class XWPFSDTContentCell implements ISDTContent { //private List<ICell> cells = new ArrayList<ICell>(). - private String text = ""; + private final CTSdtContentCell sdtContentCell; + private String text; public XWPFSDTContentCell(CTSdtContentCell sdtContentCell, XWPFTableRow xwpfTableRow, IBody part) { super(); + this.sdtContentCell = sdtContentCell; + } + + private String extractTextFromSdtContentCell() { //sdtContentCell is allowed to be null: minOccurs="0" maxOccurs="1" if (sdtContentCell == null) { - return; + return ""; } StringBuilder sb = new StringBuilder(); try (final XmlCursor cursor = sdtContentCell.newCursor()) { @@ -87,7 +92,7 @@ public class XWPFSDTContentCell implements ISDTContent { depth--; } } - text = sb.toString(); + return sb.toString(); } } @@ -103,12 +108,25 @@ public class XWPFSDTContentCell implements ISDTContent { return false; } - + @Override public String getText() { + if (text == null) { + text = extractTextFromSdtContentCell(); + } return text; } + @Override public String toString() { return getText(); } + + /** + * Return the underlying XML bean. + * @return the underlying CTSdtContentCell bean. + * @since POI 5.5.0 + */ + public CTSdtContentCell getCTSdtContentCell() { + return sdtContentCell; + } } diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFTable.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFTable.java index 7de3ec20b6..c9fe1cdd1e 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFTable.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFTable.java @@ -284,8 +284,8 @@ public class XWPFTable implements IBodyElement, ISDTContents { * @return width value as an integer */ public int getWidth() { - CTTblPr tblPr = getTblPr(); - return tblPr.isSetTblW() ? (int)Units.toDXA(POIXMLUnits.parseLength(tblPr.getTblW().xgetW())) : -1; + CTTblPr tblPr = getTblPr(false); + return tblPr != null && tblPr.isSetTblW() ? (int)Units.toDXA(POIXMLUnits.parseLength(tblPr.getTblW().xgetW())) : -1; } /** @@ -295,7 +295,7 @@ public class XWPFTable implements IBodyElement, ISDTContents { public void setWidth(int width) { CTTblPr tblPr = getTblPr(); CTTblWidth tblWidth = tblPr.isSetTblW() ? tblPr.getTblW() : tblPr.addNewTblW(); - tblWidth.setW(new BigInteger(Integer.toString(width))); + tblWidth.setW(BigInteger.valueOf(width)); tblWidth.setType(STTblWidth.DXA); } @@ -307,6 +307,80 @@ public class XWPFTable implements IBodyElement, ISDTContents { } /** + * Get the indentation value in 20ths of a point (twips). + * + * <p>This element specifies the indentation which shall be added before the leading edge of + * the current table in the document (the left edge in a left-to-right table, and the right + * edge in a right-to-left table).</p> + * <p>If the table alignment is not left/start, this property shall be ignored.</p> + * + * @see #hasIndent() + * @return indentation value as an integer (20ths of a point) + */ + public int getIndent() { + CTTblPr tblPr = getTblPr(false); + if (tblPr.isSetTblInd()) { + STTblWidth.Enum typeValue = tblPr.getTblInd().getType(); + if (typeValue == null) { + // "§17.4.87: If [type] is omitted, then its value shall be assumed to be dxa" + typeValue = STTblWidth.DXA; + } + switch (typeValue.intValue()) { + case STTblWidth.INT_DXA: + return (int) Units.toDXA(POIXMLUnits.parseLength(tblPr.getTblInd().xgetW())); + case STTblWidth.INT_NIL: + // "§17.18.90: [nil] Specifies that the current width is zero, regardless of + // any width value specified on the parent element" + return 0; + case STTblWidth.INT_PCT: + case STTblWidth.INT_AUTO: + // "§17.4.50: Any width value of type pct or auto for this element shall be ignored" + return 0; + } + } + return 0; + } + + /** + * Set the indentation in 20ths of a point (twips). + * @see #getIndent() + * @param indent Indentation value (20ths of a point) + */ + public void setIndent(int indent) { + CTTblPr tblPr = getTblPr(); + CTTblWidth tblInd = tblPr.isSetTblInd() ? tblPr.getTblInd() : tblPr.addNewTblInd(); + tblInd.setW(BigInteger.valueOf(indent)); + tblInd.setType(STTblWidth.DXA); + } + + /** + * Check if some indentation value is set for the table. + * + * <p>If this attribute is omitted, then the table shall inherit the table indentation from + * the associated table style. If table indentation is never specified in the style hierarchy, + * no indentation shall be added to the parent table.</p> + * + * @return true if the indent value is set and is valid, false if it is not set or shall be + * ignored (e.g. due to invalid type). + */ + public boolean hasIndent() { + CTTblPr tblPr = getTblPr(false); + // According to §17.4.50, values with type pct or auto shall be ignored. + return tblPr.isSetTblInd() && tblPr.getTblInd().getType() != STTblWidth.PCT + && tblPr.getTblInd().getType() != STTblWidth.AUTO; + } + + /** + * Removes the table indentation attribute from a table + */ + public void removeIndent() { + CTTblPr tPr = getTblPr(false); + if (tPr != null && tPr.isSetTblInd()) { + tPr.unsetTblInd(); + } + } + + /** * Returns CTTblPr object for table. Creates it if it does not exist. */ private CTTblPr getTblPr() { @@ -442,7 +516,7 @@ public class XWPFTable implements IBodyElement, ISDTContents { */ public String getStyleID() { String styleId = null; - CTTblPr tblPr = ctTbl.getTblPr(); + CTTblPr tblPr = getTblPr(false); if (tblPr != null) { CTString styleStr = tblPr.getTblStyle(); if (styleStr != null) { @@ -723,8 +797,8 @@ public class XWPFTable implements IBodyElement, ISDTContents { public int getRowBandSize() { int size = 0; - CTTblPr tblPr = getTblPr(); - if (tblPr.isSetTblStyleRowBandSize()) { + CTTblPr tblPr = getTblPr(false); + if (tblPr != null && tblPr.isSetTblStyleRowBandSize()) { CTDecimalNumber rowSize = tblPr.getTblStyleRowBandSize(); size = rowSize.getVal().intValue(); } @@ -739,8 +813,8 @@ public class XWPFTable implements IBodyElement, ISDTContents { public int getColBandSize() { int size = 0; - CTTblPr tblPr = getTblPr(); - if (tblPr.isSetTblStyleColBandSize()) { + CTTblPr tblPr = getTblPr(false); + if (tblPr != null && tblPr.isSetTblStyleColBandSize()) { CTDecimalNumber colSize = tblPr.getTblStyleColBandSize(); size = colSize.getVal().intValue(); } @@ -986,12 +1060,14 @@ public class XWPFTable implements IBodyElement, ISDTContents { } private int getCellMargin(Function<CTTblCellMar,CTTblWidth> margin) { - CTTblPr tblPr = getTblPr(); - CTTblCellMar tcm = tblPr.getTblCellMar(); - if (tcm != null) { - CTTblWidth tw = margin.apply(tcm); - if (tw != null) { - return (int) Units.toDXA(POIXMLUnits.parseLength(tw.xgetW())); + CTTblPr tblPr = getTblPr(false); + if (tblPr != null) { + CTTblCellMar tcm = tblPr.getTblCellMar(); + if (tcm != null) { + CTTblWidth tw = margin.apply(tcm); + if (tw != null) { + return (int) Units.toDXA(POIXMLUnits.parseLength(tw.xgetW())); + } } } return 0; @@ -1141,7 +1217,8 @@ public class XWPFTable implements IBodyElement, ISDTContents { * @since 4.0.0 */ public double getWidthDecimal() { - return getWidthDecimal(getTblPr().getTblW()); + CTTblPr pr = getTblPr(false); + return pr == null ? 0.0 : getWidthDecimal(pr.getTblW()); } /** @@ -1173,11 +1250,12 @@ public class XWPFTable implements IBodyElement, ISDTContents { * A table width can be specified as an absolute measurement (an integer * number of twips), a percentage, or the value "AUTO". * - * @return The width type. + * @return The width type. Returns {@link TableWidthType#NIL} as a default. * @since 4.0.0 */ public TableWidthType getWidthType() { - return getWidthType(getTblPr().getTblW()); + CTTblPr pr = getTblPr(false); + return pr == null ? TableWidthType.NIL : getWidthType(pr.getTblW()); } /** diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFTableCell.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFTableCell.java index f91d9a1d81..6e590e5f9e 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFTableCell.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFTableCell.java @@ -67,6 +67,7 @@ public class XWPFTableCell implements IBody, ICell { } private final CTTc ctTc; + private final XWPFDocument xwpfDocument; protected List<XWPFParagraph> paragraphs; protected List<XWPFTable> tables; protected List<IBodyElement> bodyElements; @@ -78,9 +79,16 @@ public class XWPFTableCell implements IBody, ICell { * If a table cell does not include at least one block-level element, then this document shall be considered corrupt */ public XWPFTableCell(CTTc cell, XWPFTableRow tableRow, IBody part) { + if (cell == null) { + throw new IllegalArgumentException("CTTc cannot be null"); + } + if (tableRow == null) { + throw new IllegalArgumentException("tableRow cannot be null"); + } this.ctTc = cell; this.part = part; this.tableRow = tableRow; + this.xwpfDocument = part == null ? null : part.getXWPFDocument(); bodyElements = new ArrayList<>(); paragraphs = new ArrayList<>(); @@ -524,7 +532,27 @@ public class XWPFTableCell implements IBody, ICell { @Override public XWPFDocument getXWPFDocument() { - return part.getXWPFDocument(); + if (xwpfDocument != null) { + return xwpfDocument; + } else if (part instanceof XWPFTableCell) { + return getCellDocument((XWPFTableCell) part, 0); + } else if (part != null) { + return part.getXWPFDocument(); + } + return null; + } + + private static final int MAX_RECURSION_DEPTH = 1000; + + private static XWPFDocument getCellDocument(XWPFTableCell cell, final int depth) { + if (depth > MAX_RECURSION_DEPTH) { + throw new IllegalStateException("Recursion depth exceeded while trying to get XWPFDocument from XWPFTableCell"); + } + if (cell.part instanceof XWPFTableCell) { + return getCellDocument((XWPFTableCell) cell.part, depth + 1); + } else { + return cell.part.getXWPFDocument(); + } } // Create a map from this XWPF-level enum to the STVerticalJc.Enum values diff --git a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFTableRow.java b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFTableRow.java index f27df6dc24..4b43c0817c 100644 --- a/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFTableRow.java +++ b/poi-ooxml/src/main/java/org/apache/poi/xwpf/usermodel/XWPFTableRow.java @@ -18,6 +18,7 @@ package org.apache.poi.xwpf.usermodel; import java.math.BigInteger; import java.util.ArrayList; +import java.util.Collections; import java.util.List; import org.apache.poi.ooxml.util.POIXMLUnits; @@ -211,7 +212,7 @@ public class XWPFTableRow { this.tableCells = cells; } - return tableCells; + return Collections.unmodifiableList(tableCells); } /** diff --git a/poi-ooxml/src/main/java9/module-info.java b/poi-ooxml/src/main/java9/module-info.java index d740345f59..738f9a8c71 100644 --- a/poi-ooxml/src/main/java9/module-info.java +++ b/poi-ooxml/src/main/java9/module-info.java @@ -95,8 +95,7 @@ module org.apache.poi.ooxml { /* optional dependencies for slideshow rendering via PPTX2PNG */ requires static org.apache.xmlgraphics.batik.anim; requires static org.apache.xmlgraphics.batik.awt.util; - /* this typo appears in Batik 1.18 and will be fixed in a future release */ - requires static org.apache.xmlgraphics.batik.brdige; + requires static org.apache.xmlgraphics.batik.bridge; requires static org.apache.xmlgraphics.batik.codec; requires static org.apache.xmlgraphics.batik.constants; requires static org.apache.xmlgraphics.batik.css; @@ -112,7 +111,7 @@ module org.apache.poi.ooxml { requires static org.apache.xmlgraphics.batik.transcoder; requires static org.apache.xmlgraphics.batik.util; requires static org.apache.xmlgraphics.batik.xml; - requires static xmlgraphics.commons; + requires static org.apache.xmlgraphics.commons; requires static org.apache.pdfbox; requires static org.apache.fontbox; diff --git a/poi-ooxml/src/test/java/org/apache/poi/extractor/ooxml/TestExtractorFactory.java b/poi-ooxml/src/test/java/org/apache/poi/extractor/ooxml/TestExtractorFactory.java index 557752f2ee..acf4881f79 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/extractor/ooxml/TestExtractorFactory.java +++ b/poi-ooxml/src/test/java/org/apache/poi/extractor/ooxml/TestExtractorFactory.java @@ -17,7 +17,6 @@ package org.apache.poi.extractor.ooxml; import static org.apache.poi.POITestCase.assertContains; -import static org.apache.poi.extractor.ExtractorFactory.createExtractor; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertInstanceOf; @@ -26,12 +25,14 @@ import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; +import java.io.ByteArrayInputStream; import java.io.File; import java.io.FileInputStream; import java.io.IOException; import java.util.Locale; import java.util.stream.Stream; +import org.apache.poi.EmptyFileException; import org.apache.poi.POIDataSamples; import org.apache.poi.extractor.ExtractorFactory; import org.apache.poi.extractor.POIOLE2TextExtractor; @@ -142,7 +143,7 @@ class TestExtractorFactory { @ParameterizedTest @MethodSource("testFileData") void testFile(String testcase, File file, String extractor, int count) throws Exception { - try (POITextExtractor ext = createExtractor(file)) { + try (POITextExtractor ext = ExtractorFactory.createExtractor(file)) { assertNotNull(ext); testExtractor(ext, testcase, extractor, count); } @@ -154,7 +155,7 @@ class TestExtractorFactory { // test processing of InputStream try (FileInputStream fis = new FileInputStream(testFile); POIFSFileSystem poifs = new POIFSFileSystem(fis); - POITextExtractor ext = createExtractor(poifs)) { + POITextExtractor ext = ExtractorFactory.createExtractor(poifs)) { assertNotNull(ext); testExtractor(ext, testcase, extractor, count); } @@ -165,7 +166,7 @@ class TestExtractorFactory { void testOOXML(String testcase, File testFile, String extractor, int count) throws Exception { // test processing of InputStream try (FileInputStream fis = new FileInputStream(testFile); - POITextExtractor ext = createExtractor(fis)) { + POITextExtractor ext = ExtractorFactory.createExtractor(fis)) { assertNotNull(ext); testExtractor(ext, testcase, extractor, count); } @@ -187,15 +188,31 @@ class TestExtractorFactory { @Test void testFileInvalid() { //noinspection resource - IOException ex = assertThrows(IOException.class, () -> createExtractor(txt)); - assertEquals("Can't create extractor - unsupported file type: UNKNOWN", ex.getMessage()); + IOException ex = assertThrows(IOException.class, () -> ExtractorFactory.createExtractor(txt)); + assertEquals("Can't create extractor - unsupported file type: UNKNOWN", ex.getMessage(), + "Had: " + ex); } @Test void testInputStreamInvalid() throws IOException { try (FileInputStream fis = new FileInputStream(txt)) { - IOException ex = assertThrows(IOException.class, () -> createExtractor(fis)); - assertTrue(ex.getMessage().contains(FileMagic.UNKNOWN.name())); + IOException ex = assertThrows(IOException.class, () -> ExtractorFactory.createExtractor(fis)); + assertTrue(ex.getMessage().contains(FileMagic.UNKNOWN.name()), "Had: " + ex); + } + } + + @Test + void testInputStreamEmpty() throws IOException { + try (ByteArrayInputStream fis = new ByteArrayInputStream(new byte[0])) { + EmptyFileException ex = assertThrows(EmptyFileException.class, () -> ExtractorFactory.createExtractor(fis)); + } + } + + @Test + void testInputStreamTooShort() throws IOException { + try (ByteArrayInputStream fis = new ByteArrayInputStream(new byte[] { 0 })) { + IOException ex = assertThrows(IOException.class, () -> ExtractorFactory.createExtractor(fis)); + assertTrue(ex.getMessage().contains(FileMagic.UNKNOWN.name()), "Had: " + ex); } } @@ -204,7 +221,8 @@ class TestExtractorFactory { // Not really an Extractor test, but we'll leave it to test POIFS reaction anyway ... //noinspection resource IOException ex = assertThrows(IOException.class, () -> new POIFSFileSystem(txt)); - assertTrue(ex.getMessage().contains("Invalid header signature; read 0x3D20726F68747541, expected 0xE11AB1A1E011CFD0")); + assertTrue(ex.getMessage().contains("Invalid header signature; read 0x3D20726F68747541, expected 0xE11AB1A1E011CFD0"), + "Had: " + ex); } @Test @@ -240,7 +258,7 @@ class TestExtractorFactory { try { // Check we get the right extractors now - try (POITextExtractor extractor = createExtractor(new POIFSFileSystem(new FileInputStream(xls)))) { + try (POITextExtractor extractor = ExtractorFactory.createExtractor(new POIFSFileSystem(new FileInputStream(xls)))) { assertInstanceOf(EventBasedExcelExtractor.class, extractor); assertTrue(extractor.getText().length() > 200); } @@ -259,7 +277,7 @@ class TestExtractorFactory { assertNull(ExtractorFactory.getAllThreadsPreferEventExtractors()); // And back - try (POITextExtractor extractor = createExtractor(new POIFSFileSystem(new FileInputStream(xls)))) { + try (POITextExtractor extractor = ExtractorFactory.createExtractor(new POIFSFileSystem(new FileInputStream(xls)))) { assertInstanceOf(ExcelExtractor.class, extractor); assertTrue(extractor.getText().length() > 200); } @@ -298,7 +316,7 @@ class TestExtractorFactory { void testEmbedded(String format, File file, String expected) throws Exception { int numWord = 0, numXls = 0, numPpt = 0, numMsg = 0, numWordX = 0; - try (final POIOLE2TextExtractor ext = (POIOLE2TextExtractor) createExtractor(file)) { + try (final POIOLE2TextExtractor ext = (POIOLE2TextExtractor) ExtractorFactory.createExtractor(file)) { final POITextExtractor[] embeds = ExtractorFactory.getEmbeddedDocsTextExtractors(ext); for (POITextExtractor embed : embeds) { @@ -470,6 +488,6 @@ class TestExtractorFactory { } private static POITextExtractor ex(String filename) throws IOException { - return createExtractor(ssTests.getFile(filename)); + return ExtractorFactory.createExtractor(ssTests.getFile(filename)); } } diff --git a/poi-ooxml/src/test/java/org/apache/poi/ooxml/TestPOIXMLDocument.java b/poi-ooxml/src/test/java/org/apache/poi/ooxml/TestPOIXMLDocument.java index cc22c41ca9..86672fc7e5 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/ooxml/TestPOIXMLDocument.java +++ b/poi-ooxml/src/test/java/org/apache/poi/ooxml/TestPOIXMLDocument.java @@ -24,7 +24,6 @@ import static org.junit.jupiter.api.Assertions.assertNotNull; import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertSame; import static org.junit.jupiter.api.Assertions.assertThrows; -import static org.junit.jupiter.api.Assertions.assertTrue; import java.io.ByteArrayInputStream; import java.io.File; @@ -136,8 +135,7 @@ public final class TestPOIXMLDocument { // see {@link org.apache.poi.openxml4j.opc.ZipPackage#saveImpl(java.io.OutputStream)} OpenXML4JRuntimeException e = assertThrows(OpenXML4JRuntimeException.class, () -> doc.write(out), "Should not be able to write to an output stream that has been closed."); - assertTrue(e.getMessage().matches("Fail to save: an error occurs while saving the package : " + - "The part .+ failed to be saved in the stream with marshaller .+")); + assertEquals("Failed to save: content types part", e.getMessage()); // Should not be able to write a document that has been closed doc.close(); diff --git a/poi-ooxml/src/test/java/org/apache/poi/openxml4j/opc/compliance/TestOPCComplianceCoreProperties.java b/poi-ooxml/src/test/java/org/apache/poi/openxml4j/opc/compliance/TestOPCComplianceCoreProperties.java index 2079cbd9e1..c2fce80528 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/openxml4j/opc/compliance/TestOPCComplianceCoreProperties.java +++ b/poi-ooxml/src/test/java/org/apache/poi/openxml4j/opc/compliance/TestOPCComplianceCoreProperties.java @@ -38,6 +38,7 @@ import org.apache.commons.io.output.UnsynchronizedByteArrayOutputStream; import org.apache.poi.openxml4j.exceptions.InvalidFormatException; import org.apache.poi.openxml4j.exceptions.InvalidOperationException; import org.apache.poi.openxml4j.opc.ContentTypes; +import org.apache.poi.openxml4j.opc.OPCComplianceFlags; import org.apache.poi.openxml4j.opc.OPCPackage; import org.apache.poi.openxml4j.opc.PackageRelationshipTypes; import org.apache.poi.openxml4j.opc.PackagingURIHelper; @@ -87,17 +88,26 @@ public final class TestOPCComplianceCoreProperties { private static String extractInvalidFormatMessage(String sampleNameSuffix) throws IOException { try (InputStream is = openSampleStream("OPCCompliance_CoreProperties_" + sampleNameSuffix)) { InvalidFormatException e = assertThrows(InvalidFormatException.class, - () -> OPCPackage.open(is).revert(), "expected OPC compliance exception was not thrown"); + () -> OPCPackage.open(is).revert(), "expected OPC compliance exception was not thrown"); return e.getMessage(); } } + private static void testComplianceFlagOverridePreventsException( + String sampleNameSuffix, + OPCComplianceFlags opcComplianceFlags + ) throws IOException { + try (InputStream is = openSampleStream("OPCCompliance_CoreProperties_" + sampleNameSuffix)) { + assertDoesNotThrow(() -> OPCPackage.open(is, opcComplianceFlags).revert(), "Unexpected compliance related exception thrown"); + } + } + /** * Test M4.1 rule. */ @Test void testOnlyOneCorePropertiesPart() throws Exception { - // We have relaxed this check, so we can read the file anyway + // We have relaxed this check, so we can read the file anyway assertDoesNotThrow(() -> { try (InputStream is = openSampleStream("OPCCompliance_CoreProperties_OnlyOneCorePropertiesPartFAIL.docx"); OPCPackage pkg = OPCPackage.open(is)) { @@ -105,21 +115,21 @@ public final class TestOPCComplianceCoreProperties { } }, "M4.1 should be being relaxed"); - // We will use the first core properties, and ignore the others - - try (InputStream is = openSampleStream("MultipleCoreProperties.docx"); - OPCPackage pkg = OPCPackage.open(is)) { - - // We can see 2 by type - assertEquals(2, pkg.getPartsByContentType(ContentTypes.CORE_PROPERTIES_PART).size()); - // But only the first one by relationship - assertEquals(1, pkg.getPartsByRelationshipType(PackageRelationshipTypes.CORE_PROPERTIES).size()); - // It should be core.xml not the older core1.xml - assertEquals( - "/docProps/core.xml", - pkg.getPartsByRelationshipType(PackageRelationshipTypes.CORE_PROPERTIES).get(0).getPartName().toString() - ); - } + // We will use the first core properties, and ignore the others + + try (InputStream is = openSampleStream("MultipleCoreProperties.docx"); + OPCPackage pkg = OPCPackage.open(is)) { + + // We can see 2 by type + assertEquals(2, pkg.getPartsByContentType(ContentTypes.CORE_PROPERTIES_PART).size()); + // But only the first one by relationship + assertEquals(1, pkg.getPartsByRelationshipType(PackageRelationshipTypes.CORE_PROPERTIES).size()); + // It should be core.xml not the older core1.xml + assertEquals( + "/docProps/core.xml", + pkg.getPartsByRelationshipType(PackageRelationshipTypes.CORE_PROPERTIES).get(0).getPartName().toString() + ); + } } private static URI createURI(String text) { @@ -139,8 +149,8 @@ public final class TestOPCComplianceCoreProperties { OPCPackage pkg = OPCPackage.open(is); URI partUri = createURI("/docProps/core2.xml"); InvalidOperationException e = assertThrows(InvalidOperationException.class, () -> - pkg.addRelationship(PackagingURIHelper.createPartName(partUri), TargetMode.INTERNAL, PackageRelationshipTypes.CORE_PROPERTIES), - "expected OPC compliance exception was not thrown" + pkg.addRelationship(PackagingURIHelper.createPartName(partUri), TargetMode.INTERNAL, PackageRelationshipTypes.CORE_PROPERTIES), + "expected OPC compliance exception was not thrown" ); assertEquals("OPC Compliance error [M4.1]: can't add another core properties part ! Use the built-in package method instead.", e.getMessage()); pkg.revert(); @@ -157,8 +167,8 @@ public final class TestOPCComplianceCoreProperties { URI partUri = createURI("/docProps/core2.xml"); InvalidOperationException e = assertThrows(InvalidOperationException.class, () -> - pkg.createPart(PackagingURIHelper.createPartName(partUri), ContentTypes.CORE_PROPERTIES_PART), - "expected OPC compliance exception was not thrown"); + pkg.createPart(PackagingURIHelper.createPartName(partUri), ContentTypes.CORE_PROPERTIES_PART), + "expected OPC compliance exception was not thrown"); assertEquals("OPC Compliance error [M4.1]: you try to add more than one core properties relationship in the package !", e.getMessage()); pkg.revert(); } @@ -211,7 +221,7 @@ public final class TestOPCComplianceCoreProperties { /** * Document with no core properties - testing at the OPC level, - * saving into a new stream + * saving into a new stream */ @Test void testNoCoreProperties_saveNew() throws Exception { @@ -257,7 +267,7 @@ public final class TestOPCComplianceCoreProperties { /** * Document with no core properties - testing at the OPC level, - * from a temp-file, saving in-place + * from a temp-file, saving in-place */ @Test void testNoCoreProperties_saveInPlace() throws Exception { @@ -266,7 +276,7 @@ public final class TestOPCComplianceCoreProperties { // Copy this into a temp file, so we can play with it File tmp = getOutputFile("poi-test.opc"); try (FileOutputStream out = new FileOutputStream(tmp); - InputStream in = openSampleStream(sampleFileName)) { + InputStream in = openSampleStream(sampleFileName)) { IOUtils.copy(in, out); } @@ -295,4 +305,50 @@ public final class TestOPCComplianceCoreProperties { } assertTrue(tmp.delete()); } + + /** + * Test M4.2 rule not enforced when appropriate OPCComplianceFlag is set. + */ + @Test + void testDisableEnforceCompatibilityMarkup() throws IOException { + testComplianceFlagOverridePreventsException( + "DoNotUseCompatibilityMarkupFAIL.docx", + OPCComplianceFlags.enforceAll().setForbidMarkupCompatibilityNamespace(false) + ); + } + + /** + * Test M4.3 and M4.5 rules not enforced when appropriate OPCComplianceFlag is set. + */ + @Test + void testDisableEnforceDublinCoreAndLimitedXSI() throws IOException { + testComplianceFlagOverridePreventsException( + "DCTermsNamespaceLimitedUseFAIL.docx", + OPCComplianceFlags.enforceAll() // This test document violates both M4.3 and M4.5 + .setRestrictXsiTypeAttribute(false) + .setForbidRefiningDublinCoreElements(false) + ); + } + + /** + * Test M4.4 rule not enforced when appropriate OPCComplianceFlag is set. + */ + @Test + void testDisableEnforceUnauthorizedXMLLangAttribute() throws IOException { + testComplianceFlagOverridePreventsException( + "UnauthorizedXMLLangAttributeFAIL.docx", + OPCComplianceFlags.enforceAll().setForbidXmlLangAttribute(false) + ); + } + + /** + * Test M4.5 rule not enforced when appropriate OPCComplianceFlag is set. + */ + @Test + void testDisableEnforceLimitedXSITypeAttribute_NotPresent() throws IOException { + testComplianceFlagOverridePreventsException( + "LimitedXSITypeAttribute_NotPresentFAIL.docx", + OPCComplianceFlags.enforceAll().setRestrictXsiTypeAttribute(false) + ); + } } diff --git a/poi-ooxml/src/test/java/org/apache/poi/poifs/crypt/dsig/TestSignatureInfo.java b/poi-ooxml/src/test/java/org/apache/poi/poifs/crypt/dsig/TestSignatureInfo.java index 241243a93e..d834fd1e87 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/poifs/crypt/dsig/TestSignatureInfo.java +++ b/poi-ooxml/src/test/java/org/apache/poi/poifs/crypt/dsig/TestSignatureInfo.java @@ -41,6 +41,8 @@ import java.net.ConnectException; import java.net.HttpURLConnection; import java.net.MalformedURLException; import java.net.SocketTimeoutException; +import java.net.URI; +import java.net.URISyntaxException; import java.net.URL; import java.security.GeneralSecurityException; import java.security.KeyStoreException; @@ -597,8 +599,8 @@ class TestSignatureInfo { public static String getAccessError(String destinationUrl, boolean fireRequest, int timeout) { URL url; try { - url = new URL(destinationUrl); - } catch (MalformedURLException e) { + url = new URI(destinationUrl).toURL(); + } catch (MalformedURLException | URISyntaxException e) { throw new IllegalArgumentException("Invalid destination URL", e); } diff --git a/poi-ooxml/src/test/java/org/apache/poi/util/tests/TestTempFileThreaded.java b/poi-ooxml/src/test/java/org/apache/poi/util/tests/TestTempFileThreaded.java index 625fa448e4..4110ef456b 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/util/tests/TestTempFileThreaded.java +++ b/poi-ooxml/src/test/java/org/apache/poi/util/tests/TestTempFileThreaded.java @@ -33,6 +33,7 @@ import java.util.Map; import org.apache.poi.ss.usermodel.Cell; import org.apache.poi.ss.usermodel.Row; +import org.apache.poi.util.SuppressForbidden; import org.apache.poi.util.TempFile; import org.apache.poi.util.TempFileCreationStrategy; import org.apache.poi.xssf.streaming.SXSSFSheet; @@ -51,6 +52,7 @@ class TestTempFileThreaded { // the actual thread-safe temp-file strategy private static TempFileCreationStrategy createTempFileCreationStrategy(File poiTempFileDirectory) { return new TempFileCreationStrategy() { + @SuppressForbidden("Thread.getId() is deprecated and replaced with threadId() in JDK 19+") @Override public File createTempFile(String prefix, String suffix) throws IOException { long threadId = Thread.currentThread().getId(); diff --git a/poi-ooxml/src/test/java/org/apache/poi/xddf/usermodel/chart/TestXDDFChartRemoveSeries.java b/poi-ooxml/src/test/java/org/apache/poi/xddf/usermodel/chart/TestXDDFChartRemoveSeries.java index 8bea979e33..5ebd7d13b5 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xddf/usermodel/chart/TestXDDFChartRemoveSeries.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xddf/usermodel/chart/TestXDDFChartRemoveSeries.java @@ -112,21 +112,7 @@ class TestXDDFChartRemoveSeries { } workbook.close(); } - - /** - * Attempt to remove the first series by calling chartData.getSeries().remove(0). - * <p> - * This used to corrupt the workbook but the returned <code>List</code> is unmodifiable. - */ - @Test - void testRemoveSeries0() { - procName = "testRemoveSeries0"; - fileName = procName + ".xlsx"; - - assertThrows(UnsupportedOperationException.class, () -> chartData.getSeries().remove(0)); - assertEquals(2, chartData.getSeriesCount()); - } - + /** * Remove the first series by calling chartData.removeSeries(0). * <p> diff --git a/poi-ooxml/src/test/java/org/apache/poi/xslf/TestXSLFSlideShow.java b/poi-ooxml/src/test/java/org/apache/poi/xslf/TestXSLFSlideShow.java index e66a2bec8d..97dd1c4896 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xslf/TestXSLFSlideShow.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xslf/TestXSLFSlideShow.java @@ -18,6 +18,7 @@ package org.apache.poi.xslf; import java.awt.Color; import java.awt.geom.Rectangle2D; +import java.io.FileOutputStream; import java.io.IOException; import org.apache.poi.POIDataSamples; @@ -25,6 +26,7 @@ import org.apache.poi.ooxml.POIXMLProperties.CoreProperties; import org.apache.poi.openxml4j.exceptions.OpenXML4JException; import org.apache.poi.openxml4j.opc.OPCPackage; import org.apache.poi.openxml4j.opc.PackagePart; +import org.apache.poi.sl.usermodel.AutoNumberingScheme; import org.apache.poi.sl.usermodel.ShapeType; import org.apache.poi.xslf.usermodel.*; import org.apache.xmlbeans.XmlException; @@ -167,4 +169,34 @@ class TestXSLFSlideShow { assertNotEquals(templateTextRunXmlObject, copyTextRunXmlObject); } } + + @Test + void testBulletStyle_DoesNotThrowException() throws IOException { + XMLSlideShow ppt = new XMLSlideShow(); + XSLFSlide slide = ppt.createSlide(); + XSLFAutoShape shape = slide.createAutoShape(); + shape.setAnchor(new Rectangle2D.Double(50., 50., 300., 50.)); + XSLFTextParagraph p = shape.addNewTextParagraph(); + p.addNewTextRun().setText("Text bullet style bug"); + assertDoesNotThrow(() -> p.setBulletStyle(20., Color.RED, "Calibri", AutoNumberingScheme.arabicParenRight)); + ppt.close(); + } + + @Test + void testBulletStyle_setsCorrectValue() throws IOException { + XMLSlideShow ppt = new XMLSlideShow(); + XSLFSlide slide = ppt.createSlide(); + XSLFAutoShape shape = slide.createAutoShape(); + shape.setAnchor(new Rectangle2D.Double(50., 50., 300., 50.)); + XSLFTextParagraph p = shape.addNewTextParagraph(); + p.addNewTextRun().setText("Text bullet style bug"); + double fontSize = 20.; + AutoNumberingScheme scheme = AutoNumberingScheme.arabicParenRight; + + p.setBulletStyle(fontSize, scheme); + + assertEquals(fontSize, p.getBulletFontSize()); + assertEquals(scheme, p.getAutoNumberingScheme()); + ppt.close(); + } } diff --git a/poi-ooxml/src/test/java/org/apache/poi/xslf/usermodel/TestXSLFSlideShowFactory.java b/poi-ooxml/src/test/java/org/apache/poi/xslf/usermodel/TestXSLFSlideShowFactory.java index a51f1838e8..4d29222d9a 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xslf/usermodel/TestXSLFSlideShowFactory.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xslf/usermodel/TestXSLFSlideShowFactory.java @@ -42,7 +42,9 @@ import org.apache.poi.util.IOUtils; import org.apache.poi.util.TempFile; import org.apache.poi.xssf.XSSFTestDataSamples; import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.parallel.Isolated; +@Isolated // testFactoryFromFile() changes sample-files, thus should run in isolation until this is removed public final class TestXSLFSlideShowFactory extends BaseTestSlideShowFactory { private static final POIDataSamples _slTests = POIDataSamples.getSlideShowInstance(); private static final String filename = "SampleShow.pptx"; @@ -54,7 +56,7 @@ public final class TestXSLFSlideShowFactory extends BaseTestSlideShowFactory { @Test void testFactoryFromFile() { // Remove thrown.* when bug 58779 is resolved - // In the mean time, this function will modify SampleShow.pptx on disk. + // In the meantime, this function will modify SampleShow.pptx on disk. AssertionError ex = assertThrows(AssertionError.class, () -> testFactoryFromFile(filename), "Bug 58779: " + removeExpectedExceptionMsg); assertTrue(ex.getMessage().contains("SampleShow.pptx sample file was modified as a result of closing the slideshow")); @@ -97,7 +99,7 @@ public final class TestXSLFSlideShowFactory extends BaseTestSlideShowFactory { File file = XSSFTestDataSamples.getSampleFile("workbook.xml"); try (FileInputStream fis = new FileInputStream(file)) { try { - SlideShow slideShow = SlideShowFactory.create(fis); + SlideShow<?,?> slideShow = SlideShowFactory.create(fis); if (slideShow != null) slideShow.close(); fail("SlideShowFactory.create should have failed"); } catch (IOException ie) { @@ -105,7 +107,7 @@ public final class TestXSLFSlideShowFactory extends BaseTestSlideShowFactory { } } try { - SlideShow slideShow = SlideShowFactory.create(file); + SlideShow<?,?> slideShow = SlideShowFactory.create(file); if (slideShow != null) slideShow.close(); fail("SlideShowFactory.create should have failed"); } catch (IOException ie) { diff --git a/poi-ooxml/src/test/java/org/apache/poi/xssf/eventusermodel/TestXSSFSheetXMLHandler.java b/poi-ooxml/src/test/java/org/apache/poi/xssf/eventusermodel/TestXSSFSheetXMLHandler.java index b3f1215925..7e5a3071f2 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xssf/eventusermodel/TestXSSFSheetXMLHandler.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xssf/eventusermodel/TestXSSFSheetXMLHandler.java @@ -26,7 +26,9 @@ import org.xml.sax.InputSource; import org.xml.sax.XMLReader; import java.io.InputStream; +import java.util.HashMap; import java.util.Iterator; +import java.util.Map; import static org.junit.jupiter.api.Assertions.assertDoesNotThrow; import static org.junit.jupiter.api.Assertions.assertEquals; @@ -100,4 +102,39 @@ class TestXSSFSheetXMLHandler { } } } + + @Test + void testSstStrayWhitespace() throws Exception { + try (OPCPackage xlsxPackage = OPCPackage.open(_ssTests.openResourceAsStream("bug69769.xlsx"))) { + final XSSFReader reader = new XSSFReader(xlsxPackage); + final Iterator<InputStream> iter = reader.getSheetsData(); + final Map<String, String> cellValues = new HashMap<>(); + + try (InputStream stream = iter.next()) { + final XMLReader sheetParser = XMLHelper.getSaxParserFactory().newSAXParser().getXMLReader(); + + sheetParser.setContentHandler(new XSSFSheetXMLHandler(reader.getStylesTable(), + new ReadOnlySharedStringsTable(xlsxPackage), new SheetContentsHandler() { + @Override + public void startRow(final int rowNum) { + } + + @Override + public void endRow(final int rowNum) { + } + + @Override + public void cell(final String cellReference, final String formattedValue, + final XSSFComment comment) { + cellValues.put(cellReference, formattedValue); + } + }, false)); + + assertDoesNotThrow(() -> sheetParser.parse(new InputSource(stream))); + + assertEquals(4, cellValues.size()); + assertEquals("Mustermann", cellValues.get("B2")); + } + } + } } diff --git a/poi-ooxml/src/test/java/org/apache/poi/xssf/model/TestExternalLinksTable.java b/poi-ooxml/src/test/java/org/apache/poi/xssf/model/TestExternalLinksTable.java index 045a03601b..9677cb0a7f 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xssf/model/TestExternalLinksTable.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xssf/model/TestExternalLinksTable.java @@ -32,18 +32,18 @@ public final class TestExternalLinksTable { @Test void none() throws IOException { try (XSSFWorkbook wb = XSSFTestDataSamples.openSampleWorkbook("SampleSS.xlsx")) { - assertNotNull(wb.getExternalLinksTable()); - assertEquals(0, wb.getExternalLinksTable().size()); + assertNotNull(wb.getExternalLinksTables()); + assertEquals(0, wb.getExternalLinksTables().size()); } } @Test void basicRead() throws IOException { try (XSSFWorkbook wb = XSSFTestDataSamples.openSampleWorkbook("ref-56737.xlsx")) { - assertNotNull(wb.getExternalLinksTable()); - assertEquals(1, wb.getExternalLinksTable().size()); + assertNotNull(wb.getExternalLinksTables()); + assertEquals(1, wb.getExternalLinksTables().size()); - ExternalLinksTable links = wb.getExternalLinksTable().get(0); + ExternalLinksTable links = wb.getExternalLinksTable(0); assertEquals(3, links.getSheetNames().size()); assertEquals(2, links.getDefinedNames().size()); @@ -70,13 +70,13 @@ public final class TestExternalLinksTable { @Test void basicReadWriteRead() throws IOException { try (XSSFWorkbook wb = XSSFTestDataSamples.openSampleWorkbook("ref-56737.xlsx")) { - Name name = wb.getExternalLinksTable().get(0).getDefinedNames().get(1); + Name name = wb.getExternalLinksTable(0).getDefinedNames().get(1); name.setNameName("Testing"); name.setRefersToFormula("$A$1"); XSSFWorkbook wbBack = XSSFTestDataSamples.writeOutAndReadBack(wb); - assertEquals(1, wbBack.getExternalLinksTable().size()); - ExternalLinksTable links = wbBack.getExternalLinksTable().get(0); + assertEquals(1, wbBack.getExternalLinksTables().size()); + ExternalLinksTable links = wbBack.getExternalLinksTable(0); name = links.getDefinedNames().get(0); assertEquals("NR_Global_B2", name.getNameName()); @@ -95,11 +95,11 @@ public final class TestExternalLinksTable { @Test void readWithReferencesToTwoExternalBooks() throws IOException { try (XSSFWorkbook wb = XSSFTestDataSamples.openSampleWorkbook("ref2-56737.xlsx")) { - assertNotNull(wb.getExternalLinksTable()); - assertEquals(2, wb.getExternalLinksTable().size()); + assertNotNull(wb.getExternalLinksTables()); + assertEquals(2, wb.getExternalLinksTables().size()); // Check the first one, links to 56737.xlsx - ExternalLinksTable links = wb.getExternalLinksTable().get(0); + ExternalLinksTable links = wb.getExternalLinksTable(0); assertEquals("56737.xlsx", links.getLinkedFileName()); assertEquals(3, links.getSheetNames().size()); assertEquals(2, links.getDefinedNames().size()); @@ -122,7 +122,7 @@ public final class TestExternalLinksTable { // Check the second one, links to 56737.xls, slightly differently - links = wb.getExternalLinksTable().get(1); + links = wb.getExternalLinksTable(1); assertEquals("56737.xls", links.getLinkedFileName()); assertEquals(2, links.getSheetNames().size()); assertEquals(2, links.getDefinedNames().size()); diff --git a/poi-ooxml/src/test/java/org/apache/poi/xssf/streaming/TestOutOfOrderColumns.java b/poi-ooxml/src/test/java/org/apache/poi/xssf/streaming/TestOutOfOrderColumns.java new file mode 100644 index 0000000000..b7b6e67030 --- /dev/null +++ b/poi-ooxml/src/test/java/org/apache/poi/xssf/streaming/TestOutOfOrderColumns.java @@ -0,0 +1,122 @@ +/*
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ====================================================================
+ */
+
+package org.apache.poi.xssf.streaming;
+
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.IOException;
+import java.io.InputStream;
+
+import org.apache.commons.io.output.UnsynchronizedByteArrayOutputStream;
+import org.apache.poi.ss.usermodel.Row;
+import org.apache.poi.ss.usermodel.Sheet;
+import org.apache.poi.xssf.usermodel.XSSFSheet;
+import org.apache.poi.xssf.usermodel.XSSFWorkbook;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Test creates cells in reverse column order in XSSF and SXSSF and expects
+ * saved files to have fixed the order.
+ *
+ * This is necessary because if columns in the saved file are out of order
+ * Excel will show a repair dialog when opening the file and removing data.
+ */
+public final class TestOutOfOrderColumns {
+
+ @Test
+ void outOfOrderColumnsXSSF() throws IOException {
+ try (
+ XSSFWorkbook wb = new XSSFWorkbook();
+ UnsynchronizedByteArrayOutputStream bos = UnsynchronizedByteArrayOutputStream.builder().get()
+ ) {
+ XSSFSheet sheet = wb.createSheet();
+
+ Row row = sheet.createRow(0);
+ // create cells in reverse order
+ row.createCell(1).setCellValue("def");
+ row.createCell(0).setCellValue("abc");
+
+ wb.write(bos);
+
+ validateOrder(bos.toInputStream());
+ }
+ }
+
+ @Test
+ void outOfOrderColumnsSXSSF() throws IOException {
+ try (
+ SXSSFWorkbook wb = new SXSSFWorkbook();
+ UnsynchronizedByteArrayOutputStream bos = UnsynchronizedByteArrayOutputStream.builder().get()
+ ) {
+ Sheet sheet = wb.createSheet();
+
+ Row row = sheet.createRow(0);
+ // create cells in reverse order
+ row.createCell(1).setCellValue("xyz");
+ row.createCell(0).setCellValue("uvw");
+
+ wb.write(bos);
+
+ validateOrder(bos.toInputStream());
+ }
+ }
+
+ @Test
+ /** this is the problematic case, as XSSF column sorting is skipped when saving with SXSSF. */
+ void mixOfXSSFAndSXSSF() throws IOException {
+ try (
+ XSSFWorkbook wb = new XSSFWorkbook();
+ UnsynchronizedByteArrayOutputStream bos = UnsynchronizedByteArrayOutputStream.builder().get()
+ ) {
+ XSSFSheet sheet = wb.createSheet();
+
+ Row row1 = sheet.createRow(0);
+ // create cells in reverse order
+ row1.createCell(1).setCellValue("def");
+ row1.createCell(0).setCellValue("abc");
+
+ try (SXSSFWorkbook sxssfWorkbook = new SXSSFWorkbook(wb)) {
+ Sheet sSheet = sxssfWorkbook.getSheetAt(0);
+ Row row2 = sSheet.createRow(1);
+ // create cells in reverse order
+ row2.createCell(1).setCellValue("xyz");
+ row2.createCell(0).setCellValue("uvw");
+
+ sxssfWorkbook.write(bos);
+
+ validateOrder(bos.toInputStream());
+ }
+ }
+ }
+
+ private void validateOrder(InputStream is) throws IOException {
+ // test if saved cells are in order
+ try (XSSFWorkbook xssfWorkbook = new XSSFWorkbook(is)) {
+ XSSFSheet xssfSheet = xssfWorkbook.getSheetAt(0);
+
+ Row resultRow = xssfSheet.getRow(0);
+ // POI doesn't show stored order because _cells TreeMap sorts it automatically.
+ // The only way to test is to compare the xml.
+ String s = resultRow.toString();
+ assertTrue(s.matches("(?s).*A1.*B1.*"), "unexpected order: " + s);
+ }
+ }
+
+}
diff --git a/poi-ooxml/src/test/java/org/apache/poi/xssf/streaming/TestSXSSFSheet.java b/poi-ooxml/src/test/java/org/apache/poi/xssf/streaming/TestSXSSFSheet.java index 5ab64a69aa..d0fbea91da 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xssf/streaming/TestSXSSFSheet.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xssf/streaming/TestSXSSFSheet.java @@ -63,6 +63,7 @@ public final class TestSXSSFSheet extends BaseTestXSheet { @Override @Test protected void cloneSheet() { + //noinspection Convert2MethodRef RuntimeException ex = assertThrows(RuntimeException.class, () -> super.cloneSheet()); assertEquals("Not Implemented", ex.getMessage()); } @@ -70,6 +71,7 @@ public final class TestSXSSFSheet extends BaseTestXSheet { @Override @Test protected void cloneSheetMultipleTimes() { + //noinspection Convert2MethodRef RuntimeException ex = assertThrows(RuntimeException.class, () -> super.cloneSheetMultipleTimes()); assertEquals("Not Implemented", ex.getMessage()); } @@ -80,6 +82,7 @@ public final class TestSXSSFSheet extends BaseTestXSheet { @Override @Test protected void shiftMerged() { + //noinspection Convert2MethodRef RuntimeException ex = assertThrows(RuntimeException.class, () -> super.shiftMerged()); assertEquals("Not Implemented", ex.getMessage()); } @@ -92,6 +95,7 @@ public final class TestSXSSFSheet extends BaseTestXSheet { @Override @Test protected void bug35084() { + //noinspection Convert2MethodRef RuntimeException ex = assertThrows(RuntimeException.class, () -> super.bug35084()); assertEquals("Not Implemented", ex.getMessage()); } diff --git a/poi-ooxml/src/test/java/org/apache/poi/xssf/streaming/TestSheetDataWriter.java b/poi-ooxml/src/test/java/org/apache/poi/xssf/streaming/TestSheetDataWriter.java index a452073f35..239477c352 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xssf/streaming/TestSheetDataWriter.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xssf/streaming/TestSheetDataWriter.java @@ -26,6 +26,7 @@ import static org.junit.jupiter.api.Assertions.assertTrue; import java.io.File; import java.io.FileInputStream; import java.io.IOException; +import java.io.StringWriter; import java.nio.charset.StandardCharsets; import org.apache.poi.util.IOUtils; @@ -69,6 +70,7 @@ public final class TestSheetDataWriter { IOUtils.closeQuietly(writer); } } + @Test void testWriteNewLines() throws IOException { SheetDataWriter writer = new SheetDataWriter(); @@ -84,4 +86,17 @@ public final class TestSheetDataWriter { IOUtils.closeQuietly(writer); } } + + @Test + void testDispose() throws IOException { + SheetDataWriter writer = new SheetDataWriter(); + assertTrue(writer.dispose()); + } + + @Test + void testWriterDispose() throws IOException { + StringWriter sw = new StringWriter(); + SheetDataWriter writer = new SheetDataWriter(sw); + assertTrue(writer.dispose()); + } } diff --git a/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFBugs.java b/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFBugs.java index 5c0940b8be..22a9ec10e2 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFBugs.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFBugs.java @@ -1768,8 +1768,7 @@ public final class TestXSSFBugs extends BaseTestBugzillaIssues { @ParameterizedTest @CsvSource({ - /* Not 0.0 because POI sees date "0" minus one month as invalid date, which is -1! */ - "56688_1.xlsx, -1.0", + "56688_1.xlsx, 0.0", "56688_2.xlsx, #VALUE!", "56688_3.xlsx, #VALUE!", "56688_4.xlsx, date" @@ -3911,6 +3910,34 @@ public final class TestXSSFBugs extends BaseTestBugzillaIssues { } } + @Test + void testBug69769() throws Exception { + final int expectedCount = 3; + try (XSSFWorkbook wb = openSampleWorkbook("bug69769.xlsx")) { + SharedStringsTable sst = wb.getSharedStringSource(); + assertNotNull(sst); + assertEquals(expectedCount, sst.getCount()); + for (int i = 0; i < expectedCount; i++) { + assertNotNull(sst.getItemAt(i)); + } + XSSFSheet ws = wb.getSheetAt(0); + int nRowCount = ws.getLastRowNum(); + DataFormatter df = new DataFormatter(); + for (int r = 0; r <= nRowCount; r++) { + XSSFRow row = ws.getRow(r); + if (row != null) { + for (Cell cell : row) { + String cellValue = df.formatCellValue(cell); + assertNotNull(cellValue, "Cell value should not be null"); + if (cell.getRowIndex() == 1 && cell.getColumnIndex() == 1) { + assertEquals("Mustermann", cellValue); + } + } + } + } + } + } + private static void readByCommonsCompress(File temp_excel_poi) throws IOException { /* read by commons-compress*/ try (ZipFile zipFile = ZipFile.builder().setFile(temp_excel_poi).get()) { diff --git a/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFCellStyle.java b/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFCellStyle.java index 9a48429f0b..3b605f515f 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFCellStyle.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFCellStyle.java @@ -1090,4 +1090,67 @@ class TestXSSFCellStyle { workbook.close(); } + + @Test + void cloneToHSSF() throws IOException { + try ( + XSSFWorkbook xssfWorkbook = new XSSFWorkbook(); + HSSFWorkbook hssfWorkbook = new HSSFWorkbook() + ) { + XSSFCellStyle cellStyle = xssfWorkbook.createCellStyle(); + DataFormat format = xssfWorkbook.createDataFormat(); + + cellStyle.setDataFormat(format.getFormat("###0")); + + cellStyle.setFillBackgroundColor(IndexedColors.DARK_BLUE.getIndex()); + cellStyle.setFillForegroundColor(IndexedColors.DARK_RED.getIndex()); + cellStyle.setFillPattern(FillPatternType.SOLID_FOREGROUND); + + cellStyle.setAlignment(HorizontalAlignment.RIGHT); + cellStyle.setVerticalAlignment(VerticalAlignment.TOP); + + HSSFCellStyle hssfCellStyle = hssfWorkbook.createCellStyle(); + hssfCellStyle.cloneStyleFrom(cellStyle); + + // not everything is cloned by some properties are set + assertEquals(cellStyle.getDataFormat(), hssfCellStyle.getDataFormat()); + assertEquals(IndexedColors.DARK_BLUE.getIndex(), hssfCellStyle.getFillBackgroundColor()); + assertEquals(IndexedColors.DARK_RED.getIndex(), hssfCellStyle.getFillForegroundColor()); + assertEquals(FillPatternType.SOLID_FOREGROUND, hssfCellStyle.getFillPattern()); + assertEquals(HorizontalAlignment.RIGHT, hssfCellStyle.getAlignment()); + assertEquals(VerticalAlignment.TOP, hssfCellStyle.getVerticalAlignment()); + } + } + + @Test + void cloneFromHSSF() throws IOException { + try ( + XSSFWorkbook xssfWorkbook = new XSSFWorkbook(); + HSSFWorkbook hssfWorkbook = new HSSFWorkbook() + ) { + HSSFCellStyle cellStyle = hssfWorkbook.createCellStyle(); + DataFormat format = hssfWorkbook.createDataFormat(); + + cellStyle.setDataFormat(format.getFormat("###0")); + + cellStyle.setFillBackgroundColor(IndexedColors.DARK_BLUE.getIndex()); + cellStyle.setFillForegroundColor(IndexedColors.DARK_RED.getIndex()); + cellStyle.setFillPattern(FillPatternType.SOLID_FOREGROUND); + + cellStyle.setAlignment(HorizontalAlignment.RIGHT); + cellStyle.setVerticalAlignment(VerticalAlignment.TOP); + + XSSFCellStyle xssfCellStyle = xssfWorkbook.createCellStyle(); + xssfCellStyle.cloneStyleFrom(cellStyle); + + // not everything is cloned by some properties are set + assertEquals(cellStyle.getDataFormat(), xssfCellStyle.getDataFormat()); + // assertEquals(IndexedColors.DARK_BLUE.getIndex(), xssfCellStyle.getFillBackgroundColor()); + assertEquals(IndexedColors.DARK_RED.getIndex(), xssfCellStyle.getFillForegroundColor()); + assertEquals(FillPatternType.SOLID_FOREGROUND, xssfCellStyle.getFillPattern()); + assertEquals(HorizontalAlignment.RIGHT, xssfCellStyle.getAlignment()); + assertEquals(VerticalAlignment.TOP, xssfCellStyle.getVerticalAlignment()); + } + } + } diff --git a/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFPictureData.java b/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFPictureData.java index b42aeba053..fa1cb56136 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFPictureData.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFPictureData.java @@ -35,7 +35,7 @@ public final class TestXSSFPictureData { XSSFWorkbook wb = XSSFTestDataSamples.openSampleWorkbook("WithDrawing.xlsx"); List<XSSFPictureData> pictures = wb.getAllPictures(); //wb.getAllPictures() should return the same instance across multiple calls - assertSame(pictures, wb.getAllPictures()); + assertEquals(pictures, wb.getAllPictures()); assertEquals(5, pictures.size()); String[] ext = {"jpeg", "emf", "png", "emf", "wmf"}; diff --git a/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFSheet.java b/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFSheet.java index 762ef821a7..1f5e62fb74 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFSheet.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFSheet.java @@ -241,6 +241,26 @@ public final class TestXSSFSheet extends BaseTestXSheet { } } + @Test + void autoSizeColumnWithArbitraryExtraWidth() throws IOException { + try (XSSFWorkbook workbook = new XSSFWorkbook()) { + XSSFSheet sheet = workbook.createSheet("Sheet 1"); + XSSFCell cell = sheet.createRow(0).createCell(13); + cell.setCellValue("test"); + sheet.autoSizeColumn(13); + final int size1 = sheet.getColumnWidth(13); + + sheet.setArbitraryExtraWidth(10.0); + sheet.autoSizeColumn(13); + final int size2 = sheet.getColumnWidth(13); + + assertEquals(size1 + 10, size2); + + ColumnHelper columnHelper = sheet.getColumnHelper(); + CTCol col = columnHelper.getColumn(13, false); + assertTrue(col.getBestFit()); + } + } @Test void setCellComment() throws IOException { @@ -338,6 +358,7 @@ public final class TestXSSFSheet extends BaseTestXSheet { sheet.removeMergedRegion(1); assertEquals("E5:F6", ctWorksheet.getMergeCells().getMergeCellArray(1).getRef()); assertEquals(2, sheet.getNumMergedRegions()); + assertEquals(2, ctWorksheet.getMergeCells().getCount()); sheet.removeMergedRegion(1); sheet.removeMergedRegion(0); assertEquals(0, sheet.getNumMergedRegions()); @@ -347,11 +368,15 @@ public final class TestXSSFSheet extends BaseTestXSheet { assertEquals(1, sheet.addMergedRegion(region_2)); assertEquals(2, sheet.addMergedRegion(region_3)); assertEquals(3, sheet.addMergedRegion(region_4)); + assertEquals(4, sheet.getNumMergedRegions()); + assertEquals(4, ctWorksheet.getMergeCells().getCount()); // test invalid indexes OOBE Set<Integer> rmIdx = new HashSet<>(Arrays.asList(5, 6)); sheet.removeMergedRegions(rmIdx); rmIdx = new HashSet<>(Arrays.asList(1, 3)); sheet.removeMergedRegions(rmIdx); + assertEquals(2, sheet.getNumMergedRegions()); + assertEquals(2, ctWorksheet.getMergeCells().getCount()); assertEquals("A1:B2", ctWorksheet.getMergeCells().getMergeCellArray(0).getRef()); assertEquals("E5:F6", ctWorksheet.getMergeCells().getMergeCellArray(1).getRef()); } diff --git a/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFTextParagraph.java b/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFTextParagraph.java index ec13f604be..17daaf102c 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFTextParagraph.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFTextParagraph.java @@ -90,6 +90,10 @@ class TestXSSFTextParagraph { text.setBulletFontColor(color); assertEquals(color, text.getBulletFontColor()); + final byte[] colorBytes = new byte[]{(byte) 255, 127, 0}; + text.setBulletFontColor(colorBytes); + assertArrayEquals(colorBytes, text.getBulletFontColorAsBytes()); + assertEquals(100.0, text.getBulletFontSize(), 0.01); text.setBulletFontSize(1.0); assertEquals(1.0, text.getBulletFontSize(), 0.01); @@ -192,4 +196,32 @@ class TestXSSFTextParagraph { new XSSFTextParagraph(text.getXmlObject(), shape.getCTShape()); } } + + @Test + void testXSSFTextParagraph2() throws IOException { + try (XSSFWorkbook wb = new XSSFWorkbook()) { + XSSFSheet sheet = wb.createSheet(); + XSSFDrawing drawing = sheet.createDrawingPatriarch(); + + XSSFTextBox shape = drawing.createTextbox(new XSSFClientAnchor(0, 0, 0, 0, 2, 2, 3, 4)); + XSSFTextRun run = shape.getTextParagraphs().get(0).getTextRuns().get(0); + final byte[] colorBytes = new byte[]{0, (byte) 255, (byte) 255}; + run.setFont("Arial"); + run.setFontColor(colorBytes); + run.setText("Test String"); + + List<XSSFTextParagraph> paras = shape.getTextParagraphs(); + assertEquals(1, paras.size()); + + XSSFTextParagraph text = paras.get(0); + assertEquals("Test String", text.getText()); + + List<XSSFTextRun> runs = text.getTextRuns(); + assertEquals(1, runs.size()); + XSSFTextRun run2 = runs.get(0); + assertEquals(run.getText(), run2.getText()); + assertEquals(run.getFontFamily(), run2.getFontFamily()); + assertArrayEquals(run.getFontColorAsBytes(), run2.getFontColorAsBytes()); + } + } } diff --git a/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFTextRun.java b/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFTextRun.java index 74434b164b..fae3f42274 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFTextRun.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFTextRun.java @@ -45,11 +45,17 @@ class TestXSSFTextRun { assertNotNull(run.getXmlObject()); assertNotNull(run.getRPr()); - assertEquals(new Color(0, 0, 0), run.getFontColor()); + assertArrayEquals(new byte[]{0, 0, 0}, run.getFontColorAsBytes()); + final byte[] colorBytes = new byte[]{0, (byte) 255, (byte) 255}; Color color = new Color(0, 255, 255); run.setFontColor(color); assertEquals(color, run.getFontColor()); + assertArrayEquals(colorBytes, run.getFontColorAsBytes()); + + run.setFontColor(colorBytes); + assertEquals(color, run.getFontColor()); + assertArrayEquals(colorBytes, run.getFontColorAsBytes()); assertEquals(11.0, run.getFontSize(), 0.01); run.setFontSize(12.32); diff --git a/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFWorkbook.java b/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFWorkbook.java index 7926912f6c..19da165b85 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFWorkbook.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xssf/usermodel/TestXSSFWorkbook.java @@ -1391,7 +1391,7 @@ public final class TestXSSFWorkbook extends BaseTestXWorkbook { try( XSSFWorkbook workbook2 = new XSSFWorkbook(bosB.toInputStream()) ) { - CTExternalLink link = workbook2.getExternalLinksTable().get(0).getCTExternalLink(); + CTExternalLink link = workbook2.getExternalLinksTable(0).getCTExternalLink(); CTExternalSheetData sheetData = link.getExternalBook().getSheetDataSet().getSheetDataArray(0); assertEquals(Double.valueOf(sheetData.getRowArray(0).getCellArray(0).getV()), v1); assertEquals(Double.valueOf(sheetData.getRowArray(0).getCellArray(1).getV()), v2); diff --git a/poi-ooxml/src/test/java/org/apache/poi/xwpf/TestXWPFBugs.java b/poi-ooxml/src/test/java/org/apache/poi/xwpf/TestXWPFBugs.java index ecf9d13601..5611064220 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xwpf/TestXWPFBugs.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xwpf/TestXWPFBugs.java @@ -16,10 +16,7 @@ ==================================================================== */ package org.apache.poi.xwpf; -import static org.junit.jupiter.api.Assertions.assertEquals; -import static org.junit.jupiter.api.Assertions.assertNotNull; -import static org.junit.jupiter.api.Assertions.assertThrows; -import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assertions.*; import static org.junit.jupiter.api.Assumptions.assumeTrue; import java.io.File; @@ -31,6 +28,8 @@ import javax.crypto.Cipher; import org.apache.commons.compress.archivers.zip.ZipArchiveEntry; import org.apache.commons.compress.archivers.zip.ZipFile; import org.apache.poi.POIDataSamples; +import org.apache.poi.POIException; +import org.apache.poi.ooxml.POIXMLException; import org.apache.poi.openxml4j.opc.OPCPackage; import org.apache.poi.openxml4j.opc.PackagePart; import org.apache.poi.openxml4j.opc.PackagePartName; @@ -42,14 +41,12 @@ import org.apache.poi.poifs.crypt.HashAlgorithm; import org.apache.poi.poifs.filesystem.Ole10Native; import org.apache.poi.poifs.filesystem.POIFSFileSystem; import org.apache.poi.xwpf.extractor.XWPFWordExtractor; -import org.apache.poi.xwpf.usermodel.XWPFDocument; -import org.apache.poi.xwpf.usermodel.XWPFParagraph; -import org.apache.poi.xwpf.usermodel.XWPFTable; -import org.apache.poi.xwpf.usermodel.XWPFTableCell; +import org.apache.poi.xwpf.usermodel.*; import org.apache.xmlbeans.XmlCursor; import org.apache.xmlbeans.XmlException; import org.junit.jupiter.api.Test; import org.openxmlformats.schemas.wordprocessingml.x2006.main.DocumentDocument; +import org.openxmlformats.schemas.wordprocessingml.x2006.main.STJcTable; class TestXWPFBugs { private static final POIDataSamples samples = POIDataSamples.getDocumentInstance(); @@ -141,11 +138,11 @@ class TestXWPFBugs { void bug59058() throws IOException, XmlException { String[] files = {"bug57031.docx", "bug59058.docx"}; for (String f : files) { - ZipFile zf = new ZipFile(samples.getFile(f)); - ZipArchiveEntry entry = zf.getEntry("word/document.xml"); - DocumentDocument document = DocumentDocument.Factory.parse(zf.getInputStream(entry)); - assertNotNull(document); - zf.close(); + try (ZipFile zf = ZipFile.builder().setFile(samples.getFile(f)).get()) { + ZipArchiveEntry entry = zf.getEntry("word/document.xml"); + DocumentDocument document = DocumentDocument.Factory.parse(zf.getInputStream(entry)); + assertNotNull(document); + } } } @@ -153,11 +150,11 @@ class TestXWPFBugs { void missingXsbs() throws IOException, XmlException { String[] files = {"bib-chernigovka.netdo.ru_download_docs_17459.docx"}; for (String f : files) { - ZipFile zf = new ZipFile(samples.getFile(f)); - ZipArchiveEntry entry = zf.getEntry("word/document.xml"); - DocumentDocument document = DocumentDocument.Factory.parse(zf.getInputStream(entry)); - assertNotNull(document); - zf.close(); + try (ZipFile zf = ZipFile.builder().setFile(samples.getFile(f)).get()) { + ZipArchiveEntry entry = zf.getEntry("word/document.xml"); + DocumentDocument document = DocumentDocument.Factory.parse(zf.getInputStream(entry)); + assertNotNull(document); + } } } @@ -241,4 +238,59 @@ class TestXWPFBugs { XWPFTable xwpfTable = document.insertNewTbl(xmlCursor); xwpfTable.getRow(0).getCell(0).setText("Hello"); } + + @Test + void correctParagraphAlignment() throws IOException { + try (XWPFDocument document = new XWPFDocument(samples.openResourceAsStream("bug-paragraph-alignment.docx"))) { + XWPFParagraph centeredParagraph = document.getParagraphArray(0); + assertFalse(centeredParagraph.isAlignmentSet()); + assertEquals(ParagraphAlignment.LEFT, centeredParagraph.getAlignment()); // LEFT is a fallback value here. + + XWPFParagraph leftParagraph = document.getParagraphArray(1); + assertTrue(leftParagraph.isAlignmentSet()); + assertEquals(ParagraphAlignment.LEFT, leftParagraph.getAlignment()); // LEFT is the real alignment value. + } + } + + @Test + public void testTableRightAlign() throws Exception { + // Document contains all possible values for table alignment, including null. + try (XWPFDocument doc = XWPFTestDataSamples.openSampleDocument("table-alignment.docx")) { + XWPFTable tbl0 = doc.getTableArray(0); + assertNull(tbl0.getTableAlignment()); + assertFalse(tbl0.getCTTbl().getTblPr().isSetJc()); + XWPFTable tbl1 = doc.getTableArray(1); + assertEquals(TableRowAlign.LEFT, tbl1.getTableAlignment()); + assertEquals(STJcTable.LEFT, tbl1.getCTTbl().getTblPr().getJc().xgetVal().getEnumValue()); + XWPFTable tbl2 = doc.getTableArray(2); + assertEquals(TableRowAlign.START, tbl2.getTableAlignment()); + assertEquals(STJcTable.START, tbl2.getCTTbl().getTblPr().getJc().xgetVal().getEnumValue()); + XWPFTable tbl3 = doc.getTableArray(3); + assertEquals(TableRowAlign.CENTER, tbl3.getTableAlignment()); + assertEquals(STJcTable.CENTER, tbl3.getCTTbl().getTblPr().getJc().xgetVal().getEnumValue()); + XWPFTable tbl4 = doc.getTableArray(4); + assertEquals(TableRowAlign.RIGHT, tbl4.getTableAlignment()); + assertEquals(STJcTable.RIGHT, tbl4.getCTTbl().getTblPr().getJc().xgetVal().getEnumValue()); + XWPFTable tbl5 = doc.getTableArray(5); + assertEquals(TableRowAlign.END, tbl5.getTableAlignment()); + assertEquals(STJcTable.END, tbl5.getCTTbl().getTblPr().getJc().xgetVal().getEnumValue()); + } + } + + @Test + public void testDeepTableCell() { + try { + // Document contains a table with nested cells. + //noinspection resource + XWPFTestDataSamples.openSampleDocument("deep-table-cell.docx"); + fail("Should catch exception"); + } catch (POIXMLException e) { + // JDK 25+ does more checks, so more than one exception are possible + assertTrue(e.getMessage().contains("The element \"w:t\" has a depth"), + "Had: " + e); + } catch (IOException e) { + assertInstanceOf(POIException.class, e.getCause()); + assertTrue(e.getMessage().contains("Node depth exceeds maximum supported depth")); + } + } } diff --git a/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFBugs.java b/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFBugs.java index 8afaaecb2d..4846e7a402 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFBugs.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFBugs.java @@ -28,6 +28,9 @@ import java.io.IOException; import java.math.BigInteger; import java.util.List; +import org.apache.poi.openxml4j.util.ZipArchiveFakeEntry; +import org.apache.poi.openxml4j.util.ZipInputStreamZipEntrySource; +import org.apache.poi.util.IOUtils; import org.apache.poi.util.Units; import org.apache.poi.xwpf.XWPFTestDataSamples; import org.apache.poi.xwpf.usermodel.XWPFRun.FontCharRange; @@ -149,22 +152,22 @@ class TestXWPFBugs { } } - /** - * Removing a run needs to take into account position of run if paragraph contains hyperlink runs - */ - @Test - void test58618() throws IOException { - try (XWPFDocument doc = XWPFTestDataSamples.openSampleDocument("58618.docx")) { - XWPFParagraph para = (XWPFParagraph) doc.getBodyElements().get(0); - assertNotNull(para); - assertEquals("Some text some hyper links link link and some text.....", para.getText()); - XWPFRun run = para.insertNewRun(para.getRuns().size()); - run.setText("New Text"); - assertEquals("Some text some hyper links link link and some text.....New Text", para.getText()); - para.removeRun(para.getRuns().size() - 2); - assertEquals("Some text some hyper links link linkNew Text", para.getText()); - } - } + /** + * Removing a run needs to take into account position of run if paragraph contains hyperlink runs + */ + @Test + void test58618() throws IOException { + try (XWPFDocument doc = XWPFTestDataSamples.openSampleDocument("58618.docx")) { + XWPFParagraph para = (XWPFParagraph) doc.getBodyElements().get(0); + assertNotNull(para); + assertEquals("Some text some hyper links link link and some text.....", para.getText()); + XWPFRun run = para.insertNewRun(para.getRuns().size()); + run.setText("New Text"); + assertEquals("Some text some hyper links link link and some text.....New Text", para.getText()); + para.removeRun(para.getRuns().size() - 2); + assertEquals("Some text some hyper links link linkNew Text", para.getText()); + } + } @Test void test59378() throws IOException { @@ -329,7 +332,7 @@ class TestXWPFBugs { } } - private static void addNumberingWithAbstractId(XWPFNumbering documentNumbering, int id){ + private static void addNumberingWithAbstractId(XWPFNumbering documentNumbering, int id) { // create a numbering scheme CTAbstractNum cTAbstractNum = CTAbstractNum.Factory.newInstance(); // give the scheme an ID @@ -340,4 +343,34 @@ class TestXWPFBugs { documentNumbering.addNum(abstractNumID); } + + @Test + void testBug69628() throws IOException { + final int expectedParagraphs = 24; + // bug69628.docx has -1 entry sizes in the zip data + try (XWPFDocument doc = XWPFTestDataSamples.openSampleDocument("bug69628.docx")) { + assertEquals(expectedParagraphs, doc.getParagraphs().size()); + } + // test again with smaller byte array max + ZipArchiveFakeEntry.setMaxEntrySize(30 * 1024 * 1024); + try (XWPFDocument doc = XWPFTestDataSamples.openSampleDocument("bug69628.docx")) { + assertEquals(expectedParagraphs, doc.getParagraphs().size()); + } finally { + ZipArchiveFakeEntry.setMaxEntrySize(-1); + } + // test again with smaller byte array max + IOUtils.setByteArrayMaxOverride(30 * 1024 * 1024); + try (XWPFDocument doc = XWPFTestDataSamples.openSampleDocument("bug69628.docx")) { + assertEquals(expectedParagraphs, doc.getParagraphs().size()); + } finally { + IOUtils.setByteArrayMaxOverride(-1); + } + // test again but temp files enabled + ZipInputStreamZipEntrySource.setThresholdBytesForTempFiles(1000); + try (XWPFDocument doc = XWPFTestDataSamples.openSampleDocument("bug69628.docx")) { + assertEquals(expectedParagraphs, doc.getParagraphs().size()); + } finally { + ZipInputStreamZipEntrySource.setThresholdBytesForTempFiles(-1); + } + } } diff --git a/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFComment.java b/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFComment.java index 79ffa2d701..256fe9fe7e 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFComment.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFComment.java @@ -16,6 +16,7 @@ ==================================================================== */ package org.apache.poi.xwpf.usermodel; +import org.apache.poi.common.usermodel.PictureType; import org.apache.poi.openxml4j.exceptions.InvalidFormatException; import org.apache.poi.util.LocaleUtil; import org.apache.poi.xwpf.XWPFTestDataSamples; @@ -100,7 +101,7 @@ class TestXWPFComment { XWPFParagraph paragraph = comment.createParagraph(); XWPFRun r = paragraph.createRun(); r.addPicture(new ByteArrayInputStream(new byte[0]), - Document.PICTURE_TYPE_JPEG, "test.jpg", 21, 32); + PictureType.JPEG, "test.jpg", 21, 32); assertEquals(1, comments.getAllPictures().size()); assertEquals(1, doc.getAllPackagePictures().size()); diff --git a/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFParagraph.java b/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFParagraph.java index 518734f4f6..2aaf6b1072 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFParagraph.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFParagraph.java @@ -132,6 +132,7 @@ public final class TestXWPFParagraph { XWPFParagraph p = doc.createParagraph(); assertEquals(STJc.LEFT.intValue(), p.getAlignment().getValue()); + assertFalse(p.isAlignmentSet()); CTP ctp = p.getCTP(); CTPPr ppr = ctp.getPPr() == null ? ctp.addNewPPr() : ctp.getPPr(); @@ -139,9 +140,15 @@ public final class TestXWPFParagraph { CTJc align = ppr.addNewJc(); align.setVal(STJc.CENTER); assertEquals(ParagraphAlignment.CENTER, p.getAlignment()); + assertTrue(p.isAlignmentSet()); p.setAlignment(ParagraphAlignment.BOTH); assertEquals(STJc.BOTH, ppr.getJc().getVal()); + assertTrue(p.isAlignmentSet()); + + p.setAlignment(null); + assertEquals(STJc.LEFT.intValue(), p.getAlignment().getValue()); + assertFalse(p.isAlignmentSet()); } } diff --git a/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFPictureData.java b/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFPictureData.java index 926ea82868..452c869995 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFPictureData.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFPictureData.java @@ -117,7 +117,7 @@ class TestXWPFPictureData { // Add a picture to the first paragraph header.getParagraphs().get(0).getRuns().get(0).addPicture( new ByteArrayInputStream(new byte[]{1, 2, 3, 4}), - Document.PICTURE_TYPE_JPEG, "test.jpg", 2, 2); + PictureType.JPEG, "test.jpg", 2, 2); // Check verifyOneHeaderPicture(doc); diff --git a/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFRun.java b/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFRun.java index c9c199429c..87561e720d 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFRun.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFRun.java @@ -36,6 +36,7 @@ import org.apache.poi.openxml4j.exceptions.InvalidFormatException; import org.apache.poi.util.LocaleUtil; import org.apache.poi.util.Units; import org.apache.poi.wp.usermodel.HeaderFooterType; +import org.apache.poi.xddf.usermodel.chart.XDDFChart; import org.apache.poi.xwpf.XWPFTestDataSamples; import org.apache.poi.xwpf.model.XWPFHeaderFooterPolicy; import org.junit.jupiter.api.AfterEach; @@ -552,7 +553,7 @@ class TestXWPFRun { assertEquals(0, doc.getAllPictures().size()); assertEquals(0, r.getEmbeddedPictures().size()); - r.addPicture(new ByteArrayInputStream(new byte[0]), Document.PICTURE_TYPE_JPEG, "test.jpg", 21, 32); + r.addPicture(new ByteArrayInputStream(new byte[0]), PictureType.JPEG, "test.jpg", 21, 32); assertEquals(1, doc.getAllPictures().size()); assertEquals(1, r.getEmbeddedPictures().size()); @@ -580,7 +581,7 @@ class TestXWPFRun { assertEquals(0, hdr.getAllPictures().size()); assertEquals(0, r.getEmbeddedPictures().size()); - r.addPicture(new ByteArrayInputStream(new byte[0]), Document.PICTURE_TYPE_JPEG, "test.jpg", 21, 32); + r.addPicture(new ByteArrayInputStream(new byte[0]), PictureType.JPEG, "test.jpg", 21, 32); assertEquals(1, hdr.getAllPictures().size()); assertEquals(1, r.getEmbeddedPictures().size()); @@ -627,7 +628,7 @@ class TestXWPFRun { try (XWPFDocument document = new XWPFDocument()) { document.createParagraph().createRun().addPicture( - new ByteArrayInputStream(image), Document.PICTURE_TYPE_JPEG, "test.jpg", Units.toEMU(300), Units.toEMU(100)); + new ByteArrayInputStream(image), PictureType.JPEG, "test.jpg", Units.toEMU(300), Units.toEMU(100)); try (XWPFDocument docBack = writeOutAndReadBack(document)) { List<XWPFPicture> pictures = docBack.getParagraphArray(0).getRuns().get(0).getEmbeddedPictures(); @@ -858,7 +859,7 @@ class TestXWPFRun { assertEquals(0, hdr.getAllPictures().size()); assertEquals(0, r.getEmbeddedPictures().size()); - r.addPicture(new ByteArrayInputStream(new byte[0]), Document.PICTURE_TYPE_JPEG, "test.jpg", 21, 32); + r.addPicture(new ByteArrayInputStream(new byte[0]), PictureType.JPEG, "test.jpg", 21, 32); assertEquals(1, hdr.getAllPictures().size()); assertEquals(1, r.getEmbeddedPictures().size()); @@ -901,4 +902,42 @@ class TestXWPFRun { } } } + + @Test + void testGetNumberOfTexts() { + XWPFRun run = p.createRun(); + assertEquals(0, run.getNumberOfTexts()); + run.setText("TEST STRING"); + assertEquals(1, run.getNumberOfTexts()); + } + + @Test + void testGetEmbeddedCharts() throws IOException { + try (XWPFDocument sampleDoc = XWPFTestDataSamples.openSampleDocument("61745.docx")) { + List<XWPFChart> charts = sampleDoc.getCharts(); + assertEquals(2, charts.size()); + List<XWPFChart> run1Charts = sampleDoc.getParagraphArray(0).getRuns().get(0).getEmbeddedCharts(); + assertEquals(1, run1Charts.size()); + assertEquals(charts.get(0), run1Charts.get(0)); + List<XWPFChart> run2Charts = sampleDoc.getParagraphArray(1).getRuns().get(0).getEmbeddedCharts(); + assertEquals(1, run2Charts.size()); + assertEquals(charts.get(1), run2Charts.get(0)); + } + } + + @Test + void testAddChartGetEmbeddedCharts() throws InvalidFormatException, IOException { + XWPFRun run1 = p.createRun(); + XWPFChart chart1 = doc.createChart(run1, XDDFChart.DEFAULT_WIDTH, XDDFChart.DEFAULT_HEIGHT); + assertEquals(1, run1.getEmbeddedCharts().size()); + assertEquals(chart1, run1.getEmbeddedCharts().get(0)); + + XWPFRun run2 = p.createRun(); + XWPFChart chart2 = doc.createChart(run2, XDDFChart.DEFAULT_WIDTH, XDDFChart.DEFAULT_HEIGHT); + assertEquals(1, run2.getEmbeddedCharts().size()); + assertEquals(chart2, run2.getEmbeddedCharts().get(0)); + + XWPFRun run3 = p.createRun(); + assertEquals(0, run3.getEmbeddedCharts().size()); + } } diff --git a/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFTable.java b/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFTable.java index 67e911c15a..3bd3205036 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFTable.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFTable.java @@ -16,9 +16,7 @@ ==================================================================== */ package org.apache.poi.xwpf.usermodel; -import static org.junit.jupiter.api.Assertions.assertEquals; -import static org.junit.jupiter.api.Assertions.assertNotNull; -import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.*; import java.io.IOException; import java.math.BigInteger; @@ -573,17 +571,85 @@ class TestXWPFTable { void testSetGetTableAlignment() throws IOException { try (XWPFDocument doc = new XWPFDocument()) { XWPFTable tbl = doc.createTable(1, 1); + tbl.setTableAlignment(TableRowAlign.START); + assertEquals(TableRowAlign.START, tbl.getTableAlignment()); + assertEquals(STJcTable.INT_START, tbl.getTableAlignment().getValue()); tbl.setTableAlignment(TableRowAlign.LEFT); assertEquals(TableRowAlign.LEFT, tbl.getTableAlignment()); - assertEquals(STJcTable.INT_START, tbl.getTableAlignment().getValue()); + assertEquals(STJcTable.INT_LEFT, tbl.getTableAlignment().getValue()); tbl.setTableAlignment(TableRowAlign.CENTER); assertEquals(TableRowAlign.CENTER, tbl.getTableAlignment()); assertEquals(STJcTable.INT_CENTER, tbl.getTableAlignment().getValue()); tbl.setTableAlignment(TableRowAlign.RIGHT); assertEquals(TableRowAlign.RIGHT, tbl.getTableAlignment()); + assertEquals(STJcTable.INT_RIGHT, tbl.getTableAlignment().getValue()); + tbl.setTableAlignment(TableRowAlign.END); + assertEquals(TableRowAlign.END, tbl.getTableAlignment()); assertEquals(STJcTable.INT_END, tbl.getTableAlignment().getValue()); tbl.removeTableAlignment(); assertNull(tbl.getTableAlignment()); } } -}
\ No newline at end of file + + @Test + public void testGetTableIndent() throws Exception { + // open an empty document + try (XWPFDocument doc = XWPFTestDataSamples.openSampleDocument("table-indent.docx")) { + + XWPFTable table1 = doc.getTableArray(0); + // Indent not present in the document + assertFalse(table1.hasIndent()); + assertEquals(0, table1.getIndent()); + + XWPFTable table2 = doc.getTableArray(1); + // Valid indent value with type dxa + assertTrue(table2.hasIndent()); + assertEquals(732, table2.getIndent()); + + XWPFTable table3 = doc.getTableArray(2); + // Indent is of type "nil" + assertTrue(table3.hasIndent()); + assertEquals(0, table3.getIndent()); + + XWPFTable table4 = doc.getTableArray(3); + // Indent is of type "pct" which should be ignored + assertFalse(table4.hasIndent()); + assertEquals(0, table4.getIndent()); + + XWPFTable table5 = doc.getTableArray(4); + // Indent is of type "auto" which should be ignored + assertFalse(table5.hasIndent()); + assertEquals(0, table5.getIndent()); + + XWPFTable table6 = doc.getTableArray(5); + // Valid indent value with empty type (defaults to dxa) + assertTrue(table6.hasIndent()); + assertEquals(732, table6.getIndent()); + + XWPFTable table7 = doc.getTableArray(6); + // Valid indent value, negative values are allowed + assertTrue(table7.hasIndent()); + assertEquals(-500, table7.getIndent()); + } + } + + @Test + void testSetGetTableIndent() throws IOException { + try (XWPFDocument doc = new XWPFDocument()) { + XWPFTable tbl = doc.createTable(1, 1); + assertFalse(tbl.hasIndent()); + tbl.setIndent(100); + assertTrue(tbl.hasIndent()); + assertEquals(100, tbl.getIndent()); + tbl.setIndent(0); + assertTrue(tbl.hasIndent()); + assertEquals(0, tbl.getIndent()); + tbl.setIndent(-100); + assertTrue(tbl.hasIndent()); + assertEquals(-100, tbl.getIndent()); + tbl.removeIndent(); + assertFalse(tbl.hasIndent()); + assertEquals(0, tbl.getIndent()); + } + } +} diff --git a/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFTableCell.java b/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFTableCell.java index 9d29cb8247..688133d772 100644 --- a/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFTableCell.java +++ b/poi-ooxml/src/test/java/org/apache/poi/xwpf/usermodel/TestXWPFTableCell.java @@ -271,6 +271,7 @@ class TestXWPFTableCell { XWPFDocument doc = new XWPFDocument(); XWPFTable table = doc.createTable(1, 1); XWPFTableCell cell = table.getRow(0).getCell(0); + assertEquals(doc, cell.getXWPFDocument()); // cell have at least one paragraph by default when creating a cell assertEquals(1, cell.getParagraphs().size()); @@ -282,6 +283,7 @@ class TestXWPFTableCell { XWPFDocument readDoc = XWPFTestDataSamples.writeOutAndReadBack(doc); XWPFTableCell readCell = readDoc.getTableArray(0).getRow(0).getCell(0); assertEquals(0, readCell.getParagraphs().size()); + assertEquals(readDoc, readCell.getXWPFDocument()); } @Test diff --git a/poi-ooxml/src/test/java9/module-info.java b/poi-ooxml/src/test/java9/module-info.java index 3c6276dfd6..3fbcedfb34 100644 --- a/poi-ooxml/src/test/java9/module-info.java +++ b/poi-ooxml/src/test/java9/module-info.java @@ -96,8 +96,7 @@ module org.apache.poi.ooxml { /* optional dependencies for slideshow rendering via PPTX2PNG */ requires static org.apache.xmlgraphics.batik.anim; requires static org.apache.xmlgraphics.batik.awt.util; - /* this typo appears in Batik 1.18 and will be fixed in a future release */ - requires static org.apache.xmlgraphics.batik.brdige; + requires static org.apache.xmlgraphics.batik.bridge; requires static org.apache.xmlgraphics.batik.codec; requires static org.apache.xmlgraphics.batik.constants; requires static org.apache.xmlgraphics.batik.css; @@ -113,7 +112,7 @@ module org.apache.poi.ooxml { requires static org.apache.xmlgraphics.batik.transcoder; requires static org.apache.xmlgraphics.batik.util; requires static org.apache.xmlgraphics.batik.xml; - requires static xmlgraphics.commons; + requires static org.apache.xmlgraphics.commons; requires static org.apache.pdfbox; requires static org.apache.fontbox; diff --git a/poi-scratchpad/build.gradle b/poi-scratchpad/build.gradle index 7f08037587..79069943fe 100644 --- a/poi-scratchpad/build.gradle +++ b/poi-scratchpad/build.gradle @@ -53,7 +53,7 @@ final Pattern MODULE_REGEX = ~'\\.jar$' final List MAIN_MODULE_PATH = sourceSets.main.runtimeClasspath.findAll{ it.path =~ MODULE_REGEX }.collect{ it.parent }.unique() final List TEST_MODULE_PATH = sourceSets.test.runtimeClasspath.findAll{ it.path =~ MODULE_REGEX && !(it.path =~ MODULE_NOT_REGEX) }.collect{ it.parent }.unique() -task compileJava9(type: JavaCompile) { +tasks.register('compileJava9', JavaCompile) { dependsOn 'compileJava', ':poi:jar' javaCompiler = javaToolchains.compilerFor { @@ -65,12 +65,12 @@ task compileJava9(type: JavaCompile) { source = file(JAVA9_SRC) classpath = files() options.compilerArgs = [ - '--patch-module', "${MODULE_NAME}=${sourceSets.main.output.classesDirs.asPath}", - '--module-path', files(MAIN_MODULE_PATH).asPath + '--patch-module', "${MODULE_NAME}=${sourceSets.main.output.classesDirs.asPath}", + '--module-path', files(MAIN_MODULE_PATH).asPath ] } -task compileTest9(type: JavaCompile) { +tasks.register('compileTest9', JavaCompile) { dependsOn 'compileTestJava', ':poi:jar' javaCompiler = javaToolchains.compilerFor { @@ -81,8 +81,8 @@ task compileTest9(type: JavaCompile) { destinationDirectory = file(TEST9_OUT + VERSIONS9) source = file(TEST9_SRC) options.compilerArgs = [ - '--patch-module', "${MODULE_NAME}=${(sourceSets.main.output.classesDirs + sourceSets.test.output.classesDirs).asPath}", - '--module-path', files(TEST_MODULE_PATH).asPath + '--patch-module', "${MODULE_NAME}=${(sourceSets.main.output.classesDirs + sourceSets.test.output.classesDirs).asPath}", + '--module-path', files(TEST_MODULE_PATH).asPath ] classpath = files() } @@ -103,7 +103,7 @@ task testJar(type: Jar, dependsOn: testClasses) { setArchiveClassifier 'tests' // ignore second module-info.class from main - duplicatesStrategy = 'exclude' + duplicatesStrategy = DuplicatesStrategy.EXCLUDE from sourceSets.test.output + sourceSets.main.output diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hdgf/streams/PointerContainingStream.java b/poi-scratchpad/src/main/java/org/apache/poi/hdgf/streams/PointerContainingStream.java index 69964427fa..387cb8580d 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hdgf/streams/PointerContainingStream.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hdgf/streams/PointerContainingStream.java @@ -17,8 +17,6 @@ package org.apache.poi.hdgf.streams; -import org.apache.logging.log4j.Logger; -import org.apache.poi.logging.PoiLogManager; import org.apache.poi.hdgf.chunks.ChunkFactory; import org.apache.poi.hdgf.pointers.Pointer; import org.apache.poi.hdgf.pointers.PointerFactory; @@ -28,8 +26,6 @@ import org.apache.poi.hdgf.pointers.PointerFactory; * other data too. */ public class PointerContainingStream extends Stream { // TODO - instantiable superclass - private static final Logger LOG = PoiLogManager.getLogger(PointerContainingStream.class); - private static int MAX_CHILDREN_NESTING = 500; private final Pointer[] childPointers; @@ -68,9 +64,9 @@ public class PointerContainingStream extends Stream { // TODO - instantiable sup } private void findChildren(byte[] documentData, int nesting) { - if (nesting > MAX_CHILDREN_NESTING) { + if (nesting > getMaxChildrenNesting()) { throw new IllegalArgumentException("Encountered too deep nesting, cannot process stream " + - "with more than " + MAX_CHILDREN_NESTING + " nested children. " + + "with more than " + getMaxChildrenNesting() + " nested children. " + "Some data could not be parsed. You can call setMaxChildrenNesting() to adjust " + "this limit."); } diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/MAPIDateAttribute.java b/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/MAPIDateAttribute.java index c267bd82ed..00f92545f8 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/MAPIDateAttribute.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/MAPIDateAttribute.java @@ -70,7 +70,7 @@ public final class MAPIDateAttribute extends MAPIAttribute { } /** - * Returns the Date of a Attribute, converting as appropriate + * Returns the Date of an Attribute, converting as appropriate */ public static Date getAsDate(MAPIAttribute attr) { if(attr == null) { diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/MAPIStringAttribute.java b/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/MAPIStringAttribute.java index c30ec513cb..9e3d6d0cb9 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/MAPIStringAttribute.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/MAPIStringAttribute.java @@ -64,7 +64,7 @@ public final class MAPIStringAttribute extends MAPIAttribute { } /** - * Returns the string of a Attribute, converting as appropriate + * Returns the string of an Attribute, converting as appropriate */ public static String getAsString(MAPIAttribute attr) { if(attr == null) { diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/TNEFDateAttribute.java b/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/TNEFDateAttribute.java index ea6382b461..7c27f76fbe 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/TNEFDateAttribute.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/TNEFDateAttribute.java @@ -85,7 +85,7 @@ public final class TNEFDateAttribute extends TNEFAttribute { } /** - * Returns the Date of a Attribute, converting as appropriate + * Returns the Date of an Attribute, converting as appropriate */ public static Date getAsDate(TNEFAttribute attr) { if(attr == null) { diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/TNEFStringAttribute.java b/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/TNEFStringAttribute.java index c403754edb..99c4cf4412 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/TNEFStringAttribute.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hmef/attribute/TNEFStringAttribute.java @@ -68,7 +68,7 @@ public final class TNEFStringAttribute extends TNEFAttribute { } /** - * Returns the string of a Attribute, converting as appropriate + * Returns the string of an Attribute, converting as appropriate */ public static String getAsString(TNEFAttribute attr) { if(attr == null) { diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hmef/extractor/HMEFContentsExtractor.java b/poi-scratchpad/src/main/java/org/apache/poi/hmef/extractor/HMEFContentsExtractor.java index 59cbe79e91..8e01252c64 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hmef/extractor/HMEFContentsExtractor.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hmef/extractor/HMEFContentsExtractor.java @@ -141,10 +141,10 @@ public final class HMEFContentsExtractor { // Decide what to call it String filename = att.getLongFilename(); - if(filename == null || filename.length() == 0) { + if(filename == null || filename.isEmpty()) { filename = att.getFilename(); } - if(filename == null || filename.length() == 0) { + if(filename == null || filename.isEmpty()) { filename = "attachment" + count; if(att.getExtension() != null) { filename += att.getExtension(); diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFFill.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFFill.java index 3f9f84b6d6..3a8c767e6d 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFFill.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFFill.java @@ -576,9 +576,7 @@ public final class HSLFFill { } else { EscherBSERecord bse = (EscherBSERecord) bstore.getChild(idx - 1); for (HSLFPictureData pd : pict) { - - // Reference equals is safe because these BSE belong to the same slideshow - if (pd.bse == bse) { + if (pd.getOffset() == bse.getOffset()) { return pd; } } diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFPictureShape.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFPictureShape.java index 71e67084e1..e10a54cb55 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFPictureShape.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFPictureShape.java @@ -124,9 +124,7 @@ public class HSLFPictureShape extends HSLFSimpleShape implements PictureShape<HS LOG.atError().log("no reference to picture data found "); } else { for (HSLFPictureData pd : pict) { - - // Reference equals is safe because these BSE belong to the same slideshow - if (pd.bse == bse) { + if (pd.getOffset() == bse.getOffset()) { return pd; } } diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFShapePlaceholderDetails.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFShapePlaceholderDetails.java index 8a467dfedc..348d901235 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFShapePlaceholderDetails.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFShapePlaceholderDetails.java @@ -47,6 +47,68 @@ import org.apache.poi.util.LocaleUtil; * @since POI 4.0.0 */ public class HSLFShapePlaceholderDetails extends HSLFPlaceholderDetails { + + static void updateSPRecord(final HSLFSimpleShape shape, final Placeholder placeholder) { + final EscherSpRecord spRecord = shape.getEscherChild(EscherSpRecord.RECORD_ID); + int flags = spRecord.getFlags(); + if (placeholder == null) { + flags ^= EscherSpRecord.FLAG_HAVEMASTER; + } else { + flags |= EscherSpRecord.FLAG_HAVEANCHOR | EscherSpRecord.FLAG_HAVEMASTER; + } + spRecord.setFlags(flags); + + // Placeholders can't be grouped + shape.setEscherProperty(EscherPropertyTypes.PROTECTION__LOCKAGAINSTGROUPING, (placeholder == null ? -1 : 262144)); + } + + static void removePlaceholder(final HSLFSimpleShape shape) { + final HSLFEscherClientDataRecord clientData = shape.getClientData(false); + if (clientData != null) { + clientData.removeChild(OEPlaceholderAtom.class); + clientData.removeChild(RoundTripHFPlaceholder12.class); + // remove client data if the placeholder was the only child to be carried + if (clientData.getChildRecords().isEmpty()) { + shape.getSpContainer().removeChildRecord(clientData); + } + } + } + + static OEPlaceholderAtom createOEPlaceholderAtom(final HSLFEscherClientDataRecord clientData) { + return createOEPlaceholderAtom(clientData, (byte) 0); + } + + static OEPlaceholderAtom createOEPlaceholderAtom(final HSLFEscherClientDataRecord clientData, + final byte placeholderId) { + OEPlaceholderAtom oePlaceholderAtom = new OEPlaceholderAtom(); + oePlaceholderAtom.setPlaceholderSize((byte)OEPlaceholderAtom.PLACEHOLDER_FULLSIZE); + // TODO: placement id only "SHOULD" be unique ... check other placeholders on sheet for unique id + oePlaceholderAtom.setPlacementId(-1); + oePlaceholderAtom.setPlaceholderId(placeholderId); + clientData.addChild(oePlaceholderAtom); + return oePlaceholderAtom; + } + + static byte getPlaceholderId(final HSLFSheet sheet, final Placeholder placeholder) { + if (placeholder == null) { + return 0; + } + byte phId; + // TODO: implement/switch NotesMaster + if (sheet instanceof HSLFSlideMaster) { + phId = (byte) placeholder.nativeSlideMasterId; + } else if (sheet instanceof HSLFNotes) { + phId = (byte) placeholder.nativeNotesId; + } else { + phId = (byte) placeholder.nativeSlideId; + } + + if (phId == -2) { + throw new HSLFException("Placeholder " + placeholder.name() + " not supported for this sheet type (" + sheet.getClass() + ")"); + } + return phId; + } + private enum PlaceholderContainer { slide, master, notes, notesMaster } @@ -78,7 +140,7 @@ public class HSLFShapePlaceholderDetails extends HSLFPlaceholderDetails { @Override public Placeholder getPlaceholder() { - updatePlaceholderAtom(false); + updatePlaceholderAtom(null, false); final int phId; if (oePlaceholderAtom != null) { phId = oePlaceholderAtom.getPlaceholderId(); @@ -105,17 +167,7 @@ public class HSLFShapePlaceholderDetails extends HSLFPlaceholderDetails { @Override public void setPlaceholder(final Placeholder placeholder) { - final EscherSpRecord spRecord = shape.getEscherChild(EscherSpRecord.RECORD_ID); - int flags = spRecord.getFlags(); - if (placeholder == null) { - flags ^= EscherSpRecord.FLAG_HAVEMASTER; - } else { - flags |= EscherSpRecord.FLAG_HAVEANCHOR | EscherSpRecord.FLAG_HAVEMASTER; - } - spRecord.setFlags(flags); - - // Placeholders can't be grouped - shape.setEscherProperty(EscherPropertyTypes.PROTECTION__LOCKAGAINSTGROUPING, (placeholder == null ? -1 : 262144)); + updateSPRecord(shape, placeholder); if (placeholder == null) { removePlaceholder(); @@ -123,7 +175,7 @@ public class HSLFShapePlaceholderDetails extends HSLFPlaceholderDetails { } // init client data - updatePlaceholderAtom(true); + updatePlaceholderAtom(placeholder, true); final byte phId = getPlaceholderId(placeholder); oePlaceholderAtom.setPlaceholderId(phId); @@ -158,7 +210,7 @@ public class HSLFShapePlaceholderDetails extends HSLFPlaceholderDetails { if (ph == null || size == null) { return; } - updatePlaceholderAtom(true); + updatePlaceholderAtom(ph, true); final byte ph_size; switch (size) { @@ -209,20 +261,12 @@ public class HSLFShapePlaceholderDetails extends HSLFPlaceholderDetails { } private void removePlaceholder() { - final HSLFEscherClientDataRecord clientData = shape.getClientData(false); - if (clientData != null) { - clientData.removeChild(OEPlaceholderAtom.class); - clientData.removeChild(RoundTripHFPlaceholder12.class); - // remove client data if the placeholder was the only child to be carried - if (clientData.getChildRecords().isEmpty()) { - shape.getSpContainer().removeChildRecord(clientData); - } - } + removePlaceholder(shape); oePlaceholderAtom = null; roundTripHFPlaceholder12 = null; } - private void updatePlaceholderAtom(final boolean create) { + private void updatePlaceholderAtom(final Placeholder placeholder, final boolean create) { localDateTime = null; if (shape instanceof HSLFTextBox) { EscherTextboxWrapper txtBox = ((HSLFTextBox)shape).getEscherTextboxWrapper(); @@ -255,11 +299,8 @@ public class HSLFShapePlaceholderDetails extends HSLFPlaceholderDetails { } if (oePlaceholderAtom == null) { - oePlaceholderAtom = new OEPlaceholderAtom(); - oePlaceholderAtom.setPlaceholderSize((byte)OEPlaceholderAtom.PLACEHOLDER_FULLSIZE); - // TODO: placement id only "SHOULD" be unique ... check other placeholders on sheet for unique id - oePlaceholderAtom.setPlacementId(-1); - clientData.addChild(oePlaceholderAtom); + final byte phId = getPlaceholderId(shape.getSheet(), placeholder); + oePlaceholderAtom = createOEPlaceholderAtom(clientData, phId); } if (roundTripHFPlaceholder12 == null) { roundTripHFPlaceholder12 = new RoundTripHFPlaceholder12(); diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFSimpleShape.java b/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFSimpleShape.java index da930b6899..aa85a65a92 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFSimpleShape.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hslf/usermodel/HSLFSimpleShape.java @@ -20,6 +20,9 @@ package org.apache.poi.hslf.usermodel; import java.awt.Color; import org.apache.logging.log4j.Logger; +import org.apache.poi.hslf.record.HSLFEscherClientDataRecord; +import org.apache.poi.hslf.record.OEPlaceholderAtom; +import org.apache.poi.hslf.record.RoundTripHFPlaceholder12; import org.apache.poi.logging.PoiLogManager; import org.apache.poi.ddf.AbstractEscherOptRecord; import org.apache.poi.ddf.EscherChildAnchorRecord; @@ -53,6 +56,11 @@ import org.apache.poi.sl.usermodel.StrokeStyle.LineDash; import org.apache.poi.util.LittleEndian; import org.apache.poi.util.Units; +import static org.apache.poi.hslf.usermodel.HSLFShapePlaceholderDetails.createOEPlaceholderAtom; +import static org.apache.poi.hslf.usermodel.HSLFShapePlaceholderDetails.getPlaceholderId; +import static org.apache.poi.hslf.usermodel.HSLFShapePlaceholderDetails.removePlaceholder; +import static org.apache.poi.hslf.usermodel.HSLFShapePlaceholderDetails.updateSPRecord; + /** * An abstract simple (non-group) shape. * This is the parent class for all primitive shapes like Line, Rectangle, etc. @@ -80,6 +88,8 @@ public abstract class HSLFSimpleShape extends HSLFShape implements SimpleShape<H */ protected HSLFHyperlink _hyperlink; + protected HSLFShapePlaceholderDetails _placeholderDetails; + /** * Create a SimpleShape object and initialize it from the supplied Record container. * @@ -564,10 +574,12 @@ public abstract class HSLFSimpleShape extends HSLFShape implements SimpleShape<H @Override public HSLFShapePlaceholderDetails getPlaceholderDetails() { - return new HSLFShapePlaceholderDetails(this); + if (_placeholderDetails == null) { + _placeholderDetails = new HSLFShapePlaceholderDetails(this); + } + return _placeholderDetails; } - @Override public Placeholder getPlaceholder() { return getPlaceholderDetails().getPlaceholder(); @@ -575,9 +587,62 @@ public abstract class HSLFSimpleShape extends HSLFShape implements SimpleShape<H @Override public void setPlaceholder(Placeholder placeholder) { - getPlaceholderDetails().setPlaceholder(placeholder); - } + // reset the placeholder details so that the next call to getPlaceholderDetails() will reinitialize it + _placeholderDetails = null; + updateSPRecord(this, placeholder); + if (placeholder == null) { + removePlaceholder(this); + return; + } + + HSLFEscherClientDataRecord clientData = getClientData(true); + + // OEPlaceholderAtom tells powerpoint that this shape is a placeholder + OEPlaceholderAtom oep = null; + RoundTripHFPlaceholder12 rtp = null; + for (org.apache.poi.hslf.record.Record r : clientData.getHSLFChildRecords()) { + if (r instanceof OEPlaceholderAtom) { + oep = (OEPlaceholderAtom) r; + break; + } + if (r instanceof RoundTripHFPlaceholder12) { + rtp = (RoundTripHFPlaceholder12) r; + break; + } + } + + /** + * Extract from MSDN: + * + * There is a special case when the placeholder does not have a position in the layout. + * This occurs when the user has moved the placeholder from its original position. + * In this case the placeholder ID is -1. + */ + final byte phId = getPlaceholderId(getSheet(), placeholder); + + switch (placeholder) { + case HEADER: + case FOOTER: + if (rtp == null) { + rtp = new RoundTripHFPlaceholder12(); + rtp.setPlaceholderId(phId); + clientData.addChild(rtp); + } + if (oep != null) { + clientData.removeChild(OEPlaceholderAtom.class); + } + break; + default: + if (rtp != null) { + clientData.removeChild(RoundTripHFPlaceholder12.class); + } + if (oep == null) { + oep = createOEPlaceholderAtom(clientData, phId); + } + break; + } + } @Override public void setStrokeStyle(Object... styles) { diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hsmf/extractor/OutlookTextExtractor.java b/poi-scratchpad/src/main/java/org/apache/poi/hsmf/extractor/OutlookTextExtractor.java index 62b09b374e..e87185ec93 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hsmf/extractor/OutlookTextExtractor.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hsmf/extractor/OutlookTextExtractor.java @@ -177,7 +177,7 @@ public class OutlookTextExtractor implements POIOLE2TextExtractor { * {@code "Nick <nick@example.com>; Jim <jim@example.com>"} */ protected void handleEmails(StringBuilder s, String type, String displayText, Iterator<String> emails) { - if (displayText == null || displayText.length() == 0) { + if (displayText == null || displayText.isEmpty()) { return; } diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hssf/converter/AbstractExcelUtils.java b/poi-scratchpad/src/main/java/org/apache/poi/hssf/converter/AbstractExcelUtils.java index 88498ea39e..3485f40911 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hssf/converter/AbstractExcelUtils.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hssf/converter/AbstractExcelUtils.java @@ -174,7 +174,7 @@ class AbstractExcelUtils { } static boolean isEmpty(String str) { - return str == null || str.length() == 0; + return str == null || str.isEmpty(); } static boolean isNotEmpty(String str) { diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/AbstractWordConverter.java b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/AbstractWordConverter.java index aefe15d9da..0eca5fb49a 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/AbstractWordConverter.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/AbstractWordConverter.java @@ -310,8 +310,7 @@ public abstract class AbstractWordConverter { continue; } String text = characterRun.text(); - if (text == null || text.length() == 0 - || text.charAt(0) != FIELD_BEGIN_MARK) { + if (text == null || text.isEmpty() || text.charAt(0) != FIELD_BEGIN_MARK) { continue; } diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/AbstractWordUtils.java b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/AbstractWordUtils.java index 9ef569fc6b..b2bd30f808 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/AbstractWordUtils.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/AbstractWordUtils.java @@ -417,7 +417,7 @@ public class AbstractWordUtils { static boolean isEmpty( String str ) { - return str == null || str.length() == 0; + return str == null || str.isEmpty(); } static boolean isNotEmpty( String str ) diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/DefaultFontReplacer.java b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/DefaultFontReplacer.java index b9845fd348..2df337e1d3 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/DefaultFontReplacer.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/converter/DefaultFontReplacer.java @@ -87,7 +87,7 @@ public class DefaultFontReplacer implements FontReplacer private static boolean isEmpty( String str ) { - return str == null || str.length() == 0; + return str == null || str.isEmpty(); } private static boolean isNotEmpty( String str ) diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/extractor/WordExtractor.java b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/extractor/WordExtractor.java index 880c4e2d38..06c4a202ae 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/extractor/WordExtractor.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/extractor/WordExtractor.java @@ -139,7 +139,7 @@ public final class WordExtractor implements POIOLE2TextExtractor { * Add the header/footer text, if it's not empty */ private void appendHeaderFooter( String text, StringBuilder out ) { - if ( text == null || text.length() == 0 ) + if ( text == null || text.isEmpty()) return; text = text.replace( '\r', '\n' ); diff --git a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/sprm/ParagraphSprmUncompressor.java b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/sprm/ParagraphSprmUncompressor.java index 9ee25a7fb0..da16b69ce7 100644 --- a/poi-scratchpad/src/main/java/org/apache/poi/hwpf/sprm/ParagraphSprmUncompressor.java +++ b/poi-scratchpad/src/main/java/org/apache/poi/hwpf/sprm/ParagraphSprmUncompressor.java @@ -46,423 +46,400 @@ public final class ParagraphSprmUncompressor extends SprmUncompressor { private static final Logger LOG = PoiLogManager.getLogger(ParagraphSprmUncompressor.class); - public ParagraphSprmUncompressor() - { - } + public ParagraphSprmUncompressor() { + } - public static ParagraphProperties uncompressPAP(ParagraphProperties parent, - byte[] grpprl, - int offset) - { - ParagraphProperties newProperties = parent.copy(); - SprmIterator sprmIt = new SprmIterator(grpprl, offset); + public static ParagraphProperties uncompressPAP(ParagraphProperties parent, + byte[] grpprl, + int offset) { + ParagraphProperties newProperties = parent.copy(); + SprmIterator sprmIt = new SprmIterator(grpprl, offset); - while (sprmIt.hasNext()) - { - SprmOperation sprm = sprmIt.next(); + while (sprmIt.hasNext()) { + SprmOperation sprm = sprmIt.next(); - // PAPXs can contain table sprms if the paragraph marks the end of a - // table row - if (sprm.getType() == SprmOperation.TYPE_PAP) - { - try - { - unCompressPAPOperation( newProperties, sprm ); - } - catch ( Exception exc ) - { - LOG.atError().withThrowable(exc).log("Unable to apply SPRM operation '{}'", box(sprm.getOperation())); - } - } - } + // PAPXs can contain table sprms if the paragraph marks the end of a + // table row + if (sprm.getType() == SprmOperation.TYPE_PAP) { + try { + unCompressPAPOperation(newProperties, sprm); + } catch (Exception exc) { + LOG.atError().withThrowable(exc).log("Unable to apply SPRM operation '{}'", box(sprm.getOperation())); + } + } + } - return newProperties; - } + return newProperties; + } - /** - * Performs an operation on a ParagraphProperties object. Used to uncompress - * from a papx. - * - * @param newPAP The ParagraphProperties object to perform the operation on. - * @param sprm sn SPRM operation. - */ - static void unCompressPAPOperation (ParagraphProperties newPAP, SprmOperation sprm) - { - switch (sprm.getOperation()) - { - case 0: - newPAP.setIstd (sprm.getOperand()); - break; - case 0x1: + /** + * Performs an operation on a ParagraphProperties object. Used to uncompress + * from a papx. + * + * @param newPAP The ParagraphProperties object to perform the operation on. + * @param sprm sn SPRM operation. + */ + static void unCompressPAPOperation(ParagraphProperties newPAP, SprmOperation sprm) { + switch (sprm.getOperation()) { + case 0: + newPAP.setIstd(sprm.getOperand()); + break; + case 0x1: - // Used only for piece table grpprl's not for PAPX + // Used only for piece table grpprl's not for PAPX // int istdFirst = LittleEndian.getShort (varParam, 2); // int istdLast = LittleEndian.getShort (varParam, 4); // if ((newPAP.getIstd () > istdFirst) || (newPAP.getIstd () <= istdLast)) // { // permuteIstd (newPAP, varParam, opSize); // } - break; - case 0x2: - if (newPAP.getIstd () <= 9 || newPAP.getIstd () >= 1) - { - byte paramTmp = (byte) sprm.getOperand(); - newPAP.setIstd (newPAP.getIstd () + paramTmp); - newPAP.setLvl ((byte) (newPAP.getLvl () + paramTmp)); + break; + case 0x2: + if (newPAP.getIstd() <= 9 || newPAP.getIstd() >= 1) { + byte paramTmp = (byte) sprm.getOperand(); + newPAP.setIstd(newPAP.getIstd() + paramTmp); + newPAP.setLvl((byte) (newPAP.getLvl() + paramTmp)); - if (((paramTmp >> 7) & 0x01) == 1) - { - newPAP.setIstd (Math.max (newPAP.getIstd (), 1)); - } - else - { - newPAP.setIstd (Math.min (newPAP.getIstd (), 9)); - } + if (((paramTmp >> 7) & 0x01) == 1) { + newPAP.setIstd(Math.max(newPAP.getIstd(), 1)); + } else { + newPAP.setIstd(Math.min(newPAP.getIstd(), 9)); + } - } - break; - case 0x3: - // Physical justification of the paragraph - newPAP.setJc ((byte) sprm.getOperand()); - break; - case 0x4: - newPAP.setFSideBySide (sprm.getOperand() != 0); - break; - case 0x5: - newPAP.setFKeep (sprm.getOperand() != 0); - break; - case 0x6: - newPAP.setFKeepFollow (sprm.getOperand() != 0); - break; - case 0x7: - newPAP.setFPageBreakBefore (sprm.getOperand() != 0); - break; - case 0x8: - newPAP.setBrcl ((byte) sprm.getOperand()); - break; - case 0x9: - newPAP.setBrcp ((byte) sprm.getOperand()); - break; - case 0xa: - newPAP.setIlvl ((byte) sprm.getOperand()); - break; - case 0xb: - /* sprmPIlfo -- 0x460B */ - newPAP.setIlfo( sprm.getOperandShortSigned() ); - break; - case 0xc: - newPAP.setFNoLnn (sprm.getOperand() != 0); - break; - case 0xd: - // handle tabs . variable parameter. seperate processing needed - handleTabs(newPAP, sprm); - break; - case 0xe: - newPAP.setDxaRight (sprm.getOperand()); - break; - case 0xf: - newPAP.setDxaLeft (sprm.getOperand()); - break; - case 0x10: + } + break; + case 0x3: + // Physical justification of the paragraph + newPAP.setJc((byte) sprm.getOperand()); + break; + case 0x4: + newPAP.setFSideBySide(sprm.getOperand() != 0); + break; + case 0x5: + newPAP.setFKeep(sprm.getOperand() != 0); + break; + case 0x6: + newPAP.setFKeepFollow(sprm.getOperand() != 0); + break; + case 0x7: + newPAP.setFPageBreakBefore(sprm.getOperand() != 0); + break; + case 0x8: + newPAP.setBrcl((byte) sprm.getOperand()); + break; + case 0x9: + newPAP.setBrcp((byte) sprm.getOperand()); + break; + case 0xa: + newPAP.setIlvl((byte) sprm.getOperand()); + break; + case 0xb: + /* sprmPIlfo -- 0x460B */ + newPAP.setIlfo(sprm.getOperandShortSigned()); + break; + case 0xc: + newPAP.setFNoLnn(sprm.getOperand() != 0); + break; + case 0xd: + // handle tabs . variable parameter. separate processing needed + handleTabs(newPAP, sprm); + break; + case 0xe: + newPAP.setDxaRight(sprm.getOperand()); + break; + case 0xf: + newPAP.setDxaLeft(sprm.getOperand()); + break; + case 0x10: - // sprmPNest is only stored in grpprls linked to a piece table. - newPAP.setDxaLeft (newPAP.getDxaLeft () + sprm.getOperand()); - newPAP.setDxaLeft (Math.max (0, newPAP.getDxaLeft ())); - break; - case 0x11: - newPAP.setDxaLeft1 (sprm.getOperand()); - break; - case 0x12: - newPAP.setLspd(new LineSpacingDescriptor(sprm.getGrpprl(), sprm.getGrpprlOffset())); - break; - case 0x13: - newPAP.setDyaBefore (sprm.getOperand()); - break; - case 0x14: - newPAP.setDyaAfter (sprm.getOperand()); - break; - case 0x15: - // fast saved only - //applySprmPChgTabs (newPAP, varParam, opSize); - break; - case 0x16: - // sprmPFInTable -- 0x2416 - newPAP.setFInTable( sprm.getOperand() != 0); - break; - case 0x17: - newPAP.setFTtp ( sprm.getOperand() != 0); - break; - case 0x18: - newPAP.setDxaAbs (sprm.getOperand()); - break; - case 0x19: - newPAP.setDyaAbs (sprm.getOperand()); - break; - case 0x1a: - newPAP.setDxaWidth (sprm.getOperand()); - break; - case 0x1b: - byte param = (byte)sprm.getOperand(); - // TODO: handle paragraph postioning - byte pcVert = (byte) ((param & 0x0c) >> 2); - byte pcHorz = (byte) (param & 0x03); - if (pcVert != 3) - { - newPAP.setPcVert (pcVert); - } - if (pcHorz != 3) - { - newPAP.setPcHorz (pcHorz); - } - break; + // sprmPNest is only stored in grpprls linked to a piece table. + newPAP.setDxaLeft(newPAP.getDxaLeft() + sprm.getOperand()); + newPAP.setDxaLeft(Math.max(0, newPAP.getDxaLeft())); + break; + case 0x11: + newPAP.setDxaLeft1(sprm.getOperand()); + break; + case 0x12: + newPAP.setLspd(new LineSpacingDescriptor(sprm.getGrpprl(), sprm.getGrpprlOffset())); + break; + case 0x13: + newPAP.setDyaBefore(sprm.getOperand()); + break; + case 0x14: + newPAP.setDyaAfter(sprm.getOperand()); + break; + case 0x15: + // fast saved only + //applySprmPChgTabs (newPAP, varParam, opSize); + break; + case 0x16: + // sprmPFInTable -- 0x2416 + newPAP.setFInTable(sprm.getOperand() != 0); + break; + case 0x17: + newPAP.setFTtp(sprm.getOperand() != 0); + break; + case 0x18: + newPAP.setDxaAbs(sprm.getOperand()); + break; + case 0x19: + newPAP.setDyaAbs(sprm.getOperand()); + break; + case 0x1a: + newPAP.setDxaWidth(sprm.getOperand()); + break; + case 0x1b: + byte param = (byte) sprm.getOperand(); + // TODO: handle paragraph postioning + byte pcVert = (byte) ((param & 0x0c) >> 2); + byte pcHorz = (byte) (param & 0x03); + if (pcVert != 3) { + newPAP.setPcVert(pcVert); + } + if (pcHorz != 3) { + newPAP.setPcHorz(pcHorz); + } + break; - // BrcXXX1 is older Version. Brc is used - // case 0x1c: - // newPAP.setBrcTop1((short)param); - // break; - // case 0x1d: - // newPAP.setBrcLeft1((short)param); - // break; - // case 0x1e: - // newPAP.setBrcBottom1((short)param); - // break; - // case 0x1f: - // newPAP.setBrcRight1((short)param); - // break; - // case 0x20: - // newPAP.setBrcBetween1((short)param); - // break; - // case 0x21: - // newPAP.setBrcBar1((byte)param); - // break; + // BrcXXX1 is older Version. Brc is used + // case 0x1c: + // newPAP.setBrcTop1((short)param); + // break; + // case 0x1d: + // newPAP.setBrcLeft1((short)param); + // break; + // case 0x1e: + // newPAP.setBrcBottom1((short)param); + // break; + // case 0x1f: + // newPAP.setBrcRight1((short)param); + // break; + // case 0x20: + // newPAP.setBrcBetween1((short)param); + // break; + // case 0x21: + // newPAP.setBrcBar1((byte)param); + // break; - case 0x22: - newPAP.setDxaFromText (sprm.getOperand()); - break; - case 0x23: - newPAP.setWr((byte)sprm.getOperand()); - break; - case 0x24: - newPAP.setBrcTop(new BorderCode(sprm.getGrpprl(), sprm.getGrpprlOffset())); - break; - case 0x25: - newPAP.setBrcLeft(new BorderCode(sprm.getGrpprl(), sprm.getGrpprlOffset())); - break; - case 0x26: - newPAP.setBrcBottom (new BorderCode(sprm.getGrpprl(), sprm.getGrpprlOffset())); - break; - case 0x27: - newPAP.setBrcRight (new BorderCode(sprm.getGrpprl(), sprm.getGrpprlOffset())); - break; - case 0x28: - newPAP.setBrcBetween (new BorderCode(sprm.getGrpprl(), sprm.getGrpprlOffset())); - break; - case 0x29: - newPAP.setBrcBar (new BorderCode(sprm.getGrpprl(), sprm.getGrpprlOffset())); - break; - case 0x2a: - newPAP.setFNoAutoHyph (sprm.getOperand() != 0); - break; - case 0x2b: - newPAP.setDyaHeight (sprm.getOperand()); - break; - case 0x2c: - newPAP.setDcs (new DropCapSpecifier((short)sprm.getOperand())); - break; - case 0x2d: - newPAP.setShd( new ShadingDescriptor80( (short) sprm.getOperand() ) - .toShadingDescriptor() ); + case 0x22: + newPAP.setDxaFromText(sprm.getOperand()); + break; + case 0x23: + newPAP.setWr((byte) sprm.getOperand()); + break; + case 0x24: + newPAP.setBrcTop(new BorderCode(sprm.getGrpprl(), sprm.getGrpprlOffset())); + break; + case 0x25: + newPAP.setBrcLeft(new BorderCode(sprm.getGrpprl(), sprm.getGrpprlOffset())); + break; + case 0x26: + newPAP.setBrcBottom(new BorderCode(sprm.getGrpprl(), sprm.getGrpprlOffset())); + break; + case 0x27: + newPAP.setBrcRight(new BorderCode(sprm.getGrpprl(), sprm.getGrpprlOffset())); + break; + case 0x28: + newPAP.setBrcBetween(new BorderCode(sprm.getGrpprl(), sprm.getGrpprlOffset())); + break; + case 0x29: + newPAP.setBrcBar(new BorderCode(sprm.getGrpprl(), sprm.getGrpprlOffset())); + break; + case 0x2a: + newPAP.setFNoAutoHyph(sprm.getOperand() != 0); + break; + case 0x2b: + newPAP.setDyaHeight(sprm.getOperand()); + break; + case 0x2c: + newPAP.setDcs(new DropCapSpecifier((short) sprm.getOperand())); + break; + case 0x2d: + newPAP.setShd(new ShadingDescriptor80((short) sprm.getOperand()) + .toShadingDescriptor()); + break; + case 0x2e: + newPAP.setDyaFromText(sprm.getOperand()); + break; + case 0x2f: + newPAP.setDxaFromText(sprm.getOperand()); + break; + case 0x30: + newPAP.setFLocked(sprm.getOperand() != 0); + break; + case 0x31: + newPAP.setFWidowControl(sprm.getOperand() != 0); + break; + case 0x33: + newPAP.setFKinsoku(sprm.getOperand() != 0); + break; + case 0x34: + newPAP.setFWordWrap(sprm.getOperand() != 0); + break; + case 0x35: + newPAP.setFOverflowPunct(sprm.getOperand() != 0); + break; + case 0x36: + newPAP.setFTopLinePunct(sprm.getOperand() != 0); + break; + case 0x37: + newPAP.setFAutoSpaceDE(sprm.getOperand() != 0); + break; + case 0x38: + newPAP.setFAutoSpaceDN(sprm.getOperand() != 0); + break; + case 0x39: + newPAP.setWAlignFont(sprm.getOperand()); + break; + case 0x3a: + newPAP.setFontAlign((short) sprm.getOperand()); + break; + case 0x3b: + //obsolete + break; + case 0x3e: { + // TODO: REMOVEME + byte[] buf = Arrays.copyOfRange(sprm.getGrpprl(), sprm.getGrpprlOffset(), sprm.getGrpprlOffset() + (sprm.size() - 3)); + newPAP.setAnld(buf); + break; + } + case 0x3f: + //don't really need this. spec is confusing regarding this + //sprm + byte[] varParam = sprm.getGrpprl(); + int offset = sprm.getGrpprlOffset(); + newPAP.setFPropRMark(varParam[offset] != 0); + newPAP.setIbstPropRMark(LittleEndian.getShort(varParam, offset + 1)); + newPAP.setDttmPropRMark(new DateAndTime(varParam, offset + 3)); + break; + case 0x40: + // This condition commented out, as Word seems to set outline levels even for + // paragraph with other styles than Heading 1..9, even though specification + // does not say so. See bug 49820 for discussion. + //if (newPAP.getIstd () < 1 && newPAP.getIstd () > 9) + { + newPAP.setLvl((byte) sprm.getOperand()); + } break; - case 0x2e: - newPAP.setDyaFromText (sprm.getOperand()); - break; - case 0x2f: - newPAP.setDxaFromText (sprm.getOperand()); - break; - case 0x30: - newPAP.setFLocked (sprm.getOperand() != 0); - break; - case 0x31: - newPAP.setFWidowControl (sprm.getOperand() != 0); - break; - case 0x33: - newPAP.setFKinsoku (sprm.getOperand() != 0); - break; - case 0x34: - newPAP.setFWordWrap (sprm.getOperand() != 0); - break; - case 0x35: - newPAP.setFOverflowPunct (sprm.getOperand() != 0); - break; - case 0x36: - newPAP.setFTopLinePunct (sprm.getOperand() != 0); - break; - case 0x37: - newPAP.setFAutoSpaceDE (sprm.getOperand() != 0); - break; - case 0x38: - newPAP.setFAutoSpaceDN (sprm.getOperand() != 0); - break; - case 0x39: - newPAP.setWAlignFont (sprm.getOperand()); - break; - case 0x3a: - newPAP.setFontAlign ((short) sprm.getOperand()); - break; - case 0x3b: - //obsolete - break; - case 0x3e: { - // TODO: REMOVEME - byte[] buf = Arrays.copyOfRange(sprm.getGrpprl(), sprm.getGrpprlOffset(), sprm.getGrpprlOffset() + (sprm.size() - 3)); - newPAP.setAnld(buf); - break; - } - case 0x3f: - //don't really need this. spec is confusing regarding this - //sprm - byte[] varParam = sprm.getGrpprl(); - int offset = sprm.getGrpprlOffset(); - newPAP.setFPropRMark (varParam[offset] != 0 ); - newPAP.setIbstPropRMark (LittleEndian.getShort (varParam, offset + 1)); - newPAP.setDttmPropRMark (new DateAndTime(varParam, offset + 3)); - break; - case 0x40: - // This condition commented out, as Word seems to set outline levels even for - // paragraph with other styles than Heading 1..9, even though specification - // does not say so. See bug 49820 for discussion. - //if (newPAP.getIstd () < 1 && newPAP.getIstd () > 9) - { - newPAP.setLvl ((byte) sprm.getOperand()); - } - break; - case 0x41: - // sprmPFBiDi - newPAP.setFBiDi(sprm.getOperand() != 0); - break; - case 0x43: + case 0x41: + // sprmPFBiDi + newPAP.setFBiDi(sprm.getOperand() != 0); + break; + case 0x43: - //pap.fNumRMIns - newPAP.setFNumRMIns (sprm.getOperand() != 0); - break; - case 0x44: + //pap.fNumRMIns + newPAP.setFNumRMIns(sprm.getOperand() != 0); + break; + case 0x44: - //undocumented - break; - case 0x45: - if (sprm.getSizeCode() == 6) - { - byte[] buf = new byte[sprm.size() - 3]; - System.arraycopy(buf, 0, sprm.getGrpprl(), sprm.getGrpprlOffset(), buf.length); - newPAP.setNumrm (buf); - } - else - { - /**@todo handle large PAPX from data stream*/ - } - break; + //undocumented + break; + case 0x45: + if (sprm.getSizeCode() == 6) { + byte[] buf = new byte[sprm.size() - 3]; + System.arraycopy(buf, 0, sprm.getGrpprl(), sprm.getGrpprlOffset(), buf.length); + newPAP.setNumrm(buf); + } else { + /**@todo handle large PAPX from data stream*/ + } + break; - case 0x47: - newPAP.setFUsePgsuSettings (sprm.getOperand() != 0); - break; - case 0x48: - newPAP.setFAdjustRight (sprm.getOperand() != 0); - break; - case 0x49: - // sprmPItap -- 0x6649 - newPAP.setItap( sprm.getOperand() ); - break; - case 0x4a: - // sprmPDtap -- 0x664a - newPAP.setItap( (byte) ( newPAP.getItap() + sprm.getOperand() ) ); - break; - case 0x4b: - // sprmPFInnerTableCell -- 0x244b - newPAP.setFInnerTableCell( sprm.getOperand() != 0); - break; - case 0x4c: - // sprmPFInnerTtp -- 0x244c - newPAP.setFTtpEmbedded( sprm.getOperand() != 0); - break; - case 0x4d: - // sprmPShd -- 0xc64d - ShadingDescriptor shadingDescriptor = new ShadingDescriptor( - sprm.getGrpprl(), 3 ); - newPAP.setShading( shadingDescriptor ); - break; - case 0x5d: - // sprmPDxaRight -- 0x845d - newPAP.setDxaRight( sprm.getOperand() ); - break; - case 0x5e: - // sprmPDxaLeft -- 0x845e - newPAP.setDxaLeft( sprm.getOperand() ); - break; - case 0x60: - // sprmPDxaLeft1 -- 0x8460 - newPAP.setDxaLeft1( sprm.getOperand() ); - break; - case 0x61: - // sprmPJc - newPAP.setJustificationLogical((byte) sprm.getOperand()); - break; - case 0x67: - // sprmPRsid -- 0x6467 - newPAP.setRsid( sprm.getOperand() ); - break; - default: - LOG.atDebug().log("Unknown PAP sprm ignored: {}", sprm); - break; + case 0x47: + newPAP.setFUsePgsuSettings(sprm.getOperand() != 0); + break; + case 0x48: + newPAP.setFAdjustRight(sprm.getOperand() != 0); + break; + case 0x49: + // sprmPItap -- 0x6649 + newPAP.setItap(sprm.getOperand()); + break; + case 0x4a: + // sprmPDtap -- 0x664a + newPAP.setItap((byte) (newPAP.getItap() + sprm.getOperand())); + break; + case 0x4b: + // sprmPFInnerTableCell -- 0x244b + newPAP.setFInnerTableCell(sprm.getOperand() != 0); + break; + case 0x4c: + // sprmPFInnerTtp -- 0x244c + newPAP.setFTtpEmbedded(sprm.getOperand() != 0); + break; + case 0x4d: + // sprmPShd -- 0xc64d + ShadingDescriptor shadingDescriptor = new ShadingDescriptor( + sprm.getGrpprl(), 3); + newPAP.setShading(shadingDescriptor); + break; + case 0x5d: + // sprmPDxaRight -- 0x845d + newPAP.setDxaRight(sprm.getOperand()); + break; + case 0x5e: + // sprmPDxaLeft -- 0x845e + newPAP.setDxaLeft(sprm.getOperand()); + break; + case 0x60: + // sprmPDxaLeft1 -- 0x8460 + newPAP.setDxaLeft1(sprm.getOperand()); + break; + case 0x61: + // sprmPJc + newPAP.setJustificationLogical((byte) sprm.getOperand()); + break; + case 0x67: + // sprmPRsid -- 0x6467 + newPAP.setRsid(sprm.getOperand()); + break; + default: + LOG.atDebug().log("Unknown PAP sprm ignored: {}", sprm); + break; } - } + } - private static void handleTabs(ParagraphProperties pap, SprmOperation sprm) - { - byte[] grpprl = sprm.getGrpprl(); - int offset = sprm.getGrpprlOffset(); - int delSize = grpprl[offset++]; - int[] tabPositions = pap.getRgdxaTab(); - TabDescriptor[] tabDescriptors = pap.getRgtbd(); + private static void handleTabs(ParagraphProperties pap, SprmOperation sprm) { + byte[] grpprl = sprm.getGrpprl(); + int offset = sprm.getGrpprlOffset(); + int delSize = grpprl[offset++]; + int[] tabPositions = pap.getRgdxaTab(); + TabDescriptor[] tabDescriptors = pap.getRgtbd(); - Map<Integer, TabDescriptor> tabMap = new HashMap<>(); - for (int x = 0; x < tabPositions.length; x++) - { - tabMap.put(tabPositions[x], tabDescriptors[x]); - } + Map<Integer, TabDescriptor> tabMap = new HashMap<>(); + for (int x = 0; x < tabPositions.length; x++) { + tabMap.put(tabPositions[x], tabDescriptors[x]); + } - for (int x = 0; x < delSize; x++) - { - tabMap.remove((int) LittleEndian.getShort(grpprl, offset)); - offset += LittleEndianConsts.SHORT_SIZE; - } + for (int x = 0; x < delSize; x++) { + tabMap.remove((int) LittleEndian.getShort(grpprl, offset)); + offset += LittleEndianConsts.SHORT_SIZE; + } - int addSize = grpprl[offset++]; - int start = offset; - for (int x = 0; x < addSize; x++) - { - Integer key = (int) LittleEndian.getShort(grpprl, offset); - TabDescriptor val = new TabDescriptor( grpprl, start + ((TBDAbstractType.getSize() * addSize) + x) ); - tabMap.put(key, val); - offset += LittleEndianConsts.SHORT_SIZE; - } + int addSize = grpprl[offset++]; + int start = offset; + for (int x = 0; x < addSize; x++) { + Integer key = (int) LittleEndian.getShort(grpprl, offset); + TabDescriptor val = new TabDescriptor(grpprl, start + ((TBDAbstractType.getSize() * addSize) + x)); + tabMap.put(key, val); + offset += LittleEndianConsts.SHORT_SIZE; + } - tabPositions = new int[tabMap.size()]; - tabDescriptors = new TabDescriptor[tabPositions.length]; + tabPositions = new int[tabMap.size()]; + tabDescriptors = new TabDescriptor[tabPositions.length]; - List<Integer> list = new ArrayList<>(tabMap.keySet()); - Collections.sort(list); + List<Integer> list = new ArrayList<>(tabMap.keySet()); + Collections.sort(list); - for (int x = 0; x < tabPositions.length; x++) - { - Integer key = list.get(x); - tabPositions[x] = key; - if (tabMap.containsKey( key )) - tabDescriptors[x] = tabMap.get(key); - else - tabDescriptors[x] = new TabDescriptor(); - } + for (int x = 0; x < tabPositions.length; x++) { + Integer key = list.get(x); + tabPositions[x] = key; + if (tabMap.containsKey(key)) + tabDescriptors[x] = tabMap.get(key); + else + tabDescriptors[x] = new TabDescriptor(); + } - pap.setRgdxaTab(tabPositions); - pap.setRgtbd(tabDescriptors); - } + pap.setRgdxaTab(tabPositions); + pap.setRgtbd(tabDescriptors); + } } diff --git a/poi-scratchpad/src/main/java9/module-info.java b/poi-scratchpad/src/main/java9/module-info.java index ea505f6c1c..10e92f26aa 100644 --- a/poi-scratchpad/src/main/java9/module-info.java +++ b/poi-scratchpad/src/main/java9/module-info.java @@ -21,6 +21,7 @@ module org.apache.poi.scratchpad { requires commons.math3; requires org.apache.commons.io; requires org.apache.commons.codec; + requires org.apache.commons.collections4; requires org.apache.logging.log4j; uses org.apache.poi.sl.usermodel.MetroShapeProvider; diff --git a/poi-scratchpad/src/test/java/org/apache/poi/hslf/model/TestLine.java b/poi-scratchpad/src/test/java/org/apache/poi/hslf/model/TestLine.java index 0384b19043..e26793bde5 100644 --- a/poi-scratchpad/src/test/java/org/apache/poi/hslf/model/TestLine.java +++ b/poi-scratchpad/src/test/java/org/apache/poi/hslf/model/TestLine.java @@ -18,6 +18,8 @@ package org.apache.poi.hslf.model; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertNotNull; import java.awt.Color; import java.awt.Rectangle; @@ -27,9 +29,11 @@ import java.util.Arrays; import org.apache.poi.hslf.HSLFTestDataSamples; import org.apache.poi.hslf.usermodel.HSLFLine; +import org.apache.poi.hslf.usermodel.HSLFPlaceholder; import org.apache.poi.hslf.usermodel.HSLFShape; import org.apache.poi.hslf.usermodel.HSLFSlide; import org.apache.poi.hslf.usermodel.HSLFSlideShow; +import org.apache.poi.hslf.usermodel.HSLFTextBox; import org.apache.poi.sl.usermodel.StrokeStyle.LineCompound; import org.apache.poi.sl.usermodel.StrokeStyle.LineDash; import org.junit.jupiter.api.Test; @@ -62,9 +66,14 @@ public final class TestLine { @Test void testCreateLines() throws IOException { + final String title = "Lines tester"; try (HSLFSlideShow ppt1 = new HSLFSlideShow()) { HSLFSlide slide1 = ppt1.createSlide(); - slide1.addTitle().setText("Lines tester"); + HSLFTextBox titleBox = slide1.addTitle(); + titleBox.setText(title); + assertInstanceOf(HSLFPlaceholder.class, titleBox); + HSLFPlaceholder pl = (HSLFPlaceholder) titleBox; + assertNotNull(pl.getPlaceholder()); for (Object[] line : lines) { HSLFLine hslfLine = new HSLFLine(); @@ -85,6 +94,7 @@ public final class TestLine { try (HSLFSlideShow ppt2 = HSLFTestDataSamples.writeOutAndReadBack(ppt1)) { HSLFSlide slide2 = ppt2.getSlides().get(0); + assertEquals(title, slide2.getTitle()); int idx = 0; for (HSLFShape shape : slide2.getShapes().subList(1,14)) { diff --git a/poi-scratchpad/src/test/java/org/apache/poi/hslf/usermodel/TestBugs.java b/poi-scratchpad/src/test/java/org/apache/poi/hslf/usermodel/TestBugs.java index 1cd5be3cf6..575d443b5b 100644 --- a/poi-scratchpad/src/test/java/org/apache/poi/hslf/usermodel/TestBugs.java +++ b/poi-scratchpad/src/test/java/org/apache/poi/hslf/usermodel/TestBugs.java @@ -68,19 +68,10 @@ import org.apache.poi.poifs.filesystem.POIFSFileSystem; import org.apache.poi.poifs.macros.VBAMacroReader; import org.apache.poi.sl.draw.DrawPaint; import org.apache.poi.sl.extractor.SlideShowExtractor; -import org.apache.poi.sl.usermodel.ColorStyle; -import org.apache.poi.sl.usermodel.PaintStyle; +import org.apache.poi.sl.usermodel.*; import org.apache.poi.sl.usermodel.PaintStyle.SolidPaint; import org.apache.poi.sl.usermodel.PictureData.PictureType; -import org.apache.poi.sl.usermodel.Placeholder; -import org.apache.poi.sl.usermodel.ShapeType; -import org.apache.poi.sl.usermodel.Slide; -import org.apache.poi.sl.usermodel.SlideShow; -import org.apache.poi.sl.usermodel.SlideShowFactory; -import org.apache.poi.sl.usermodel.TextBox; -import org.apache.poi.sl.usermodel.TextParagraph; import org.apache.poi.sl.usermodel.TextParagraph.TextAlign; -import org.apache.poi.sl.usermodel.TextRun; import org.apache.poi.util.LittleEndian; import org.apache.poi.util.StringUtil; import org.apache.poi.util.Units; @@ -904,4 +895,22 @@ public final class TestBugs { assertEquals(ShapeType.NOT_PRIMITIVE, shList.get(2).getShapeType()); } } + + @Test + void test69697() throws Exception { + try (HSLFSlideShow ppt = open("bug69697.ppt")) { + HSLFSlide slide = ppt.getSlides().get(0); + for (HSLFShape sh : slide.getShapes()) { + if (sh instanceof HSLFPictureShape) { + HSLFPictureShape pict = (HSLFPictureShape) sh; + HSLFPictureData pictData = pict.getPictureData(); + assertNotNull(pictData, "PictureData should not be null for shape: " + pict.getShapeName()); + byte[] data = pictData.getData(); + assertNotNull(data, "Picture data should not be null for shape: " + pict.getShapeName()); + PictureData.PictureType type = pictData.getType(); + assertNotNull(type, "Picture type should not be null for shape: " + pict.getShapeName()); + } + } + } + } } diff --git a/poi-scratchpad/src/test/java/org/apache/poi/hslf/usermodel/TestPictures.java b/poi-scratchpad/src/test/java/org/apache/poi/hslf/usermodel/TestPictures.java index 2b90916775..5474c7f8d0 100644 --- a/poi-scratchpad/src/test/java/org/apache/poi/hslf/usermodel/TestPictures.java +++ b/poi-scratchpad/src/test/java/org/apache/poi/hslf/usermodel/TestPictures.java @@ -29,6 +29,8 @@ import java.awt.geom.Dimension2D; import java.awt.image.BufferedImage; import java.io.ByteArrayInputStream; import java.io.IOException; +import java.net.URI; +import java.net.URISyntaxException; import java.net.URL; import java.util.Arrays; import java.util.Collections; @@ -271,9 +273,9 @@ public final class TestPictures { @Test @Disabled("requires an internet connection to a 3rd party site") // As of 2017-06-20, the file still exists at the specified URL and the test passes. - void testZeroPictureLength() throws IOException { + void testZeroPictureLength() throws IOException, URISyntaxException { // take the data from www instead of test directory - URL url = new URL("http://www.cs.sfu.ca/~anoop/courses/CMPT-882-Fall-2002/chris.ppt"); + URL url = new URI("http://www.cs.sfu.ca/~anoop/courses/CMPT-882-Fall-2002/chris.ppt").toURL(); HSLFSlideShowImpl hslf = new HSLFSlideShowImpl(url.openStream()); /* Assume that the file could retrieved... InputStream is; diff --git a/poi-scratchpad/src/test/java9/module-info.java b/poi-scratchpad/src/test/java9/module-info.java index 35dbc01a3e..748a2244a7 100644 --- a/poi-scratchpad/src/test/java9/module-info.java +++ b/poi-scratchpad/src/test/java9/module-info.java @@ -21,6 +21,7 @@ module org.apache.poi.scratchpad { requires commons.math3; requires org.apache.commons.io; requires org.apache.commons.codec; + requires org.apache.commons.collections4; requires org.apache.logging.log4j; uses org.apache.poi.sl.usermodel.MetroShapeProvider; diff --git a/poi/build.gradle b/poi/build.gradle index 2c6c7c542f..2b1076840e 100644 --- a/poi/build.gradle +++ b/poi/build.gradle @@ -37,7 +37,7 @@ sourceSets { dependencies { api "commons-codec:commons-codec:${commonsCodecVersion}" - api 'org.apache.commons:commons-collections4:4.4' + api 'org.apache.commons:commons-collections4:4.5.0' api "org.apache.commons:commons-math3:${commonsMathVersion}" api "commons-io:commons-io:${commonsIoVersion}" api 'com.zaxxer:SparseBitSet:1.3' @@ -56,7 +56,7 @@ dependencies { } // generate and compile the file Version.java file -task generateVersionJava() { +tasks.register('generateVersionJava') { //dependsOn ':poi-ooxml:build', ':poi-integration:build', ':poi-excelant:build' File fileIn = file("src/main/version/Version.java.template") @@ -80,7 +80,7 @@ final Pattern MODULE_NOT_REGEX = ~'(poi[/\\\\][^/\\\\]+$|batik-script)' final Pattern MODULE_REGEX = ~'\\.jar$' final List MODULE_PATH = sourceSets.test.runtimeClasspath.findAll{ it.path =~ MODULE_REGEX && !(it.path =~ MODULE_NOT_REGEX) }.collect{ it.parent }.unique() -task compileJava9(type: JavaCompile) { +tasks.register('compileJava9', JavaCompile) { dependsOn 'compileJava' javaCompiler = javaToolchains.compilerFor { @@ -92,12 +92,12 @@ task compileJava9(type: JavaCompile) { source = file(JAVA9_SRC) classpath = files() options.compilerArgs = [ - '--patch-module', "${MODULE_NAME}=${sourceSets.main.output.classesDirs.asPath}", - '--module-path', sourceSets.main.compileClasspath.asPath + '--patch-module', "${MODULE_NAME}=${sourceSets.main.output.classesDirs.asPath}", + '--module-path', sourceSets.main.compileClasspath.asPath ] } -task compileTest9(type: JavaCompile) { +tasks.register('compileTest9', JavaCompile) { dependsOn 'compileTestJava' javaCompiler = javaToolchains.compilerFor { @@ -108,8 +108,8 @@ task compileTest9(type: JavaCompile) { destinationDirectory = file(TEST9_OUT + VERSIONS9) source = file(TEST9_SRC) options.compilerArgs = [ - '--patch-module', "${MODULE_NAME}=${(sourceSets.main.output.classesDirs + sourceSets.test.output.classesDirs).asPath}", - '--module-path', files(MODULE_PATH).asPath + '--patch-module', "${MODULE_NAME}=${(sourceSets.main.output.classesDirs + sourceSets.test.output.classesDirs).asPath}", + '--module-path', files(MODULE_PATH).asPath ] classpath = files() } @@ -129,7 +129,7 @@ task testJar(type: Jar, dependsOn: [ testClasses, compileTest9 ]) { setArchiveClassifier 'tests' // ignore second module-info.class from main - duplicatesStrategy = 'exclude' + duplicatesStrategy = DuplicatesStrategy.EXCLUDE from sourceSets.test.output + sourceSets.main.output diff --git a/poi/src/main/java/org/apache/poi/POIException.java b/poi/src/main/java/org/apache/poi/POIException.java new file mode 100644 index 0000000000..ef656b6598 --- /dev/null +++ b/poi/src/main/java/org/apache/poi/POIException.java @@ -0,0 +1,59 @@ +/* ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ +package org.apache.poi; + +/** + * Indicates a generic POI exception. This is not commonly used in POI + * but this is intended to be a base class for some new POI exceptions. + * Historically, POI has used {@link RuntimeException} for most of its + * exceptions, but this is not a good practice. This class is a checked + * class that extends {@link Exception} so needs to be explicitly + * caught or declared in the method signature. + * + * @since POI 5.5.0 + */ +public class POIException extends Exception { + private static final long serialVersionUID = 1L; + + /** + * Create a new {@code POIException} with the specified message. + * + * @param msg The error message for the exception. + */ + public POIException(String msg) { + super(msg); + } + + /** + * Create a new {@code POIException} with the specified cause. + * + * @param cause the cause of this exception + */ + public POIException(Throwable cause) { + super(cause); + } + + /** + * Create a new {@code POIException} with the specified message and cause. + * + * @param msg The error message for the exception. + * @param cause the cause of this exception + */ + public POIException(String msg, Throwable cause) { + super(msg, cause); + } +} diff --git a/poi/src/main/java/org/apache/poi/hpsf/ClassID.java b/poi/src/main/java/org/apache/poi/hpsf/ClassID.java index 7e0ec5e2d8..688fd6fa0c 100644 --- a/poi/src/main/java/org/apache/poi/hpsf/ClassID.java +++ b/poi/src/main/java/org/apache/poi/hpsf/ClassID.java @@ -109,11 +109,12 @@ public class ClassID implements Duplicatable, GenericRecord { /** * Gets the bytes making out the class ID. They are returned in correct order, i.e. big-endian. + * This no longer returns a reference to the internal byte array, but a copy of it. * * @return the bytes making out the class ID. */ public byte[] getBytes() { - return bytes; + return bytes.clone(); } /** @@ -152,7 +153,7 @@ public class ClassID implements Duplicatable, GenericRecord { /* Read 8 bytes. */ System.arraycopy(src, 8 + offset, bytes, 8, 8); - return bytes; + return bytes.clone(); } /** diff --git a/poi/src/main/java/org/apache/poi/hssf/extractor/EventBasedExcelExtractor.java b/poi/src/main/java/org/apache/poi/hssf/extractor/EventBasedExcelExtractor.java index f9af178a5a..aa58173db6 100644 --- a/poi/src/main/java/org/apache/poi/hssf/extractor/EventBasedExcelExtractor.java +++ b/poi/src/main/java/org/apache/poi/hssf/extractor/EventBasedExcelExtractor.java @@ -58,7 +58,7 @@ import org.apache.poi.poifs.filesystem.POIFSFileSystem; * the XLS2CSVmra example * </p> * - * @see <a href="http://svn.apache.org/repos/asf/poi/trunk/src/examples/src/org/apache/poi/hssf/eventusermodel/examples/XLS2CSVmra.java">XLS2CSVmra</a> + * @see <a href="https://github.com/apache/poi/blob/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/eventusermodel/XLS2CSVmra.java">XLS2CSVmra</a> */ public class EventBasedExcelExtractor implements POIOLE2TextExtractor, org.apache.poi.ss.extractor.ExcelExtractor { private final POIFSFileSystem poifs; diff --git a/poi/src/main/java/org/apache/poi/hssf/extractor/ExcelExtractor.java b/poi/src/main/java/org/apache/poi/hssf/extractor/ExcelExtractor.java index 3f413b0643..fc0e7aa43c 100644 --- a/poi/src/main/java/org/apache/poi/hssf/extractor/ExcelExtractor.java +++ b/poi/src/main/java/org/apache/poi/hssf/extractor/ExcelExtractor.java @@ -51,7 +51,7 @@ import org.apache.poi.ss.usermodel.Row.MissingCellPolicy; * the XLS2CSVmra example * </p> * - * @see <a href="http://svn.apache.org/repos/asf/poi/trunk/poi-examples/src/main/java/org/apache/poi/hssf/eventusermodel/examples/XLS2CSVmra.java">XLS2CSVmra</a> + * @see <a href="https://github.com/apache/poi/blob/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/eventusermodel/XLS2CSVmra.java">XLS2CSVmra</a> */ public class ExcelExtractor implements POIOLE2TextExtractor, org.apache.poi.ss.extractor.ExcelExtractor { private final HSSFWorkbook _wb; diff --git a/poi/src/main/java/org/apache/poi/hssf/record/EscherAggregate.java b/poi/src/main/java/org/apache/poi/hssf/record/EscherAggregate.java index 2c71372ee9..67beb21207 100644 --- a/poi/src/main/java/org/apache/poi/hssf/record/EscherAggregate.java +++ b/poi/src/main/java/org/apache/poi/hssf/record/EscherAggregate.java @@ -1037,11 +1037,7 @@ public final class EscherAggregate extends AbstractEscherHolderRecord { final UnsynchronizedByteArrayOutputStream buffer = UnsynchronizedByteArrayOutputStream.builder().get(); void addBytes(byte[] data) { - try { - buffer.write(data); - } catch (IOException e) { - throw new IllegalStateException("Couldn't get data from drawing/continue records", e); - } + buffer.write(data); } @Override diff --git a/poi/src/main/java/org/apache/poi/hssf/record/TextObjectRecord.java b/poi/src/main/java/org/apache/poi/hssf/record/TextObjectRecord.java index 17bcce71e7..d4a303f873 100644 --- a/poi/src/main/java/org/apache/poi/hssf/record/TextObjectRecord.java +++ b/poi/src/main/java/org/apache/poi/hssf/record/TextObjectRecord.java @@ -212,7 +212,7 @@ public final class TextObjectRecord extends ContinuableRecord { protected void serialize(ContinuableRecordOutput out) { serializeTXORecord(out); - if (_text.getString().length() > 0) { + if (!_text.getString().isEmpty()) { serializeTrailingRecords(out); } } diff --git a/poi/src/main/java/org/apache/poi/hssf/record/WriteAccessRecord.java b/poi/src/main/java/org/apache/poi/hssf/record/WriteAccessRecord.java index 88f8affd2d..712693554c 100644 --- a/poi/src/main/java/org/apache/poi/hssf/record/WriteAccessRecord.java +++ b/poi/src/main/java/org/apache/poi/hssf/record/WriteAccessRecord.java @@ -108,10 +108,19 @@ public final class WriteAccessRecord extends StandardRecord { data = IOUtils.safelyAllocate(in.remaining(), STRING_SIZE); in.readFully(data); if (UTF16FLAG.isSet(is16BitFlag)) { - byteCnt = Math.min(nChars * 2, data.length); + // the spec only allows up to 109 bytes for the string in this record, but it seems some broken + // software out there will generate invalid records + int min = Math.min(nChars * 2, data.length); + + // make sure byteCnt is divisible by 2 as we read UTF-16LE + byteCnt = min - (min % 2); + charset = StandardCharsets.UTF_16LE; } else { + // the spec only allows up to 109 bytes for the string in this record, but it seems some broken + // software out there will generate invalid records byteCnt = Math.min(nChars, data.length); + charset = StandardCharsets.ISO_8859_1; } } @@ -130,7 +139,8 @@ public final class WriteAccessRecord extends StandardRecord { boolean is16bit = StringUtil.hasMultibyte(username); int encodedByteCount = username.length() * (is16bit ? 2 : 1); if (encodedByteCount > STRING_SIZE) { - throw new IllegalArgumentException("Name is too long: " + username); + throw new IllegalArgumentException("Name is too long, expecting up to " + STRING_SIZE + + " bytes, but had: " + encodedByteCount + " bytes: " + username); } field_1_username = username; diff --git a/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFCell.java b/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFCell.java index ac67a459a4..fd4f97365d 100644 --- a/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFCell.java +++ b/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFCell.java @@ -17,7 +17,6 @@ package org.apache.poi.hssf.usermodel; -import java.text.SimpleDateFormat; import java.time.LocalDateTime; import java.util.Calendar; import java.util.Date; @@ -48,6 +47,7 @@ import org.apache.poi.ss.usermodel.CellStyle; import org.apache.poi.ss.usermodel.CellType; import org.apache.poi.ss.usermodel.CellValue; import org.apache.poi.ss.usermodel.Comment; +import org.apache.poi.ss.usermodel.DataFormatter; import org.apache.poi.ss.usermodel.DateUtil; import org.apache.poi.ss.usermodel.FormulaError; import org.apache.poi.ss.usermodel.Hyperlink; @@ -55,7 +55,6 @@ import org.apache.poi.ss.usermodel.RichTextString; import org.apache.poi.ss.util.CellRangeAddress; import org.apache.poi.ss.util.CellReference; import org.apache.poi.ss.util.NumberToTextConverter; -import org.apache.poi.util.LocaleUtil; /** * High level representation of a cell in a row of a spreadsheet. @@ -271,7 +270,7 @@ public class HSSFCell extends CellBase { * */ - private void setCellType(CellType cellType, boolean setValue, int row,short col, short styleIndex) + private void setCellType(CellType cellType, boolean setValue, int row, short col, short styleIndex) { switch (cellType) { @@ -1038,21 +1037,20 @@ public class HSSFCell extends CellBase { case BLANK: return ""; case BOOLEAN: - return getBooleanCellValue()?"TRUE":"FALSE"; + return getBooleanCellValue() ? "TRUE" : "FALSE"; case ERROR: return ErrorEval.getText((( BoolErrRecord ) _record).getErrorValue()); case FORMULA: return getCellFormula(); case NUMERIC: - //TODO apply the dataformat for this cell if (DateUtil.isCellDateFormatted(this)) { - SimpleDateFormat sdf = new SimpleDateFormat("dd-MMM-yyyy", LocaleUtil.getUserLocale()); - sdf.setTimeZone(LocaleUtil.getUserTimeZone()); - return sdf.format(getDateCellValue()); + DataFormatter df = new DataFormatter(); + df.setUseCachedValuesForFormulaCells(true); + return df.formatCellValue(this); } - return String.valueOf(getNumericCellValue()); + return Double.toString(getNumericCellValue()); case STRING: - return getStringCellValue(); + return getRichStringCellValue().toString(); default: return "Unknown Cell Type: " + getCellType(); } diff --git a/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFCellStyle.java b/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFCellStyle.java index 0983c45497..20d3bcaf6e 100644 --- a/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFCellStyle.java +++ b/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFCellStyle.java @@ -35,6 +35,7 @@ import org.apache.poi.ss.usermodel.FillPatternType; import org.apache.poi.ss.usermodel.Font; import org.apache.poi.ss.usermodel.HorizontalAlignment; import org.apache.poi.ss.usermodel.VerticalAlignment; +import org.apache.poi.ss.util.CellUtil; import org.apache.poi.util.Removal; import org.apache.poi.util.ThreadLocalUtil; @@ -49,22 +50,29 @@ public final class HSSFCellStyle implements CellStyle, Duplicatable { private final ExtendedFormatRecord _format; private final short _index; private final InternalWorkbook _workbook; + private final HSSFWorkbook _hssfWorkbook; - - /** Creates new HSSFCellStyle why would you want to do this?? */ protected HSSFCellStyle(short index, ExtendedFormatRecord rec, HSSFWorkbook workbook) { - this(index, rec, workbook.getWorkbook()); + _workbook = workbook.getInternalWorkbook(); + _hssfWorkbook = workbook; + _index = index; + _format = rec; } + + @Deprecated + @Removal(version = "7.0.0") protected HSSFCellStyle(short index, ExtendedFormatRecord rec, InternalWorkbook workbook) { _workbook = workbook; + _hssfWorkbook = null; _index = index; - _format = rec; + _format = rec; } protected HSSFCellStyle(HSSFCellStyle other) { _workbook = other._workbook; + _hssfWorkbook = other._hssfWorkbook; _index = other._index; _format = other._format; } @@ -851,9 +859,10 @@ public final class HSSFCellStyle implements CellStyle, Duplicatable { if(source instanceof HSSFCellStyle) { this.cloneStyleFrom((HSSFCellStyle)source); } else { - throw new IllegalArgumentException("Can only clone from one HSSFCellStyle to another, not between HSSFCellStyle and XSSFCellStyle"); + CellUtil.cloneStyle(source, this, _hssfWorkbook); } } + public void cloneStyleFrom(HSSFCellStyle source) { // First we need to clone the extended format // record diff --git a/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFName.java b/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFName.java index 75d8c0a303..60fdffa599 100644 --- a/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFName.java +++ b/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFName.java @@ -180,7 +180,7 @@ public final class HSSFName implements Name { */ private static void validateName(String name) { - if (name.length() == 0) { + if (name.isEmpty()) { throw new IllegalArgumentException("Name cannot be blank"); } if (name.length() > 255) { diff --git a/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFSheet.java b/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFSheet.java index bba313f57d..9e56f37714 100644 --- a/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFSheet.java +++ b/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFSheet.java @@ -645,7 +645,7 @@ public final class HSSFSheet implements Sheet { } ExtendedFormatRecord xf = _book.getExFormatAt(styleIndex); - return new HSSFCellStyle(styleIndex, xf, _book); + return new HSSFCellStyle(styleIndex, xf, _workbook); } /** diff --git a/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFWorkbook.java b/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFWorkbook.java index 0fea271340..6c7bb93a2b 100644 --- a/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFWorkbook.java +++ b/poi/src/main/java/org/apache/poi/hssf/usermodel/HSSFWorkbook.java @@ -234,7 +234,8 @@ public final class HSSFWorkbook extends POIDocument implements Workbook { * @return the max image length allowed for HSSFWorkbook */ public static int getMaxImageLength() { - return MAX_IMAGE_LENGTH; + final int ioMaxSize = IOUtils.getByteArrayMaxOverride(); + return ioMaxSize < 0 ? MAX_IMAGE_LENGTH : Math.min(MAX_IMAGE_LENGTH, ioMaxSize); } /** @@ -1978,7 +1979,7 @@ public final class HSSFWorkbook extends POIDocument implements Workbook { case PICTURE_TYPE_WMF: // remove first 22 bytes if file starts with the WMF placeable header if (FileMagic.valueOf(pictureData) == FileMagic.WMF) { - pictureData = IOUtils.safelyClone(pictureData, 22, pictureData.length - 22, MAX_IMAGE_LENGTH); + pictureData = IOUtils.safelyClone(pictureData, 22, pictureData.length - 22, getMaxImageLength()); } // fall through case PICTURE_TYPE_EMF: diff --git a/poi/src/main/java/org/apache/poi/hssf/usermodel/HeaderFooter.java b/poi/src/main/java/org/apache/poi/hssf/usermodel/HeaderFooter.java index aa883dd44e..3884462587 100644 --- a/poi/src/main/java/org/apache/poi/hssf/usermodel/HeaderFooter.java +++ b/poi/src/main/java/org/apache/poi/hssf/usermodel/HeaderFooter.java @@ -282,7 +282,7 @@ public abstract class HeaderFooter implements org.apache.poi.ss.usermodel.Header int pos; // Check we really got something to work on - if (pText == null || pText.length() == 0) { + if (pText == null || pText.isEmpty()) { return pText; } diff --git a/poi/src/main/java/org/apache/poi/hssf/usermodel/helpers/HSSFRowColShifter.java b/poi/src/main/java/org/apache/poi/hssf/usermodel/helpers/HSSFRowColShifter.java index 698f1d7279..dc68c77dcb 100644 --- a/poi/src/main/java/org/apache/poi/hssf/usermodel/helpers/HSSFRowColShifter.java +++ b/poi/src/main/java/org/apache/poi/hssf/usermodel/helpers/HSSFRowColShifter.java @@ -62,19 +62,19 @@ import static org.apache.logging.log4j.util.Unbox.box; } /** - * Update the formulas in specified row using the formula shifting policy specified by shifter + * Update the formulas in the specified row using the formula shifting policy specified by shifter * * @param row the row to update the formulas on * @param formulaShifter the formula shifting policy */ /*package*/ static void updateRowFormulas(HSSFRow row, FormulaShifter formulaShifter) { - HSSFSheet sheet = row.getSheet(); - for (Cell c : row) { - HSSFCell cell = (HSSFCell) c; - String formula = cell.getCellFormula(); - if (formula.length() > 0) { - String shiftedFormula = shiftFormula(row, formula, formulaShifter); - cell.setCellFormula(shiftedFormula); + for (Cell cell : row) { + if (cell.getCellType() == CellType.FORMULA) { + String formula = cell.getCellFormula(); + if (formula != null && !formula.isEmpty()) { + String shiftedFormula = shiftFormula(row, formula, formulaShifter); + cell.setCellFormula(shiftedFormula); + } } } } diff --git a/poi/src/main/java/org/apache/poi/hssf/util/HSSFColor.java b/poi/src/main/java/org/apache/poi/hssf/util/HSSFColor.java index 263a7c0da9..cc3d3ed796 100644 --- a/poi/src/main/java/org/apache/poi/hssf/util/HSSFColor.java +++ b/poi/src/main/java/org/apache/poi/hssf/util/HSSFColor.java @@ -25,6 +25,7 @@ import java.util.Map; import java.util.Objects; import org.apache.poi.ss.usermodel.Color; +import org.apache.poi.util.Removal; /** @@ -34,7 +35,7 @@ import org.apache.poi.ss.usermodel.Color; * Each color has an index (for the standard palette in Excel (tm) ), * native (RGB) triplet and string triplet. The string triplet is as the * color would be represented by Gnumeric. Having (string) this here is a bit of a - * collision of function between HSSF and the HSSFSerializer but I think its + * collision of function between HSSF and the HSSFSerializer but I think it's * a reasonable one in this case. */ public class HSSFColor implements Color { @@ -42,7 +43,7 @@ public class HSSFColor implements Color { private static Map<Integer,HSSFColor> indexHash; private static Map<HSSFColorPredefined,HSSFColor> enumList; - private final java.awt.Color color; + private final int rgb; private final int index; private final int index2; @@ -110,7 +111,7 @@ public class HSSFColor implements Color { private final HSSFColor color; HSSFColorPredefined(int index, int index2, int rgb) { - this.color = new HSSFColor(index, index2, new java.awt.Color(rgb)); + this.color = new HSSFColor(index, index2, rgb); } /** @@ -145,7 +146,7 @@ public class HSSFColor implements Color { * @return (a copy of) the HSSFColor assigned to the enum */ public HSSFColor getColor() { - return new HSSFColor(getIndex(), getIndex2(), color.color); + return new HSSFColor(getIndex(), getIndex2(), color.rgb); } } @@ -153,13 +154,40 @@ public class HSSFColor implements Color { /** Creates a new instance of HSSFColor */ public HSSFColor() { // automatic index - this(0x40, -1, java.awt.Color.BLACK); + this(0x40, -1, 0x000000); } + /** Constructs new instance of {@code HSSFColor} by + * extracting RGB from {@link java.awt.Color}. The code is equivalent + * to calling: + * <pre> + * new HSSFColor(index, index2, color.getRGB()); + * </pre> + * or specifying {@link #HSSFColor(int, int, int) RGB directly}. + * + * @param index + * @param index2 + * @param color color to extract RGB from + * @deprecated use {@link #HSSFColor(int, int, int)} instead + */ + @Removal(version = "7.0.0") public HSSFColor(int index, int index2, java.awt.Color color) { + this(index, index2, color.getRGB()); + } + + /** Constructs new instance of {@code HSSFColor} by + * specifying RGB as an {@code int} value. Given {@code blue}, {@code green} and + * {@code blue} being byte values between {@code 0x00 to 0xFF}, then + * {@code rgb = blue + (green >> 8) + (red >> 16)}. + * @param index + * @param index2 + * @param rgb combined value of RGB + * @since POI 5.5.0 + */ + public HSSFColor(int index, int index2, int rgb) { this.index = index; this.index2 = index2; - this.color = color; + this.rgb = 0xFF000000 | rgb; } /** @@ -203,7 +231,7 @@ public class HSSFColor implements Color { } /** - * this function returns all colors in a hastable. It's not implemented as a + * This function returns all colors in a map. It's not implemented as a * static member/statically initialized because that would be dirty in a * server environment as it is intended. This means you'll eat the time * it takes to create it once per request but you will not hold onto it @@ -235,7 +263,7 @@ public class HSSFColor implements Color { private static synchronized Map<HSSFColorPredefined,HSSFColor> mapEnumToColorClass() { if (enumList == null) { enumList = new EnumMap<>(HSSFColorPredefined.class); - // AUTOMATIC is not add to list + // AUTOMATIC is not added to list addHSSFColorPredefined(HSSFColorPredefined.BLACK); addHSSFColorPredefined(HSSFColorPredefined.BROWN); addHSSFColorPredefined(HSSFColorPredefined.OLIVE_GREEN); @@ -315,7 +343,7 @@ public class HSSFColor implements Color { */ public short [] getTriplet() { - return new short[] { (short)color.getRed(), (short)color.getGreen(), (short)color.getBlue() }; + return new short[] { getRed(), getGreen(), getBlue() }; } /** @@ -324,9 +352,19 @@ public class HSSFColor implements Color { */ public String getHexString() { - return (Integer.toHexString(color.getRed()*0x101) + ":" + - Integer.toHexString(color.getGreen()*0x101) + ":" + - Integer.toHexString(color.getBlue()*0x101)).toUpperCase(Locale.ROOT); + return (Integer.toHexString(getRed()*0x101) + ":" + + Integer.toHexString(getGreen()*0x101) + ":" + + Integer.toHexString(getBlue()*0x101)).toUpperCase(Locale.ROOT); + } + + private final short getBlue() { + return (short) (rgb & 0xFF); + } + private final short getGreen() { + return (short) ((rgb >> 8) & 0xFF); + } + private final short getRed() { + return (short) ((rgb >> 16) & 0xFF); } @Override @@ -338,12 +376,12 @@ public class HSSFColor implements Color { if (index != hssfColor.index) return false; if (index2 != hssfColor.index2) return false; - return Objects.equals(color, hssfColor.color); + return Objects.equals(rgb, hssfColor.rgb); } @Override public int hashCode() { - return Objects.hash(color,index,index2); + return Objects.hash(rgb, index, index2); } /** diff --git a/poi/src/main/java/org/apache/poi/poifs/dev/POIFSDump.java b/poi/src/main/java/org/apache/poi/poifs/dev/POIFSDump.java index d29745ea82..fdf6bb85f4 100644 --- a/poi/src/main/java/org/apache/poi/poifs/dev/POIFSDump.java +++ b/poi/src/main/java/org/apache/poi/poifs/dev/POIFSDump.java @@ -71,7 +71,7 @@ public final class POIFSDump { DirectoryEntry root = fs.getRoot(); String filenameWithoutPath = new File(filename).getName(); File dumpDir = new File(filenameWithoutPath + "_dump"); - File file = new File(dumpDir, root.getName()); + File file = IOUtils.newFile(dumpDir, root.getName()); if (!file.exists() && !file.mkdirs()) { throw new IOException("Could not create directory " + file); } @@ -104,13 +104,14 @@ public final class POIFSDump { try (DocumentInputStream is = new DocumentInputStream(node)) { bytes = IOUtils.toByteArray(is); } - try (OutputStream out = Files.newOutputStream(new File(parent, node.getName().trim()).toPath())) { + try (OutputStream out = Files.newOutputStream( + IOUtils.newFile(parent, node.getName().trim()).toPath())) { out.write(bytes); } } else if (entry instanceof DirectoryEntry){ DirectoryEntry dir = (DirectoryEntry)entry; - File file = new File(parent, entry.getName()); - if(!file.exists() && !file.mkdirs()) { + File file = IOUtils.newFile(parent, entry.getName()); + if (!file.exists() && !file.mkdirs()) { throw new IOException("Could not create directory " + file); } dump(dir, file); @@ -119,8 +120,9 @@ public final class POIFSDump { } } } + public static void dump(POIFSFileSystem fs, int startBlock, String name, File parent) throws IOException { - File file = new File(parent, name); + File file = IOUtils.newFile(parent, name); try (OutputStream out = Files.newOutputStream(file.toPath())) { POIFSStream stream = new POIFSStream(fs, startBlock); diff --git a/poi/src/main/java/org/apache/poi/poifs/eventfilesystem/POIFSReader.java b/poi/src/main/java/org/apache/poi/poifs/eventfilesystem/POIFSReader.java index b8d443aab4..4cb3ebb4e2 100644 --- a/poi/src/main/java/org/apache/poi/poifs/eventfilesystem/POIFSReader.java +++ b/poi/src/main/java/org/apache/poi/poifs/eventfilesystem/POIFSReader.java @@ -141,22 +141,23 @@ public class POIFSReader * assumed * @param name the document name * - * @throws NullPointerException if listener is null or name is - * null or empty + * @throws NullPointerException if listener is null or name is null * @throws IllegalStateException if read() has already been - * called + * called or name is empty */ - public void registerListener(final POIFSReaderListener listener, final POIFSDocumentPath path, final String name) { - if ((listener == null) || (name == null) || (name.length() == 0)) { - throw new NullPointerException(); + if (listener == null || name == null) { + throw new NullPointerException("invalid null parameter"); + } + if (name.isEmpty()) { + throw new IllegalStateException("name must not be empty"); } if (registryClosed) { - throw new IllegalStateException(); + throw new IllegalStateException("registry closed"); } - registry.registerListener(listener, (path == null) ? new POIFSDocumentPath() : path, name); + registry.registerListener(listener, path == null ? new POIFSDocumentPath() : path, name); } /** diff --git a/poi/src/main/java/org/apache/poi/poifs/filesystem/DocumentDescriptor.java b/poi/src/main/java/org/apache/poi/poifs/filesystem/DocumentDescriptor.java index b8d783638e..40ffdffaec 100644 --- a/poi/src/main/java/org/apache/poi/poifs/filesystem/DocumentDescriptor.java +++ b/poi/src/main/java/org/apache/poi/poifs/filesystem/DocumentDescriptor.java @@ -46,7 +46,7 @@ public class DocumentDescriptor { throw new NullPointerException("name must not be null"); } - if (name.length() == 0) + if (name.isEmpty()) { throw new IllegalArgumentException("name cannot be empty"); } diff --git a/poi/src/main/java/org/apache/poi/poifs/macros/VBAMacroExtractor.java b/poi/src/main/java/org/apache/poi/poifs/macros/VBAMacroExtractor.java index c0db47e5fb..e5a80e9034 100644 --- a/poi/src/main/java/org/apache/poi/poifs/macros/VBAMacroExtractor.java +++ b/poi/src/main/java/org/apache/poi/poifs/macros/VBAMacroExtractor.java @@ -26,6 +26,7 @@ import java.nio.file.Files; import java.util.Map; import java.util.Map.Entry; +import org.apache.poi.util.IOUtils; import org.apache.poi.util.StringUtil; /** @@ -95,7 +96,7 @@ public class VBAMacroExtractor { System.out.println(); System.out.println(moduleCode); } else { - File out = new File(outputDir, moduleName + extension); + File out = IOUtils.newFile(outputDir, moduleName + extension); try (OutputStream fout = Files.newOutputStream(out.toPath()); OutputStreamWriter fwriter = new OutputStreamWriter(fout, StringUtil.UTF8)) { fwriter.write(moduleCode); diff --git a/poi/src/main/java/org/apache/poi/poifs/property/PropertyTable.java b/poi/src/main/java/org/apache/poi/poifs/property/PropertyTable.java index 203f23cd46..562413e0c6 100644 --- a/poi/src/main/java/org/apache/poi/poifs/property/PropertyTable.java +++ b/poi/src/main/java/org/apache/poi/poifs/property/PropertyTable.java @@ -83,11 +83,14 @@ public final class PropertyTable implements BATManaged { for (ByteBuffer bb : dataSource) { // Turn it into an array - byte[] data; - if (bb.hasArray() && bb.arrayOffset() == 0 && - bb.array().length == _bigBigBlockSize.getBigBlockSize()) { - data = bb.array(); - } else { + byte[] data = null; + if (bb.hasArray() && bb.arrayOffset() == 0) { + final byte[] array = bb.array(); + if (array.length == _bigBigBlockSize.getBigBlockSize()) { + data = array; + } + } + if (data == null) { data = IOUtils.safelyAllocate(_bigBigBlockSize.getBigBlockSize(), POIFSFileSystem.getMaxRecordLength()); int toRead = data.length; @@ -108,7 +111,7 @@ public final class PropertyTable implements BATManaged { Property property = _properties.get(0); if (property != null) { if (property instanceof DirectoryProperty) { - populatePropertyTree((DirectoryProperty) property); + populatePropertyTree((DirectoryProperty) property, 0); } else { throw new IOException("Invalid format, cannot convert property " + property + " to DirectoryProperty"); } @@ -224,7 +227,14 @@ public final class PropertyTable implements BATManaged { _header_block.setPropertyCount(countBlocks()); } - private void populatePropertyTree(DirectoryProperty root) throws IOException { + // Maximum depth of the property tree to prevent stackoverflow errors + private static final int MAX_PROPERTY_DEPTH = 1000; + + private void populatePropertyTree(final DirectoryProperty root, final int depth) throws IOException { + if (depth > MAX_PROPERTY_DEPTH) { + throw new IOException("Property tree too deep, likely a corrupt file"); + } + int index = root.getChildIndex(); if (!Property.isValidIndex(index)) { @@ -243,7 +253,7 @@ public final class PropertyTable implements BATManaged { root.addChild(property); if (property.isDirectory()) { - populatePropertyTree(( DirectoryProperty ) property); + populatePropertyTree((DirectoryProperty) property, depth + 1); } index = property.getPreviousChildIndex(); if (isValidIndex(index)) { diff --git a/poi/src/main/java/org/apache/poi/sl/usermodel/AutoNumberingScheme.java b/poi/src/main/java/org/apache/poi/sl/usermodel/AutoNumberingScheme.java index 8f717807c9..3c4a55d878 100644 --- a/poi/src/main/java/org/apache/poi/sl/usermodel/AutoNumberingScheme.java +++ b/poi/src/main/java/org/apache/poi/sl/usermodel/AutoNumberingScheme.java @@ -174,10 +174,10 @@ public enum AutoNumberingScheme { public String format(int value) { String index = formatIndex(value); String cased = formatCase(index); - return formatSeperator(cased); + return formatSeparator(cased); } - private String formatSeperator(String cased) { + private String formatSeparator(String cased) { String name = name().toLowerCase(Locale.ROOT); if (name.contains("plain")) return cased; if (name.contains("parenright")) return cased+")"; diff --git a/poi/src/main/java/org/apache/poi/ss/format/CellFormatPart.java b/poi/src/main/java/org/apache/poi/ss/format/CellFormatPart.java index 990181baad..d8f59b70a7 100644 --- a/poi/src/main/java/org/apache/poi/ss/format/CellFormatPart.java +++ b/poi/src/main/java/org/apache/poi/ss/format/CellFormatPart.java @@ -26,8 +26,10 @@ import javax.swing.*; import java.awt.*; import java.util.*; +import java.util.List; import java.util.regex.Matcher; import java.util.regex.Pattern; +import java.util.stream.Collectors; import static org.apache.poi.ss.format.CellFormatter.quote; @@ -50,29 +52,13 @@ public class CellFormatPart { private static final Logger LOG = PoiLogManager.getLogger(CellFormatPart.class); static final Map<String, Color> NAMED_COLORS; + static final List<Color> INDEXED_COLORS; private final Color color; private final CellFormatCondition condition; private final CellFormatter format; private final CellFormatType type; - static { - NAMED_COLORS = new TreeMap<>( - String.CASE_INSENSITIVE_ORDER); - - for (HSSFColor.HSSFColorPredefined color : HSSFColor.HSSFColorPredefined.values()) { - String name = color.name(); - short[] rgb = color.getTriplet(); - Color c = new Color(rgb[0], rgb[1], rgb[2]); - NAMED_COLORS.put(name, c); - if (name.indexOf('_') > 0) - NAMED_COLORS.put(name.replace('_', ' '), c); - if (name.indexOf("_PERCENT") > 0) - NAMED_COLORS.put(name.replace("_PERCENT", "%").replace('_', - ' '), c); - } - } - /** Pattern for the color part of a cell format part. */ public static final Pattern COLOR_PAT; /** Pattern for the condition part of a cell format part. */ @@ -103,6 +89,50 @@ public class CellFormatPart { public static final int SPECIFICATION_GROUP; static { + // Build indexed color list, in order, from 1 to 56 + Integer[] indexedColors = new Integer[] { + 0x000000, 0xFFFFFF, 0xFF0000, 0x00FF00, 0x0000FF, 0xFFFF00, 0xFF00FF, 0x00FFFF, + 0x800000, 0x008000, 0x000080, 0x808000, 0x800080, 0x008080, 0xC0C0C0, 0x808080, + 0x9999FF, 0x993366, 0xFFFFCC, 0xCCFFFF, 0x660066, 0xFF8080, 0x0066CC, 0xCCCCFF, + 0x000080, 0xFF00FF, 0xFFFF00, 0x00FFFF, 0x800080, 0x800000, 0x008080, 0x0000FF, + 0x00CCFF, 0xCCFFFF, 0xCCFFCC, 0xFFFF99, 0x99CCFF, 0xFF99CC, 0xCC99FF, 0xFFCC99, + 0x3366FF, 0x33CCCC, 0x99CC00, 0xFFCC00, 0xFF9900, 0xFF6600, 0x666699, 0x969696, + 0x003366, 0x339966, 0x003300, 0x333300, 0x993300, 0x993366, 0x333399, 0x333333 + }; + INDEXED_COLORS = Collections.unmodifiableList( + Arrays.asList(indexedColors) + .stream().map(Color::new) + .collect(Collectors.toList())); + + // Build initial named color map + Map<String, Color> namedColors = new TreeMap<>( + String.CASE_INSENSITIVE_ORDER); + + // Retain compatibility with original implementation + for (HSSFColor.HSSFColorPredefined color : HSSFColor.HSSFColorPredefined.values()) { + String name = color.name(); + short[] rgb = color.getTriplet(); + Color c = new Color(rgb[0], rgb[1], rgb[2]); + namedColors.put(name, c); + if (name.indexOf('_') > 0) + namedColors.put(name.replace('_', ' '), c); + if (name.indexOf("_PERCENT") > 0) + namedColors.put(name.replace("_PERCENT", "%").replace('_', + ' '), c); + } + + // Add missing color values and replace incorrectly defined standard colors + // used in Excel, Google Sheets, etc. The first eight indexed colors correspond + // exactly to named colors. + namedColors.put("black", INDEXED_COLORS.get(0)); + namedColors.put("white", INDEXED_COLORS.get(1)); + namedColors.put("red", INDEXED_COLORS.get(2)); + namedColors.put("green", INDEXED_COLORS.get(3)); + namedColors.put("blue", INDEXED_COLORS.get(4)); + namedColors.put("yellow", INDEXED_COLORS.get(5)); + namedColors.put("magenta", INDEXED_COLORS.get(6)); + namedColors.put("cyan", INDEXED_COLORS.get(7)); + // A condition specification String condition = "([<>=]=?|!=|<>) # The operator\n" + " \\s*(-?([0-9]+(?:\\.[0-9]*)?)|(\\.[0-9]*))\\s* # The constant to test against\n"; @@ -110,8 +140,16 @@ public class CellFormatPart { // A currency symbol / string, in a specific locale String currency = "(\\[\\$.{0,3}(-[0-9a-f]{3,4})?])"; - String color = - "\\[(black|blue|cyan|green|magenta|red|white|yellow|color [0-9]+)]"; + // Build the color code matching expression. We should match any named color + // in the set as well as a string in the form of "Color 8" or "Color 15". + String color = "\\[("; + for (String key : namedColors.keySet()) { + // Escape special characters in the color name + color += key.replaceAll("([^a-zA-Z0-9])", "\\\\$1") + "|"; + } + // Match the indexed color table (accept both e.g. COLOR2 and COLOR 2) + // Both formats are accepted as input in other products + color += "color\\s*[0-9]+)\\]"; // A number specification // Note: careful that in something like ##, that the trailing comma is not caught up in the integer part @@ -159,6 +197,17 @@ public class CellFormatPart { CONDITION_OPERATOR_GROUP = findGroup(FORMAT_PAT, "[>=1]@", ">="); CONDITION_VALUE_GROUP = findGroup(FORMAT_PAT, "[>=1]@", "1"); SPECIFICATION_GROUP = findGroup(FORMAT_PAT, "[Blue][>1]\\a ?", "\\a ?"); + + // Once patterns have been compiled, add indexed colors to + // namedColors so they can be easily picked up by getColor(). + for (int i = 0; i < INDEXED_COLORS.size(); ++i) { + namedColors.put("color" + (i + 1), INDEXED_COLORS.get(i)); + // Also support space between "color" and number. + namedColors.put("color " + (i + 1), INDEXED_COLORS.get(i)); + } + + // Store namedColors as NAMED_COLORS + NAMED_COLORS = Collections.unmodifiableMap(namedColors); } interface PartHandler { @@ -250,12 +299,23 @@ public class CellFormatPart { * @return The color specification or {@code null}. */ private static Color getColor(Matcher m) { - String cdesc = m.group(COLOR_GROUP); - if (cdesc == null || cdesc.length() == 0) + return getColor(m.group(COLOR_GROUP)); + } + + /** + * Get the Color object matching a color name, or {@code null} if the + * color name is not recognized. + * + * @param cname Color name, such as "red" or "Color 15" + * + * @return a Color object or {@code null}. + */ + static Color getColor(String cname) { + if (cname == null || cname.isEmpty()) return null; - Color c = NAMED_COLORS.get(cdesc); + Color c = NAMED_COLORS.get(cname); if (c == null) { - LOG.warn("Unknown color: {}", quote(cdesc)); + LOG.warn("Unknown color: {}", quote(cname)); } return c; } @@ -270,7 +330,7 @@ public class CellFormatPart { */ private CellFormatCondition getCondition(Matcher m) { String mdesc = m.group(CONDITION_OPERATOR_GROUP); - if (mdesc == null || mdesc.length() == 0) + if (mdesc == null || mdesc.isEmpty()) return null; return CellFormatCondition.getInstance(m.group( CONDITION_OPERATOR_GROUP), m.group(CONDITION_VALUE_GROUP)); @@ -509,7 +569,7 @@ public class CellFormatPart { StringBuffer fmt = new StringBuffer(); while (m.find()) { String part = group(m, 0); - if (part.length() > 0) { + if (!part.isEmpty()) { String repl = partHandler.handlePart(m, part, type, fmt); if (repl == null) { switch (part.charAt(0)) { diff --git a/poi/src/main/java/org/apache/poi/ss/formula/EvaluationConditionalFormatRule.java b/poi/src/main/java/org/apache/poi/ss/formula/EvaluationConditionalFormatRule.java index 54199cbfca..3d0e441dbc 100644 --- a/poi/src/main/java/org/apache/poi/ss/formula/EvaluationConditionalFormatRule.java +++ b/poi/src/main/java/org/apache/poi/ss/formula/EvaluationConditionalFormatRule.java @@ -357,7 +357,7 @@ public class EvaluationConditionalFormatRule implements Comparable<EvaluationCon String f2 = rule.getFormula2(); ValueEval eval2 = BlankEval.instance; - if (f2 != null && f2.length() > 0) { + if (f2 != null && !f2.isEmpty()) { eval2 = unwrapEval(workbookEvaluator.evaluate(f2, ConditionalFormattingEvaluator.getRef(cell), region)); } diff --git a/poi/src/main/java/org/apache/poi/ss/formula/FormulaParser.java b/poi/src/main/java/org/apache/poi/ss/formula/FormulaParser.java index 020ae38d8c..c748231838 100644 --- a/poi/src/main/java/org/apache/poi/ss/formula/FormulaParser.java +++ b/poi/src/main/java/org/apache/poi/ss/formula/FormulaParser.java @@ -483,7 +483,7 @@ public final class FormulaParser { } else { // Is it a named range? String name = parseAsName(); - if (name.length() == 0) { + if (name.isEmpty()) { throw new FormulaParseException("Cell reference or Named Range " + "expected after sheet name at index " + _pointer + "."); } diff --git a/poi/src/main/java/org/apache/poi/ss/formula/WorkbookEvaluator.java b/poi/src/main/java/org/apache/poi/ss/formula/WorkbookEvaluator.java index 11ae822a21..4b703fc143 100644 --- a/poi/src/main/java/org/apache/poi/ss/formula/WorkbookEvaluator.java +++ b/poi/src/main/java/org/apache/poi/ss/formula/WorkbookEvaluator.java @@ -971,7 +971,7 @@ public final class WorkbookEvaluator { } /** - * Register a ATP function in runtime. + * Register an ATP function in runtime. * * @param name the function name * @param func the function to register diff --git a/poi/src/main/java/org/apache/poi/ss/formula/atp/AnalysisToolPak.java b/poi/src/main/java/org/apache/poi/ss/formula/atp/AnalysisToolPak.java index dd165383ee..a34b8b370d 100644 --- a/poi/src/main/java/org/apache/poi/ss/formula/atp/AnalysisToolPak.java +++ b/poi/src/main/java/org/apache/poi/ss/formula/atp/AnalysisToolPak.java @@ -1,12 +1,19 @@ -/* - * ==================================================================== Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. - * The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or - * agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - * KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - * ==================================================================== - */ +/* ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ package org.apache.poi.ss.formula.atp; @@ -17,6 +24,8 @@ import java.util.Locale; import java.util.Map; import java.util.TreeSet; +import org.apache.logging.log4j.Logger; +import org.apache.poi.logging.PoiLogManager; import org.apache.poi.ss.formula.OperationEvaluationContext; import org.apache.poi.ss.formula.eval.NotImplementedFunctionException; import org.apache.poi.ss.formula.eval.ValueEval; @@ -32,6 +41,8 @@ public final class AnalysisToolPak implements UDFFinder { public static final UDFFinder instance = new AnalysisToolPak(); + private static final Logger LOG = PoiLogManager.getLogger(AnalysisToolPak.class); + private static final class NotImplemented implements FreeRefFunction { private final String _functionName; @@ -180,6 +191,7 @@ public final class AnalysisToolPak implements UDFFinder { r(m, "RECEIVED", null); r(m, "RTD", null); r(m, "SERIESSUM", null); + r(m, "SHEET", Sheet.instance); r(m, "SINGLE", Single.instance); r(m, "SQRTPI", Sqrtpi.instance); r(m, "STDEV.S", Stdevs.instance); @@ -265,9 +277,26 @@ public final class AnalysisToolPak implements UDFFinder { * @throws IllegalArgumentException if the function is unknown or already registered. * @since 3.8 beta6 */ - public static void registerFunction(String name, FreeRefFunction func){ + public static void registerFunction(String name, FreeRefFunction func) { + registerFunction(name, func, false); + } + + /** + * Register an ATP function in runtime. + * + * @param name the function name + * @param func the function to register + * @param force force registration even if the function is already registered or unknown to POI + * @throws IllegalArgumentException if the function is unknown or already registered (and `force` is not true). + * @since POI 5.5.0 + */ + public static void registerFunction(String name, FreeRefFunction func, boolean force) { AnalysisToolPak inst = (AnalysisToolPak)instance; - if(!isATPFunction(name)) { + if (force) { + // Excel regularly adds new functions, so the ones registered in POI + // can be well out of date - allow users who know what they are doing + // to force their update + } else if(!isATPFunction(name)) { FunctionMetadata metaData = FunctionMetadataRegistry.getFunctionByName(name); if(metaData != null) { throw new IllegalArgumentException(name + " is a built-in Excel function. " + @@ -276,13 +305,20 @@ public final class AnalysisToolPak implements UDFFinder { throw new IllegalArgumentException(name + " is not a function from the Excel Analysis Toolpack."); } + FreeRefFunction f = inst.findFunction(name); if(f != null && !(f instanceof NotImplemented)) { - throw new IllegalArgumentException("POI already implements " + name + - ". You cannot override POI's implementations of Excel functions"); + if (force) { + LOG.info("POI already implements " + name + + ". You are overriding the implementation."); + } else { + throw new IllegalArgumentException("POI already implements " + name + + ". You cannot override POI's implementations of Excel functions"); + } } // FIXME: inconsistent case-sensitivity inst._functionsByName.put(name, func); } + } diff --git a/poi/src/main/java/org/apache/poi/ss/formula/atp/TextJoinFunction.java b/poi/src/main/java/org/apache/poi/ss/formula/atp/TextJoinFunction.java index 5e7ffe8b87..45b3ec31ac 100644 --- a/poi/src/main/java/org/apache/poi/ss/formula/atp/TextJoinFunction.java +++ b/poi/src/main/java/org/apache/poi/ss/formula/atp/TextJoinFunction.java @@ -86,7 +86,7 @@ final class TextJoinFunction implements FreeRefFunction { String textValue = OperandResolver.coerceValueToString(textArg); // If we're not ignoring empty values or if our value is not empty, add it to the list - if (!ignoreEmpty || (textValue != null && textValue.length() > 0)) { + if (!ignoreEmpty || (textValue != null && !textValue.isEmpty())) { textValues.add(textValue); } } diff --git a/poi/src/main/java/org/apache/poi/ss/formula/function/FunctionMetadataReader.java b/poi/src/main/java/org/apache/poi/ss/formula/function/FunctionMetadataReader.java index b03c732e89..4b6e6fa2e7 100644 --- a/poi/src/main/java/org/apache/poi/ss/formula/function/FunctionMetadataReader.java +++ b/poi/src/main/java/org/apache/poi/ss/formula/function/FunctionMetadataReader.java @@ -124,7 +124,7 @@ final class FunctionMetadataReader { byte returnClassCode = parseReturnTypeCode(parts[4]); byte[] parameterClassCodes = parseOperandTypeCodes(parts[5]); // 6 isVolatile - boolean hasNote = parts[7].length() > 0; + boolean hasNote = !parts[7].isEmpty(); validateFunctionName(functionName); // TODO - make POI use isVolatile @@ -134,7 +134,7 @@ final class FunctionMetadataReader { private static byte parseReturnTypeCode(String code) { - if(code.length() == 0) { + if(code.isEmpty()) { return Ptg.CLASS_REF; // happens for GETPIVOTDATA } return parseOperandTypeCode(code); @@ -155,7 +155,7 @@ final class FunctionMetadataReader { // (all unspecified params are assumed to be the same as the last) nItems --; } - byte[] result = IOUtils.safelyAllocate(nItems, MAX_RECORD_LENGTH); + byte[] result = IOUtils.safelyAllocate(nItems, getMaxRecordLength()); for (int i = 0; i < nItems; i++) { result[i] = parseOperandTypeCode(array[i]); } diff --git a/poi/src/main/java/org/apache/poi/ss/formula/functions/BaseNumberUtils.java b/poi/src/main/java/org/apache/poi/ss/formula/functions/BaseNumberUtils.java index c39d082e10..db583f3229 100644 --- a/poi/src/main/java/org/apache/poi/ss/formula/functions/BaseNumberUtils.java +++ b/poi/src/main/java/org/apache/poi/ss/formula/functions/BaseNumberUtils.java @@ -23,7 +23,7 @@ public class BaseNumberUtils { public static double convertToDecimal(String value, int base, int maxNumberOfPlaces) throws IllegalArgumentException { - if (value == null || value.length() == 0) { + if (value == null || value.isEmpty()) { return 0.0; } diff --git a/poi/src/main/java/org/apache/poi/ss/formula/functions/Code.java b/poi/src/main/java/org/apache/poi/ss/formula/functions/Code.java index 96f2a13204..30f2d3257f 100644 --- a/poi/src/main/java/org/apache/poi/ss/formula/functions/Code.java +++ b/poi/src/main/java/org/apache/poi/ss/formula/functions/Code.java @@ -41,7 +41,7 @@ public class Code extends Fixed1ArgFunction { } String text = OperandResolver.coerceValueToString(veText1); - if (text.length() == 0) { + if (text.isEmpty()) { return ErrorEval.VALUE_INVALID; } diff --git a/poi/src/main/java/org/apache/poi/ss/formula/functions/Complex.java b/poi/src/main/java/org/apache/poi/ss/formula/functions/Complex.java index a10c54a758..a4fac2685e 100644 --- a/poi/src/main/java/org/apache/poi/ss/formula/functions/Complex.java +++ b/poi/src/main/java/org/apache/poi/ss/formula/functions/Complex.java @@ -90,7 +90,7 @@ public class Complex extends Var2or3ArgFunction implements FreeRefFunction { } String suffixValue = OperandResolver.coerceValueToString(suffix); - if (suffixValue.length() == 0) { + if (suffixValue.isEmpty()) { suffixValue = DEFAULT_SUFFIX; } if (suffixValue.equals(DEFAULT_SUFFIX.toUpperCase(Locale.ROOT)) || diff --git a/poi/src/main/java/org/apache/poi/ss/formula/functions/Countif.java b/poi/src/main/java/org/apache/poi/ss/formula/functions/Countif.java index 93fdf033a4..ecb57e5e1a 100644 --- a/poi/src/main/java/org/apache/poi/ss/formula/functions/Countif.java +++ b/poi/src/main/java/org/apache/poi/ss/formula/functions/Countif.java @@ -339,7 +339,7 @@ public final class Countif extends Fixed2ArgFunction { switch(getCode()) { case CmpOp.NONE: case CmpOp.EQ: - return _value.length() == 0; + return _value.isEmpty(); case CmpOp.NE: // pred '<>' matches empty string but not blank cell // pred '<>ABC' matches blank and 'not ABC' diff --git a/poi/src/main/java/org/apache/poi/ss/formula/functions/Imaginary.java b/poi/src/main/java/org/apache/poi/ss/formula/functions/Imaginary.java index 012aacdd01..f478c95d5b 100644 --- a/poi/src/main/java/org/apache/poi/ss/formula/functions/Imaginary.java +++ b/poi/src/main/java/org/apache/poi/ss/formula/functions/Imaginary.java @@ -74,7 +74,7 @@ public class Imaginary extends Fixed1ArgFunction implements FreeRefFunction { String imaginaryGroup = m.group(5); boolean hasImaginaryPart = imaginaryGroup.equals("i") || imaginaryGroup.equals("j"); - if (imaginaryGroup.length() == 0) { + if (imaginaryGroup.isEmpty()) { return new StringEval(String.valueOf(0)); } diff --git a/poi/src/main/java/org/apache/poi/ss/formula/functions/Rept.java b/poi/src/main/java/org/apache/poi/ss/formula/functions/Rept.java index c3be177ce3..33b2c46366 100644 --- a/poi/src/main/java/org/apache/poi/ss/formula/functions/Rept.java +++ b/poi/src/main/java/org/apache/poi/ss/formula/functions/Rept.java @@ -40,7 +40,6 @@ import org.apache.poi.ss.formula.eval.ValueEval; */ public class Rept extends Fixed2ArgFunction { - @Override public ValueEval evaluate(int srcRowIndex, int srcColumnIndex, ValueEval text, ValueEval number_times) { @@ -64,7 +63,7 @@ public class Rept extends Fixed2ArgFunction { strb.append(strText1); } - if (strb.toString().length() > 32767) { + if (strb.length() > 32767) { return ErrorEval.VALUE_INVALID; } diff --git a/poi/src/main/java/org/apache/poi/ss/formula/functions/Sheet.java b/poi/src/main/java/org/apache/poi/ss/formula/functions/Sheet.java new file mode 100644 index 0000000000..37b78dbb89 --- /dev/null +++ b/poi/src/main/java/org/apache/poi/ss/formula/functions/Sheet.java @@ -0,0 +1,89 @@ +/* ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ + +package org.apache.poi.ss.formula.functions; + +import org.apache.poi.ss.formula.EvaluationWorkbook; +import org.apache.poi.ss.formula.OperationEvaluationContext; +import org.apache.poi.ss.formula.eval.*; + +/** + * Implementation for Excel SHEET() function. + * <p> + * <b>Syntax</b>:<br> <b>SHEET</b>([value])<br> + * </p> + * <p> + * Returns the sheet number of the referenced sheet or the current sheet if no argument is provided. + * </p> + * <p> + * Examples: + * </p> + * <ul> + * <li><code>=SHEET()</code> → returns the current sheet number (1-based)</li> + * <li><code>=SHEET(A1)</code> → returns the sheet number of the reference A1</li> + * <li><code>=SHEET(A1:B5)</code> → returns the sheet number of the range A1:B5</li> + * <li><code>=SHEET("Sheet3")</code> → returns the sheet number of the sheet named "Sheet3"</li> + * </ul> + * <p> + * See <a href="https://support.microsoft.com/en-us/office/sheet-function-44718b6f-8b87-47a1-a9d6-b701c06cff24">Microsoft Documentation</a> + * </p> + */ +public class Sheet implements FreeRefFunction { + + public static final Sheet instance = new Sheet(); + + @Override + public ValueEval evaluate(ValueEval[] args, OperationEvaluationContext ec) { + try { + if (args.length == 0) { + // No argument provided → return the current sheet index +1 (Excel uses 1-based index) + return new NumberEval((double) ec.getSheetIndex() + 1); + } else { + ValueEval arg = args[0]; + + if (arg instanceof RefEval) { + // Argument is a single cell reference → return the sheet index of that reference +1 + RefEval ref = (RefEval) arg; + int sheetIndex = ref.getFirstSheetIndex(); + return new NumberEval((double) sheetIndex + 1); + } else if (arg instanceof AreaEval) { + // Argument is a cell range → return the sheet index of that area +1 + AreaEval area = (AreaEval) arg; + int sheetIndex = area.getFirstSheetIndex(); + return new NumberEval((double) sheetIndex + 1); + } else if (arg instanceof StringEval) { + // Argument is a string (sheet name, e.g., "Sheet3") → look up the sheet index by name + String sheetName = ((StringEval) arg).getStringValue(); + EvaluationWorkbook wb = ec.getWorkbook(); + int sheetIndex = wb.getSheetIndex(sheetName); + if (sheetIndex >= 0) { + return new NumberEval((double) sheetIndex + 1); + } else { + // Sheet name not found → return #N/A error + return ErrorEval.NA; + } + } else { + // Unsupported argument type → return #N/A error + return ErrorEval.NA; + } + } + } catch (Exception e) { + // Any unexpected exception (e.g., null pointers) → return #VALUE! error + return ErrorEval.VALUE_INVALID; + } + } +} diff --git a/poi/src/main/java/org/apache/poi/ss/formula/functions/Value.java b/poi/src/main/java/org/apache/poi/ss/formula/functions/Value.java index 451f0a2fab..87edae4b0e 100644 --- a/poi/src/main/java/org/apache/poi/ss/formula/functions/Value.java +++ b/poi/src/main/java/org/apache/poi/ss/formula/functions/Value.java @@ -152,7 +152,7 @@ public final class Value extends Fixed1ArgFunction implements ArrayFunction { foundPercentage = true; break; } - if (remainingTextTrimmed.length() > 0) { + if (!remainingTextTrimmed.isEmpty()) { // intervening spaces not allowed once the digits start return null; } diff --git a/poi/src/main/java/org/apache/poi/ss/usermodel/DateUtil.java b/poi/src/main/java/org/apache/poi/ss/usermodel/DateUtil.java index 0f44be4279..452c8948bb 100644 --- a/poi/src/main/java/org/apache/poi/ss/usermodel/DateUtil.java +++ b/poi/src/main/java/org/apache/poi/ss/usermodel/DateUtil.java @@ -70,7 +70,7 @@ public class DateUtil { private static final Pattern date_ptrn2 = Pattern.compile("^\\[[a-zA-Z]+]"); private static final Pattern date_ptrn3a = Pattern.compile("[yYmMdDhHsS]"); // add "\u5e74 \u6708 \u65e5" for Chinese/Japanese date format:2017 \u5e74 2 \u6708 7 \u65e5 - private static final Pattern date_ptrn3b = Pattern.compile("^[\\[\\]yYmMdDhHsS\\-T/\u5e74\u6708\u65e5,. :\"\\\\]+0*[ampAMP/]*$"); + private static final Pattern date_ptrn3b = Pattern.compile("^[\\[\\]yYmMdDhHsS\\-T/\u5e74\u6708\u65e5,. :\"\\\\]+0* ?[ampAMP/]*$"); // elapsed time patterns: [h],[m] and [s] private static final Pattern date_ptrn4 = Pattern.compile("^\\[([hH]+|[mM]+|[sS]+)]"); @@ -220,8 +220,12 @@ public class DateUtil { return internalGetExcelDate(year, dayOfYear, hour, minute, second, milliSecond, use1904windowing); } + private static boolean isLastDay1899(final int year, final int dayOfYear) { + return year == 1899 && dayOfYear == 365; + } + private static double internalGetExcelDate(int year, int dayOfYear, int hour, int minute, int second, int milliSecond, boolean use1904windowing) { - if ((!use1904windowing && year < 1900) || + if ((!use1904windowing && (year < 1900 && !isLastDay1899(year, dayOfYear))) || (use1904windowing && year < 1904)) { return BAD_DATE; @@ -544,6 +548,7 @@ public class DateUtil { // avoid re-checking DateUtil.isADateFormat(int, String) if a given format // string represents a date format if the same string is passed multiple times. // see https://issues.apache.org/bugzilla/show_bug.cgi?id=55611 + private static boolean maintainCache = true; private static final ThreadLocal<Integer> lastFormatIndex = ThreadLocal.withInitial(() -> -1); private static final ThreadLocal<String> lastFormatString = new ThreadLocal<>(); private static final ThreadLocal<Boolean> lastCachedResult = new ThreadLocal<>(); @@ -557,22 +562,24 @@ public class DateUtil { } private static boolean isCached(String formatString, int formatIndex) { - return formatIndex == lastFormatIndex.get() + return maintainCache && formatIndex == lastFormatIndex.get() && formatString.equals(lastFormatString.get()); } private static void cache(String formatString, int formatIndex, boolean cached) { - if (formatString == null || "".equals(formatString)) { - lastFormatString.remove(); - } else { - lastFormatString.set(formatString); - } - if (formatIndex == -1) { - lastFormatIndex.remove(); - } else { - lastFormatIndex.set(formatIndex); + if (maintainCache) { + if (formatString == null || "".equals(formatString)) { + lastFormatString.remove(); + } else { + lastFormatString.set(formatString); + } + if (formatIndex == -1) { + lastFormatIndex.remove(); + } else { + lastFormatIndex.set(formatIndex); + } + lastCachedResult.set(cached); } - lastCachedResult.set(cached); } /** @@ -620,7 +627,7 @@ public class DateUtil { } // If we didn't get a real string, don't even cache it as we can always find this out quickly - if(formatString == null || formatString.length() == 0) { + if(formatString == null || formatString.isEmpty()) { return false; } @@ -719,24 +726,27 @@ public class DateUtil { * @see #isADateFormat(int, java.lang.String) */ public static boolean isInternalDateFormat(int format) { - switch(format) { - // Internal Date Formats as described on page 427 in - // Microsoft Excel Dev's Kit... - case 0x0e: - case 0x0f: - case 0x10: - case 0x11: - case 0x12: - case 0x13: - case 0x14: - case 0x15: - case 0x16: - case 0x2d: - case 0x2e: - case 0x2f: - return true; - } - return false; + switch(format) { + // Internal Date Formats as described on page 427 in + // Microsoft Excel Dev's Kit... + // see also javadoc in org.apache.poi.ss.usermodel.BuiltinFormats + case 0x0e: + case 0x0f: + case 0x10: + case 0x11: + // the 0x12 to 0x15 formats are time (only) formats + case 0x12: + case 0x13: + case 0x14: + case 0x15: + case 0x16: + // the 0x2d to 0x2f formats are time (only) formats + case 0x2d: + case 0x2e: + case 0x2f: + return true; + } + return false; } /** @@ -811,7 +821,6 @@ public class DateUtil { * @return true if valid * @param value the double value */ - public static boolean isValidExcelDate(double value) { return (value > -Double.MIN_VALUE); @@ -850,31 +859,24 @@ public class DateUtil { * @throws IllegalArgumentException if date is invalid */ private static int absoluteDay(int year, int dayOfYear, boolean use1904windowing) { - return dayOfYear + daysInPriorYears(year, use1904windowing); + return dayOfYear + daysInPriorYears(year, dayOfYear, use1904windowing); } - /** - * Return the number of days in prior years since 1900 - * - * @return days number of days in years prior to yr. - * @param yr a year (1900 < yr < 4000) - * @param use1904windowing Should 1900 or 1904 date windowing be used? - * @throws IllegalArgumentException if year is outside of range. - */ - - static int daysInPriorYears(int yr, boolean use1904windowing) + private static int daysInPriorYears(final int year, final int dayOfYear, + final boolean use1904windowing) { - if ((!use1904windowing && yr < 1900) || (use1904windowing && yr < 1904)) { + if ((!use1904windowing && (year < 1900 && !isLastDay1899(year, dayOfYear))) + || (use1904windowing && year < 1904)) { throw new IllegalArgumentException("'year' must be 1900 or greater"); } - int yr1 = yr - 1; + int yr1 = year - 1; int leapDays = yr1 / 4 // plus julian leap days in prior years - yr1 / 100 // minus prior century years + yr1 / 400 // plus years divisible by 400 - 460; // leap days in previous 1900 years - return 365 * (yr - (use1904windowing ? 1904 : 1900)) + leapDays; + return 365 * (year - (use1904windowing ? 1904 : 1900)) + leapDays; } // set HH:MM:SS fields of cal to 00:00:00:000 @@ -998,4 +1000,18 @@ public class DateUtil { return tm; } + + /** + * Enable or disable the thread-local cache for date format checking. + * If enabled, the date format checking will be cached per thread, + * which can improve performance when checking the same format multiple times. + * If disabled, the cache will not be used and each check will be performed independently. + * + * @param enable true to enable the cache, false to disable it (enabled, by default) + * @since POI 5.5.0 + */ + public static void enableThreadLocalCache(final boolean enable) { + // enable thread-local cache for date format checking + maintainCache = enable; + } } diff --git a/poi/src/main/java/org/apache/poi/ss/util/AreaReference.java b/poi/src/main/java/org/apache/poi/ss/util/AreaReference.java index fc45d81b4a..fd1cb4ff51 100644 --- a/poi/src/main/java/org/apache/poi/ss/util/AreaReference.java +++ b/poi/src/main/java/org/apache/poi/ss/util/AreaReference.java @@ -326,7 +326,7 @@ public class AreaReference { String currentSegment = ""; StringTokenizer st = new StringTokenizer(reference, ","); while(st.hasMoreTokens()) { - if (currentSegment.length() > 0) { + if (!currentSegment.isEmpty()) { currentSegment += ","; } currentSegment += st.nextToken(); @@ -336,7 +336,7 @@ public class AreaReference { currentSegment = ""; } } - if (currentSegment.length() > 0) { + if (!currentSegment.isEmpty()) { results.add(currentSegment); } return results.toArray(new String[0]); diff --git a/poi/src/main/java/org/apache/poi/ss/util/CellReference.java b/poi/src/main/java/org/apache/poi/ss/util/CellReference.java index 1749878163..da1202c283 100644 --- a/poi/src/main/java/org/apache/poi/ss/util/CellReference.java +++ b/poi/src/main/java/org/apache/poi/ss/util/CellReference.java @@ -116,22 +116,22 @@ public class CellReference implements GenericRecord { _sheetName = parts.sheetName; String colRef = parts.colRef; - _isColAbs = (colRef.length() > 0) && colRef.charAt(0) == '$'; + _isColAbs = (!colRef.isEmpty()) && colRef.charAt(0) == '$'; if (_isColAbs) { colRef = colRef.substring(1); } - if (colRef.length() == 0) { + if (colRef.isEmpty()) { _colIndex = -1; } else { _colIndex = convertColStringToIndex(colRef); } String rowRef=parts.rowRef; - _isRowAbs = (rowRef.length() > 0) && rowRef.charAt(0) == '$'; + _isRowAbs = (!rowRef.isEmpty()) && rowRef.charAt(0) == '$'; if (_isRowAbs) { rowRef = rowRef.substring(1); } - if (rowRef.length() == 0) { + if (rowRef.isEmpty()) { _rowIndex = -1; } else { // throws NumberFormatException if rowRef is not convertible to an int @@ -451,7 +451,7 @@ public class CellReference implements GenericRecord { } /** - * Takes in a 0-based base-10 column and returns a ALPHA-26 + * Takes in a 0-based base-10 column and returns an ALPHA-26 * representation. * eg {@code convertNumToColString(3)} returns {@code "D"} */ diff --git a/poi/src/main/java/org/apache/poi/ss/util/CellUtil.java b/poi/src/main/java/org/apache/poi/ss/util/CellUtil.java index f3e5bf55b6..7c1b3ad81e 100644 --- a/poi/src/main/java/org/apache/poi/ss/util/CellUtil.java +++ b/poi/src/main/java/org/apache/poi/ss/util/CellUtil.java @@ -18,6 +18,7 @@ package org.apache.poi.ss.util; import java.util.Collections; +import java.util.EnumMap; import java.util.EnumSet; import java.util.HashMap; import java.util.Locale; @@ -46,6 +47,7 @@ import org.apache.poi.ss.usermodel.CellStyle; import org.apache.poi.ss.usermodel.VerticalAlignment; import org.apache.poi.ss.usermodel.Workbook; import org.apache.poi.util.Beta; +import org.apache.poi.util.Internal; import org.apache.poi.util.Removal; /** @@ -278,6 +280,7 @@ public final class CellUtil { map.put(LEFT_BORDER_COLOR, CellPropertyType.LEFT_BORDER_COLOR); map.put(RIGHT_BORDER_COLOR, CellPropertyType.RIGHT_BORDER_COLOR); map.put(TOP_BORDER_COLOR, CellPropertyType.TOP_BORDER_COLOR); + map.put(DATA_FORMAT, CellPropertyType.DATA_FORMAT); map.put(FILL_BACKGROUND_COLOR, CellPropertyType.FILL_BACKGROUND_COLOR); map.put(FILL_FOREGROUND_COLOR, CellPropertyType.FILL_FOREGROUND_COLOR); map.put(FILL_BACKGROUND_COLOR_COLOR, CellPropertyType.FILL_BACKGROUND_COLOR_COLOR); @@ -287,10 +290,11 @@ public final class CellUtil { map.put(HIDDEN, CellPropertyType.HIDDEN); map.put(INDENTION, CellPropertyType.INDENTION); map.put(LOCKED, CellPropertyType.LOCKED); + map.put(QUOTE_PREFIXED, CellPropertyType.QUOTE_PREFIXED); map.put(ROTATION, CellPropertyType.ROTATION); - map.put(VERTICAL_ALIGNMENT, CellPropertyType.VERTICAL_ALIGNMENT); map.put(SHRINK_TO_FIT, CellPropertyType.SHRINK_TO_FIT); - map.put(QUOTE_PREFIXED, CellPropertyType.QUOTE_PREFIXED); + map.put(VERTICAL_ALIGNMENT, CellPropertyType.VERTICAL_ALIGNMENT); + map.put(WRAP_TEXT, CellPropertyType.WRAP_TEXT); namePropertyMap = Collections.unmodifiableMap(map); } @@ -409,7 +413,7 @@ public final class CellUtil { switch (copyCellType) { case NUMERIC: // DataFormat is not copied unless policy.isCopyCellStyle is true - if (DateUtil.isCellDateFormatted(srcCell)) { + if (!policy.isCopyCellStyle() && DateUtil.isCellDateFormatted(srcCell)) { destCell.setCellValue(srcCell.getDateCellValue()); } else { destCell.setCellValue(srcCell.getNumericCellValue()); @@ -570,7 +574,7 @@ public final class CellUtil { @Deprecated @Removal(version = "7.0.0") public static void setCellStyleProperties(Cell cell, Map<String, Object> properties) { - Map<CellPropertyType, Object> strPropMap = new HashMap<>(properties.size()); + final EnumMap<CellPropertyType, Object> strPropMap = new EnumMap<>(CellPropertyType.class); properties.forEach((k, v) -> strPropMap.put(namePropertyMap.get(k), v)); setCellStyleProperties(cell, strPropMap, false); } @@ -610,7 +614,7 @@ public final class CellUtil { CellStyle originalStyle = cell.getCellStyle(); CellStyle newStyle = null; - Map<CellPropertyType, Object> values = getFormatProperties(originalStyle); + EnumMap<CellPropertyType, Object> values = getFormatProperties(originalStyle); if (properties.containsKey(CellPropertyType.FILL_FOREGROUND_COLOR_COLOR) && properties.get(CellPropertyType.FILL_FOREGROUND_COLOR_COLOR) == null) { values.remove(CellPropertyType.FILL_FOREGROUND_COLOR); } @@ -627,11 +631,11 @@ public final class CellUtil { // index seems like what index the cellstyle is in the list of styles for a workbook. // not good to compare on! - int numberCellStyles = workbook.getNumCellStyles(); + final int numberCellStyles = workbook.getNumCellStyles(); for (int i = 0; i < numberCellStyles; i++) { CellStyle wbStyle = workbook.getCellStyleAt(i); - Map<CellPropertyType, Object> wbStyleMap = getFormatProperties(wbStyle); + EnumMap<CellPropertyType, Object> wbStyleMap = getFormatProperties(wbStyle); // the desired style already exists in the workbook. Use the existing style. if (styleMapsMatch(wbStyleMap, values, disableNullColorCheck)) { @@ -651,8 +655,8 @@ public final class CellUtil { private static boolean styleMapsMatch(final Map<CellPropertyType, Object> newProps, final Map<CellPropertyType, Object> storedProps, final boolean disableNullColorCheck) { - final Map<CellPropertyType, Object> map1Copy = new HashMap<>(newProps); - final Map<CellPropertyType, Object> map2Copy = new HashMap<>(storedProps); + final EnumMap<CellPropertyType, Object> map1Copy = new EnumMap<>(newProps); + final EnumMap<CellPropertyType, Object> map2Copy = new EnumMap<>(storedProps); final Object backColor1 = map1Copy.remove(CellPropertyType.FILL_BACKGROUND_COLOR_COLOR); final Object backColor2 = map2Copy.remove(CellPropertyType.FILL_BACKGROUND_COLOR_COLOR); final Object foreColor1 = map1Copy.remove(CellPropertyType.FILL_FOREGROUND_COLOR_COLOR); @@ -683,20 +687,26 @@ public final class CellUtil { * @param cell The cell that is to be changed. * @param property The name of the property that is to be changed. * @param propertyValue The value of the property that is to be changed. - * + * @throws NullPointerException if {@code cell} or {@code property} is null * @since POI 5.4.0 */ public static void setCellStyleProperty(Cell cell, CellPropertyType property, Object propertyValue) { + if (cell == null) { + throw new NullPointerException("Cell must not be null"); + } + if (property == null) { + throw new NullPointerException("CellPropertyType must not be null"); + } boolean disableNullColorCheck = false; final Map<CellPropertyType, Object> propMap; if (CellPropertyType.FILL_FOREGROUND_COLOR_COLOR.equals(property) && propertyValue == null) { disableNullColorCheck = true; - propMap = new HashMap<>(); + propMap = new EnumMap<>(CellPropertyType.class); propMap.put(CellPropertyType.FILL_FOREGROUND_COLOR_COLOR, null); propMap.put(CellPropertyType.FILL_FOREGROUND_COLOR, null); } else if (CellPropertyType.FILL_BACKGROUND_COLOR_COLOR.equals(property) && propertyValue == null) { disableNullColorCheck = true; - propMap = new HashMap<>(); + propMap = new EnumMap<>(CellPropertyType.class); propMap.put(CellPropertyType.FILL_BACKGROUND_COLOR_COLOR, null); propMap.put(CellPropertyType.FILL_BACKGROUND_COLOR, null); } else { @@ -739,8 +749,8 @@ public final class CellUtil { * @return map of format properties (CellPropertyType -> Object) * @see #setFormatProperties(CellStyle, Workbook, Map) */ - private static Map<CellPropertyType, Object> getFormatProperties(CellStyle style) { - Map<CellPropertyType, Object> properties = new HashMap<>(); + private static EnumMap<CellPropertyType, Object> getFormatProperties(CellStyle style) { + EnumMap<CellPropertyType, Object> properties = new EnumMap<>(CellPropertyType.class); put(properties, CellPropertyType.ALIGNMENT, style.getAlignment()); put(properties, CellPropertyType.VERTICAL_ALIGNMENT, style.getVerticalAlignment()); put(properties, CellPropertyType.BORDER_BOTTOM, style.getBorderBottom()); @@ -776,7 +786,6 @@ public final class CellUtil { * * @param src the property map to copy from (read-only) * @param dest the property map to copy into - * @since POI 3.15 beta 3 */ private static void putAll(final Map<CellPropertyType, Object> src, Map<CellPropertyType, Object> dest) { for (final CellPropertyType key : src.keySet()) { @@ -806,7 +815,7 @@ public final class CellUtil { * Sets the format properties of the given style based on the given map. * * @param style cell style - * @param workbook parent workbook + * @param workbook parent workbook (can be null but some fomt info will not be copied if null is passed) * @param properties map of format properties (CellPropertyType -> Object) * @see #getFormatProperties(CellStyle) */ @@ -848,7 +857,9 @@ public final class CellUtil { } } - style.setFont(workbook.getFontAt(getInt(properties, CellPropertyType.FONT))); + if (workbook != null) { + style.setFont(workbook.getFontAt(getInt(properties, CellPropertyType.FONT))); + } style.setHidden(getBoolean(properties, CellPropertyType.HIDDEN)); style.setIndention(getShort(properties, CellPropertyType.INDENTION)); style.setLeftBorderColor(getShort(properties, CellPropertyType.LEFT_BORDER_COLOR)); @@ -862,6 +873,25 @@ public final class CellUtil { } /** + * Clones the style from one cell to another. For internal use only. + * Users should use the cloneStyleFrom method on CellStyle instead. + * + * @param src source cell style + * @param dest destination cell style + * @param destWorkbook destination workbook (can be null but some font info will not be copied if null is passed) + * @throws IllegalArgumentException if source or destination styles are null + * @since POI 5.5.0 + */ + @Internal + public static void cloneStyle(CellStyle src, CellStyle dest, Workbook destWorkbook) { + if (src == null || dest == null) { + throw new IllegalArgumentException("Source and destination styles must not be null"); + } + EnumMap<CellPropertyType, Object> properties = getFormatProperties(src); + setFormatProperties(dest, destWorkbook, properties); + } + + /** * Utility method that returns the named short value from the given map. * * @param properties map of named properties (CellPropertyType -> Object) diff --git a/poi/src/main/java/org/apache/poi/ss/util/PropertyTemplate.java b/poi/src/main/java/org/apache/poi/ss/util/PropertyTemplate.java index 2f74af55d7..e00b785070 100644 --- a/poi/src/main/java/org/apache/poi/ss/util/PropertyTemplate.java +++ b/poi/src/main/java/org/apache/poi/ss/util/PropertyTemplate.java @@ -28,9 +28,11 @@ import org.apache.poi.ss.usermodel.IndexedColors; import org.apache.poi.ss.usermodel.Row; import org.apache.poi.ss.usermodel.Sheet; import org.apache.poi.ss.usermodel.Workbook; +import org.apache.poi.util.Removal; +import java.util.EnumMap; +import java.util.EnumSet; import java.util.HashMap; -import java.util.HashSet; import java.util.Map; import java.util.Set; @@ -42,9 +44,9 @@ import java.util.Set; * sheet in any workbook. * * This class requires the full spreadsheet to be in memory, so - * {@link org.apache.poi.xssf.streaming.SXSSFWorkbook} Spreadsheets are not + * <code>SXSSFWorkbook</code> Spreadsheets are not * supported. The same PropertyTemplate can, however, be applied to both - * {@link HSSFWorkbook} and {@link org.apache.poi.xssf.usermodel.XSSFWorkbook} + * {@link HSSFWorkbook} and <code>XSSFWorkbook</code> * objects if necessary. Portions of the border that fall outside the max range * of the {@link Workbook} sheet are ignored. * </p> @@ -59,7 +61,7 @@ public final class PropertyTemplate { * This is a list of cell properties for one shot application to a range of * cells at a later time. */ - private final Map<CellAddress, Map<CellPropertyType, Object>> _propertyTemplate; + private final Map<CellAddress, EnumMap<CellPropertyType, Object>> _propertyTemplate; /** * Create a PropertyTemplate object @@ -75,17 +77,17 @@ public final class PropertyTemplate { */ public PropertyTemplate(PropertyTemplate template) { this(); - for (Map.Entry<CellAddress, Map<CellPropertyType, Object>> entry : template.getTemplate().entrySet()) { + for (Map.Entry<CellAddress, EnumMap<CellPropertyType, Object>> entry : template.getTemplate().entrySet()) { _propertyTemplate.put(new CellAddress(entry.getKey()), cloneCellProperties(entry.getValue())); } } - private Map<CellAddress, Map<CellPropertyType, Object>> getTemplate() { + private Map<CellAddress, EnumMap<CellPropertyType, Object>> getTemplate() { return _propertyTemplate; } - private static Map<CellPropertyType, Object> cloneCellProperties(Map<CellPropertyType, Object> properties) { - return new HashMap<>(properties); + private static EnumMap<CellPropertyType, Object> cloneCellProperties(EnumMap<CellPropertyType, Object> properties) { + return new EnumMap<>(properties); } /** @@ -409,11 +411,11 @@ public final class PropertyTemplate { * @param range - {@link CellRangeAddress} range of cells to remove borders. */ private void removeBorders(CellRangeAddress range) { - Set<CellPropertyType> properties = new HashSet<>(); - properties.add(CellPropertyType.BORDER_TOP); - properties.add(CellPropertyType.BORDER_BOTTOM); - properties.add(CellPropertyType.BORDER_LEFT); - properties.add(CellPropertyType.BORDER_RIGHT); + EnumSet<CellPropertyType> properties = EnumSet.of( + CellPropertyType.BORDER_TOP, + CellPropertyType.BORDER_BOTTOM, + CellPropertyType.BORDER_LEFT, + CellPropertyType.BORDER_RIGHT); for (int row = range.getFirstRow(); row <= range.getLastRow(); row++) { for (int col = range.getFirstColumn(); col <= range .getLastColumn(); col++) { @@ -433,7 +435,7 @@ public final class PropertyTemplate { */ public void applyBorders(Sheet sheet) { Workbook wb = sheet.getWorkbook(); - for (Map.Entry<CellAddress, Map<CellPropertyType, Object>> entry : _propertyTemplate + for (Map.Entry<CellAddress, EnumMap<CellPropertyType, Object>> entry : _propertyTemplate .entrySet()) { CellAddress cellAddress = entry.getKey(); if (cellAddress.getRow() < wb.getSpreadsheetVersion().getMaxRows() @@ -756,11 +758,11 @@ public final class PropertyTemplate { * @param range - {@link CellRangeAddress} range of cells to remove borders. */ private void removeBorderColors(CellRangeAddress range) { - Set<CellPropertyType> properties = new HashSet<>(); - properties.add(CellPropertyType.TOP_BORDER_COLOR); - properties.add(CellPropertyType.BOTTOM_BORDER_COLOR); - properties.add(CellPropertyType.LEFT_BORDER_COLOR); - properties.add(CellPropertyType.RIGHT_BORDER_COLOR); + Set<CellPropertyType> properties = EnumSet.of( + CellPropertyType.TOP_BORDER_COLOR, + CellPropertyType.BOTTOM_BORDER_COLOR, + CellPropertyType.LEFT_BORDER_COLOR, + CellPropertyType.RIGHT_BORDER_COLOR); for (int row = range.getFirstRow(); row <= range.getLastRow(); row++) { for (int col = range.getFirstColumn(); col <= range .getLastColumn(); col++) { @@ -781,9 +783,9 @@ public final class PropertyTemplate { */ private void addProperty(int row, int col, CellPropertyType property, Object value) { CellAddress cell = new CellAddress(row, col); - Map<CellPropertyType, Object> cellProperties = _propertyTemplate.get(cell); + EnumMap<CellPropertyType, Object> cellProperties = _propertyTemplate.get(cell); if (cellProperties == null) { - cellProperties = new HashMap<>(); + cellProperties = new EnumMap<>(CellPropertyType.class); } cellProperties.put(property, value); _propertyTemplate.put(cell, cellProperties); @@ -795,7 +797,7 @@ public final class PropertyTemplate { */ private void removeProperties(int row, int col, Set<CellPropertyType> properties) { CellAddress cell = new CellAddress(row, col); - Map<CellPropertyType, Object> cellProperties = _propertyTemplate.get(cell); + EnumMap<CellPropertyType, Object> cellProperties = _propertyTemplate.get(cell); if (cellProperties != null) { cellProperties.keySet().removeAll(properties); if (cellProperties.isEmpty()) { @@ -946,6 +948,7 @@ public final class PropertyTemplate { * @deprecated See {@link #getTemplateProperty(int, int, CellPropertyType)} */ @Deprecated + @Removal(version = "7.0.0") public short getTemplateProperty(int row, int col, String propertyName) { return getTemplateProperty(new CellAddress(row, col), CellUtil.namePropertyMap.get(propertyName)); } diff --git a/poi/src/main/java/org/apache/poi/ss/util/SheetUtil.java b/poi/src/main/java/org/apache/poi/ss/util/SheetUtil.java index bc448254fa..633a785b93 100644 --- a/poi/src/main/java/org/apache/poi/ss/util/SheetUtil.java +++ b/poi/src/main/java/org/apache/poi/ss/util/SheetUtil.java @@ -257,9 +257,17 @@ public class SheetUtil { * @param str the text contained in the cell * @return the best fit cell width */ - private static double getCellWidth(float defaultCharWidth, int colspan, - CellStyle style, double minWidth, AttributedString str) { - TextLayout layout = new TextLayout(str.getIterator(), fontRenderContext); + private static double getCellWidth(float defaultCharWidth, final int colspan, + final CellStyle style, final double minWidth, final AttributedString str) { + TextLayout layout; + try { + layout = new TextLayout(str.getIterator(), fontRenderContext); + } catch (Throwable t) { + if (shouldIgnoreMissingFontSystem(t)) { + return FAILOVER_FUNCTION.apply(defaultCharWidth, colspan, style, minWidth, str); + } + throw t; + } final Rectangle2D bounds; if (style.getRotation() != 0) { /* @@ -353,26 +361,60 @@ public class SheetUtil { TextLayout layout = new TextLayout(str.getIterator(), fontRenderContext); return layout.getAdvance(); } catch (Throwable t) { - // ignore exception and return a default char width if - // the ignore-feature is enabled and the exception indicates that - // the underlying font system is not available - if (ignoreMissingFontSystem && ( - // the three types of exception usually indicate here that the font - // system is not fully installed, i.e. system libraries missing or - // some JDK classes cannot be loaded - t instanceof UnsatisfiedLinkError || - t instanceof NoClassDefFoundError || - t instanceof InternalError || - // other fatal exceptions will always be rethrown - !ExceptionUtil.isFatal(t))) { + if (shouldIgnoreMissingFontSystem(t)) { return DEFAULT_CHAR_WIDTH; } - throw t; } } /** + * A function with 5 inputs and a return value. + * @param <A> the type of the first input to the function + * @param <B> the type of the second input to the function + * @param <C> the type of the third input to the function + * @param <D> the type of the fourth input to the function + * @param <E> the type of the fifth input to the function + * @param <R> the return type of the function + * @since POI 5.4.1 + */ + @FunctionalInterface + public interface Function5Arity<A, B, C, D, E, R> { + R apply(A a, B b, C c, D d, E e); + } + + private static final Function5Arity<Float, Integer, CellStyle, Double, AttributedString, Float> DEFAULT_FAILOVER_FUNCTION = + (defaultCharWidth, colspan, style, minWidth, string) -> defaultCharWidth; + + private static Function5Arity<Float, Integer, CellStyle, Double, AttributedString, Float> FAILOVER_FUNCTION = + DEFAULT_FAILOVER_FUNCTION; + + /** + * Define a function to be used as a failover when the font system is not available. + * This function will be called with the default character width, the colspan, the cell style, + * the minimum width and the attributed string of the cell. + * <p> + * The default function will return the default character width. + * </p> + * @since POI 5.4.1 + */ + public static void setFailoverFunction(Function5Arity<Float, Integer, CellStyle, Double, AttributedString, Float> failoverFunction) { + FAILOVER_FUNCTION = failoverFunction == null ? DEFAULT_FAILOVER_FUNCTION : failoverFunction; + } + + private static boolean shouldIgnoreMissingFontSystem(final Throwable t) { + return ignoreMissingFontSystem && ( + // the three types of exception usually indicate here that the font + // system is not fully installed, i.e. system libraries missing or + // some JDK classes cannot be loaded + t instanceof UnsatisfiedLinkError || + t instanceof NoClassDefFoundError || + t instanceof InternalError || + // other fatal exceptions will always be rethrown + !ExceptionUtil.isFatal(t)); + } + + /** * Compute width of a single cell in a row * Convenience method for {@link #getCellWidth} * diff --git a/poi/src/main/java/org/apache/poi/util/DefaultTempFileCreationStrategy.java b/poi/src/main/java/org/apache/poi/util/DefaultTempFileCreationStrategy.java index 9b2e711ed4..48495c94a3 100644 --- a/poi/src/main/java/org/apache/poi/util/DefaultTempFileCreationStrategy.java +++ b/poi/src/main/java/org/apache/poi/util/DefaultTempFileCreationStrategy.java @@ -52,6 +52,9 @@ public class DefaultTempFileCreationStrategy implements TempFileCreationStrategy /** The directory where the temporary files will be created (<code>null</code> to use the default directory). */ private volatile File dir; + /** The directory where that was passed to the constructor (<code>null</code> to use the default directory). */ + private final File initDir; + /** The lock to make dir initialized only once. */ private final Lock dirLock = new ReentrantLock(); @@ -65,14 +68,23 @@ public class DefaultTempFileCreationStrategy implements TempFileCreationStrategy } /** - * Creates the strategy allowing to set the + * Creates the strategy allowing to set a custom directory for the temporary files. + * <p> + * If you provide a non-null dir as input, it must be a directory (if it already exists). + * Since POI 5.5.0, this is checked at construction time. In previous versions, it was checked + * at the first call to {@link #createTempFile(String, String)} or {@link #createTempDirectory(String)}. + * </p> * * @param dir The directory where the temporary files will be created (<code>null</code> to use the default directory). - * + * @throws IllegalArgumentException if the provided directory does not exist or is not a directory * @see Files#createTempFile(Path, String, String, FileAttribute[]) */ public DefaultTempFileCreationStrategy(File dir) { + this.initDir = dir; this.dir = dir; + if (dir != null && dir.exists() && !dir.isDirectory()) { + throw new IllegalArgumentException("The provided file is not a directory: " + dir); + } } @Override @@ -117,7 +129,11 @@ public class DefaultTempFileCreationStrategy implements TempFileCreationStrategy } protected Path getPOIFilesDirectoryPath() throws IOException { - return Paths.get(getJavaIoTmpDir(), POIFILES); + if (initDir == null) { + return Paths.get(getJavaIoTmpDir(), POIFILES); + } else { + return initDir.toPath(); + } } // Create our temp dir only once by double-checked locking diff --git a/poi/src/main/java/org/apache/poi/util/IOUtils.java b/poi/src/main/java/org/apache/poi/util/IOUtils.java index 430e895557..3487c00f96 100644 --- a/poi/src/main/java/org/apache/poi/util/IOUtils.java +++ b/poi/src/main/java/org/apache/poi/util/IOUtils.java @@ -108,6 +108,14 @@ public final class IOUtils { } /** + * @return The maximum number of bytes that should be possible to be allocated in one step. + * @since 5.4.1 + */ + public static int getByteArrayMaxOverride() { + return BYTE_ARRAY_MAX_OVERRIDE; + } + + /** * Peeks at the first 8 bytes of the stream. Returns those bytes, but * with the stream unaffected. Requires a stream that supports mark/reset, * or a PushbackInputStream. If the stream has >0 but <8 bytes, @@ -209,6 +217,27 @@ public final class IOUtils { } /** + * Reads up to {@code length} bytes from the input stream, and returns the bytes read. + * + * @param stream The byte stream of data to read. + * @param length The maximum length to read, use {@link Integer#MAX_VALUE} to read the stream + * until EOF + * @param maxLength if the input is equal to/longer than {@code maxLength} bytes, + * then throw an {@link IOException} complaining about the length. + * use {@link Integer#MAX_VALUE} to disable the check - if {@link #setByteArrayMaxOverride(int)} is + * set then that max of that value and this maxLength is used + * @return A byte array with the read bytes. + * @throws IOException If reading data fails or EOF is encountered too early for the given length. + * @throws RecordFormatException If the requested length is invalid. + * @since POI 5.4.1 + */ + public static byte[] toByteArray(InputStream stream, final long length, final int maxLength) throws IOException { + return toByteArray(stream, + length > Integer.MAX_VALUE ? Integer.MAX_VALUE : (int) length, + maxLength, true, length != Integer.MAX_VALUE); + } + + /** * Reads the input stream, and returns the bytes read. * * @param stream The byte stream of data to read. @@ -227,15 +256,12 @@ public final class IOUtils { private static byte[] toByteArray(InputStream stream, final int length, final int maxLength, final boolean checkEOFException, final boolean isLengthKnown) throws IOException { - if (length < 0 || maxLength < 0) { - throw new RecordFormatException("Can't allocate an array of length < 0"); - } final int derivedMaxLength = Math.max(maxLength, BYTE_ARRAY_MAX_OVERRIDE); if ((length != Integer.MAX_VALUE) || (derivedMaxLength != Integer.MAX_VALUE)) { checkLength(length, derivedMaxLength); } - final int derivedLen = isLengthKnown ? Math.min(length, derivedMaxLength) : derivedMaxLength; + final int derivedLen = isLengthKnown && length >= 0 ? Math.min(length, derivedMaxLength) : derivedMaxLength; final int byteArrayInitLen = calculateByteArrayInitLength(isLengthKnown, length, derivedMaxLength); final int internalBufferLen = DEFAULT_BUFFER_SIZE; try (UnsynchronizedByteArrayOutputStream baos = UnsynchronizedByteArrayOutputStream.builder().setBufferSize(byteArrayInitLen).get()) { @@ -254,7 +280,7 @@ public final class IOUtils { throwRecordTruncationException(derivedMaxLength); } - if (checkEOFException && derivedLen != Integer.MAX_VALUE && totalBytes < derivedLen) { + if (checkEOFException && length >= 0 && derivedLen != Integer.MAX_VALUE && totalBytes < derivedLen) { throw new EOFException("unexpected EOF - expected len: " + derivedLen + " - actual len: " + totalBytes); } @@ -575,7 +601,6 @@ public final class IOUtils { return Arrays.copyOfRange(src, offset, offset+realLength); } - /** * Simple utility function to check that you haven't hit EOF * when reading a byte. @@ -592,6 +617,28 @@ public final class IOUtils { return b; } + /** + * Creates a new file in the given parent directory with the given name. + * There is a check to prevent path traversal attacks. Only path traversal + * that would lead to a file outside the parent directory is regarded as an issue. + * + * @param parent The parent directory where the file should be created. + * @param name The name of the file to create. + * @return The created file. + * @throws IOException If path traversal is detected. + * @since POI 5.5.0 + */ + public static File newFile(final File parent, final String name) throws IOException { + final File file = new File(parent, name); + if (!file.toPath().toAbsolutePath().normalize().startsWith( + parent.toPath().toAbsolutePath().normalize() + )) { + throw new IOException(String.format( + Locale.ROOT, "Failing due to path traversal in `%s`", name)); + } + return file; + } + private static void throwRFE(long length, int maxLength) { throw new RecordFormatException(String.format(Locale.ROOT, "Tried to allocate an array of length %,d" + ", but the maximum length for this record type is %,d.%n" + diff --git a/poi/src/main/java/org/apache/poi/util/TempFile.java b/poi/src/main/java/org/apache/poi/util/TempFile.java index 46bf8ccc8b..f5ab4e6f4a 100644 --- a/poi/src/main/java/org/apache/poi/util/TempFile.java +++ b/poi/src/main/java/org/apache/poi/util/TempFile.java @@ -19,6 +19,8 @@ package org.apache.poi.util; import java.io.File; import java.io.IOException; +import java.util.Objects; +import java.util.function.Supplier; /** * Interface for creating temporary files. Collects them all into one directory by default. @@ -27,7 +29,14 @@ public final class TempFile { /** The strategy used by {@link #createTempFile(String, String)} to create the temporary files. */ private static TempFileCreationStrategy strategy = new DefaultTempFileCreationStrategy(); - /** Define a constant for this property as it is sometimes mistypes as "tempdir" otherwise */ + /** If set for the thread, this is used instead of the strategy variable above. */ + private static final ThreadLocal<TempFileCreationStrategy> threadLocalStrategy = new ThreadLocal<>(); + static { + // allow to clear all thread-locals via ThreadLocalUtil + ThreadLocalUtil.registerCleaner(threadLocalStrategy::remove); + } + + /** Define a constant for this property as it is sometimes mistyped as "tempdir" otherwise */ public static final String JAVA_IO_TMPDIR = "java.io.tmpdir"; private TempFile() { @@ -47,6 +56,21 @@ public final class TempFile { } TempFile.strategy = strategy; } + + /** + * Configures the strategy used by {@link #createTempFile(String, String)} to create the temporary files. + * + * @param strategy The new strategy to be used to create the temporary files for this thread. + * <code>null</code> can be used to reset the strategy for this thread to the default one. + * @since POI 5.5.0 + */ + public static void setThreadLocalTempFileCreationStrategy(TempFileCreationStrategy strategy) { + if (strategy == null) { + threadLocalStrategy.remove(); + } else { + threadLocalStrategy.set(strategy); + } + } /** * Creates a new and empty temporary file. By default, files are collected into one directory and are not @@ -64,10 +88,44 @@ public final class TempFile { * @throws IOException If no temporary file could be created. */ public static File createTempFile(String prefix, String suffix) throws IOException { - return strategy.createTempFile(prefix, suffix); + return getStrategy().createTempFile(prefix, suffix); } public static File createTempDirectory(String name) throws IOException { - return strategy.createTempDirectory(name); + return getStrategy().createTempDirectory(name); + } + + /** + * Executes the given task ensuring that POI will use the given temp file creation strategy + * within the scope of the given task. The change of strategy is not visible to other threads, + * and the previous strategy is restored after the task completed (normally or exceptionally). + * + * @param newStrategy the temp file strategy to be used in the scope of the given task + * @param task the task to be executed with the given temp file strategy + * @return the result of the given task + * + * @since POI 5.5.0 + */ + public static <R> R withStrategy(TempFileCreationStrategy newStrategy, Supplier<? extends R> task) { + Objects.requireNonNull(newStrategy, "newStrategy"); + Objects.requireNonNull(task, "task"); + + TempFileCreationStrategy oldStrategy = threadLocalStrategy.get(); + try { + threadLocalStrategy.set(newStrategy); + return task.get(); + } finally { + setThreadLocalTempFileCreationStrategy(oldStrategy); + } + } + + private static TempFileCreationStrategy getStrategy() { + final TempFileCreationStrategy s = threadLocalStrategy.get(); + if (s == null) { + threadLocalStrategy.remove(); + return strategy; + } else { + return s; + } } } diff --git a/poi/src/main/java/org/apache/poi/util/XMLHelper.java b/poi/src/main/java/org/apache/poi/util/XMLHelper.java index 341062d7de..071ae08f54 100644 --- a/poi/src/main/java/org/apache/poi/util/XMLHelper.java +++ b/poi/src/main/java/org/apache/poi/util/XMLHelper.java @@ -30,6 +30,7 @@ import static javax.xml.stream.XMLOutputFactory.IS_REPAIRING_NAMESPACES; import java.io.StringReader; import java.lang.reflect.Method; +import java.util.Locale; import java.util.concurrent.TimeUnit; import javax.xml.parsers.DocumentBuilder; @@ -49,7 +50,9 @@ import javax.xml.validation.SchemaFactory; import org.apache.logging.log4j.Level; import org.apache.logging.log4j.LogBuilder; import org.apache.logging.log4j.Logger; +import org.apache.poi.POIException; import org.apache.poi.logging.PoiLogManager; +import org.w3c.dom.Node; import org.xml.sax.ErrorHandler; import org.xml.sax.InputSource; import org.xml.sax.SAXException; @@ -77,7 +80,6 @@ public final class XMLHelper { "org.apache.xerces.util.SecurityManager" }; - private static final Logger LOG = PoiLogManager.getLogger(XMLHelper.class); private static long lastLog; @@ -253,8 +255,56 @@ public final class XMLHelper { return factory; } + /** + * Counts the depth of the DOM tree starting from the given node. + * + * @param node the node to check + * @param maxSupportedDepth the maximum supported depth of the DOM tree + * @return the depth + * @throws POIException if the depth exceeds <code>maxSupportedDepth</code> + */ + public static int getDepthOfChildNodes(final Node node, final int maxSupportedDepth) throws POIException { + return getDepthOfChildNodes(node, maxSupportedDepth, 0); + } + + private static int getDepthOfChildNodes(final Node node, final int maxSupportedDepth, + final int nodeDepth) throws POIException { + final int currentDepth = nodeDepth + 1; + int maxDepth = currentDepth; + Node child = node.getFirstChild(); + while (child != null) { + int childDepth = getDepthOfChildNodes(child, maxSupportedDepth, currentDepth); + if (childDepth > maxDepth) { + maxDepth = childDepth; + if (maxDepth > maxSupportedDepth) { + throw new POIException(String.format(Locale.ROOT, + "Node depth exceeds maximum supported depth of %s" , + maxSupportedDepth)); + } + } + child = child.getNextSibling(); + } + return maxDepth; + } + + private static Object _xercesSecurityManager; + private static volatile boolean _xercesSecurityManagerSet = false; private static Object getXercesSecurityManager() { + if (_xercesSecurityManagerSet) { + return _xercesSecurityManager; + } else { + synchronized (XMLHelper.class) { + if (!_xercesSecurityManagerSet) { + _xercesSecurityManager = tryGetXercesSecurityManager(); + _xercesSecurityManagerSet = true; + } + } + return _xercesSecurityManager; + } + } + + private static Object tryGetXercesSecurityManager() { // Try built-in JVM one first, standalone if not for (String securityManagerClassName : SECURITY_MANAGERS) { try { @@ -272,7 +322,6 @@ public final class XMLHelper { logThrowable(e, "SAX Feature unsupported", securityManagerClassName); } } - return null; } diff --git a/poi/src/test/java/org/apache/poi/POIDataSamples.java b/poi/src/test/java/org/apache/poi/POIDataSamples.java index e15843f377..f976cd0c91 100644 --- a/poi/src/test/java/org/apache/poi/POIDataSamples.java +++ b/poi/src/test/java/org/apache/poi/POIDataSamples.java @@ -169,7 +169,7 @@ public final class POIDataSamples { + "' not found in data dir '" + _resolvedDataDir.getAbsolutePath() + "'"); } try { - if(sampleFileName.length() > 0) { + if(!sampleFileName.isEmpty()) { String fn = sampleFileName; if(fn.indexOf('/') > 0) { fn = fn.substring(fn.indexOf('/')+1); diff --git a/poi/src/test/java/org/apache/poi/hssf/eventusermodel/TestFormatTrackingHSSFListener.java b/poi/src/test/java/org/apache/poi/hssf/eventusermodel/TestFormatTrackingHSSFListener.java index 2a99b3b395..3ef75d7f3d 100644 --- a/poi/src/test/java/org/apache/poi/hssf/eventusermodel/TestFormatTrackingHSSFListener.java +++ b/poi/src/test/java/org/apache/poi/hssf/eventusermodel/TestFormatTrackingHSSFListener.java @@ -16,7 +16,9 @@ ==================================================================== */ package org.apache.poi.hssf.eventusermodel; + import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotEquals; import static org.junit.jupiter.api.Assertions.assertNotNull; import static org.junit.jupiter.api.Assertions.assertTrue; @@ -96,7 +98,7 @@ final class TestFormatTrackingHSSFListener { // Should always give us a string String s = listener.formatNumberDateCell(cvr); assertNotNull(s); - assertTrue(s.length() > 0); + assertNotEquals(0, s.length()); } } diff --git a/poi/src/test/java/org/apache/poi/hssf/model/TestDrawingAggregate.java b/poi/src/test/java/org/apache/poi/hssf/model/TestDrawingAggregate.java index 12854be920..8d07fc4d0e 100644 --- a/poi/src/test/java/org/apache/poi/hssf/model/TestDrawingAggregate.java +++ b/poi/src/test/java/org/apache/poi/hssf/model/TestDrawingAggregate.java @@ -118,11 +118,7 @@ class TestDrawingAggregate { UnsynchronizedByteArrayOutputStream out = UnsynchronizedByteArrayOutputStream.builder().get(); for (RecordBase rb : aggRecords) { Record r = (org.apache.poi.hssf.record.Record) rb; - try { - out.write(r.serialize()); - } catch (IOException e) { - throw new RuntimeException(e); - } + out.write(r.serialize()); } return out.toByteArray(); } @@ -263,11 +259,7 @@ class TestDrawingAggregate { UnsynchronizedByteArrayOutputStream out = UnsynchronizedByteArrayOutputStream.builder().get(); for (RecordBase rb : records) { Record r = (org.apache.poi.hssf.record.Record) rb; - try { - out.write(r.serialize()); - } catch (IOException e) { - throw new RuntimeException(e); - } + out.write(r.serialize()); } return out.toByteArray(); } diff --git a/poi/src/test/java/org/apache/poi/hssf/model/TestEscherRecordFactory.java b/poi/src/test/java/org/apache/poi/hssf/model/TestEscherRecordFactory.java index 091802098c..f641b6eeb3 100644 --- a/poi/src/test/java/org/apache/poi/hssf/model/TestEscherRecordFactory.java +++ b/poi/src/test/java/org/apache/poi/hssf/model/TestEscherRecordFactory.java @@ -42,11 +42,7 @@ class TestEscherRecordFactory { UnsynchronizedByteArrayOutputStream out = UnsynchronizedByteArrayOutputStream.builder().get(); for (RecordBase rb : records) { Record r = (org.apache.poi.hssf.record.Record) rb; - try { - out.write(r.serialize()); - } catch (IOException e) { - throw new RuntimeException(e); - } + out.write(r.serialize()); } return out.toByteArray(); } diff --git a/poi/src/test/java/org/apache/poi/hssf/model/TestWorkbook.java b/poi/src/test/java/org/apache/poi/hssf/model/TestWorkbook.java index 76b306b1d9..5b277e52cc 100644 --- a/poi/src/test/java/org/apache/poi/hssf/model/TestWorkbook.java +++ b/poi/src/test/java/org/apache/poi/hssf/model/TestWorkbook.java @@ -22,10 +22,12 @@ import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertNotNull; import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; import java.io.IOException; +import org.apache.commons.io.output.UnsynchronizedByteArrayOutputStream; import org.apache.poi.hssf.record.CountryRecord; import org.apache.poi.hssf.record.FontRecord; import org.apache.poi.hssf.record.RecalcIdRecord; @@ -170,4 +172,56 @@ final class TestWorkbook { int newRecordsCount = iwb.getNumRecords(); assertEquals(oldRecordsCount, newRecordsCount, "records count after getWriteAccess"); } + + @Test + void testSetUserName() throws IOException { + // normal username + setAndReadUserName("username", false); + + // 109 characters max if no "multibyte" character + setAndReadUserName("1234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789", false); + + // 54 max if there is at least one "multibyte" character + setAndReadUserName("€23456789012345678901234567890123456789012345678901234", false); + + // also works for very strange characters + setAndReadUserName("\uD801\uDC37\uD852\uDF62€$ⵃⵥꭓꭃꭦ﹄４Ｕｶ\uD800\uDFB1\uD800\uDFC9\uD834\uDF45\uD834\uDF4B\uD83E\uDF22\uD83E\uDF53\uD83E\uDFB5\uD83E\uDFF6\uD801\uDC37\uD852\uDF62€$ⵃⵥꭓꭃꭦ﹄４Ｕｶ\uD800\uDFB1\uD800\uDFC9\uD834\uDF45\uD834\uDF4B", false); + + // fails with longer strings + setAndReadUserName("12345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890", + true); + setAndReadUserName("€234567890123456789012345678901234567890123456789012345", true); + setAndReadUserName("\uD801\uDC37\uD852\uDF62€$ⵃⵥꭓꭃꭦ﹄４Ｕｶ\uD800\uDFB1\uD800\uDFC9\uD834\uDF45\uD834\uDF4B\uD83E\uDF22\uD83E\uDF53\uD83E\uDFB5\uD83E\uDFF6\uD801\uDC37\uD852\uDF62€$ⵃⵥꭓꭃꭦ﹄４Ｕｶ\uD800\uDFB1\uD800\uDFC9\uD834\uDF45\uD834\uDF4B\uDF4B", + true); + } + + private static void setAndReadUserName(String username, boolean fails) throws IOException { + try (HSSFWorkbook wb = new HSSFWorkbook()) { + InternalWorkbook iwb = wb.getInternalWorkbook(); + + String prev = iwb.getWriteAccess().getUsername(); + if (fails) { + assertThrows(IllegalArgumentException.class, + () -> iwb.getWriteAccess().setUsername(username), + "Expected to fail with username " + username); + assertEquals(prev, iwb.getWriteAccess().getUsername(), + "Username should not have been changed, but had: " + prev + " and " + + iwb.getWriteAccess().getUsername()); + + // cannot test more if username is too long + return; + } else { + iwb.getWriteAccess().setUsername(username); + } + + assertEquals(username, iwb.getWriteAccess().getUsername()); + try (UnsynchronizedByteArrayOutputStream os = UnsynchronizedByteArrayOutputStream.builder().get()) { + wb.write(os); + try (HSSFWorkbook wb2 = new HSSFWorkbook(os.toInputStream())) { + InternalWorkbook iwb2 = wb2.getInternalWorkbook(); + assertEquals(username, iwb2.getWriteAccess().getUsername()); + } + } + } + } } diff --git a/poi/src/test/java/org/apache/poi/hssf/record/TestRecordFactory.java b/poi/src/test/java/org/apache/poi/hssf/record/TestRecordFactory.java index a44cce0e42..fb3f44eb6c 100644 --- a/poi/src/test/java/org/apache/poi/hssf/record/TestRecordFactory.java +++ b/poi/src/test/java/org/apache/poi/hssf/record/TestRecordFactory.java @@ -211,11 +211,7 @@ final class TestRecordFactory { }; UnsynchronizedByteArrayOutputStream baos = UnsynchronizedByteArrayOutputStream.builder().get(); for (org.apache.poi.hssf.record.Record rec : recs) { - try { - baos.write(rec.serialize()); - } catch (IOException e) { - throw new RuntimeException(e); - } + baos.write(rec.serialize()); } //simulate the bad padding at the end of the workbook stream in attachment 23483 of bug 46987 baos.write(0x00); diff --git a/poi/src/test/java/org/apache/poi/hssf/record/TestWriteAccessRecord.java b/poi/src/test/java/org/apache/poi/hssf/record/TestWriteAccessRecord.java index ee3cfec38b..8286f442c0 100644 --- a/poi/src/test/java/org/apache/poi/hssf/record/TestWriteAccessRecord.java +++ b/poi/src/test/java/org/apache/poi/hssf/record/TestWriteAccessRecord.java @@ -93,4 +93,47 @@ final class TestWriteAccessRecord { confirmRecordEncoding(WriteAccessRecord.sid, expectedEncoding, rec.serialize()); } + + @Test + void testUTF16LE() { + byte[] data = HexRead.readFromString("" + + "5c 00 70 00 1C 00 01 " + + "44 00 61 00 74 00 61 00 20 00 44 00 79 00 6e 00 " + + "61 00 6d 00 69 00 63 00 73 00 27 00 20 00 53 00 " + + "70 00 72 00 65 00 61 00 64 00 42 00 75 00 69 00 " + + "6c 00 64 00 65 00 72 00 20 00 20 00 20 00 20 00 " + + "20 00 20 00 20 00 20 00 20 00 20 00 20 00 20 00 " + + "20 00 20 00 20 00 20 00 20 00 20 00 20 00 20 00 " + + "20 00 20 00 20 00 20 00 20 00 20 00 20 00 20 00 " + + "20 00 20 00 20 00" + ); + RecordInputStream in = TestcaseRecordInputStream.create(data); + + WriteAccessRecord rec = new WriteAccessRecord(in); + + assertEquals("Data Dynamics' SpreadBuilder", rec.getUsername()); + } + + @Test + void testUTF16LE_wrong_size() { + // "0x51" on position 5 is an incorrect size, as it would require 162 bytes to encode as UTF-16LE + // the spec only allows up to 109 bytes for the string in this record, but it seems some broken + // software out there will generate such a file + byte[] data = HexRead.readFromString("" + + "5c 00 70 00 51 00 01 " + + "44 00 61 00 74 00 61 00 20 00 44 00 79 00 6e 00 " + + "61 00 6d 00 69 00 63 00 73 00 27 00 20 00 53 00 " + + "70 00 72 00 65 00 61 00 64 00 42 00 75 00 69 00 " + + "6c 00 64 00 65 00 72 00 20 00 20 00 20 00 20 00 " + + "20 00 20 00 20 00 20 00 20 00 20 00 20 00 20 00 " + + "20 00 20 00 20 00 20 00 20 00 20 00 20 00 20 00 " + + "20 00 20 00 20 00 20 00 20 00 20 00 20 00 20 00 " + + "20 00 20 00 20 00" + ); + RecordInputStream in = TestcaseRecordInputStream.create(data); + + WriteAccessRecord rec = new WriteAccessRecord(in); + + assertEquals("Data Dynamics' SpreadBuilder", rec.getUsername()); + } } diff --git a/poi/src/test/java/org/apache/poi/hssf/usermodel/TestBugs.java b/poi/src/test/java/org/apache/poi/hssf/usermodel/TestBugs.java index 3b026b2ce1..df7da70e19 100644 --- a/poi/src/test/java/org/apache/poi/hssf/usermodel/TestBugs.java +++ b/poi/src/test/java/org/apache/poi/hssf/usermodel/TestBugs.java @@ -26,6 +26,8 @@ import java.awt.image.BufferedImage; import java.io.ByteArrayInputStream; import java.io.File; import java.io.IOException; +import java.net.URI; +import java.net.URISyntaxException; import java.net.URL; import java.util.ArrayList; import java.util.Arrays; @@ -2316,12 +2318,12 @@ final class TestBugs extends BaseTestBugzillaIssues { } @Test - void test46515() throws IOException { + void test46515() throws IOException, URISyntaxException { try (Workbook wb = openSampleWorkbook("46515.xls")) { // Get structure from webservice String urlString = "https://poi.apache.org/components/spreadsheet/images/calendar.jpg"; - URL structURL = new URL(urlString); + URL structURL = new URI(urlString).toURL(); BufferedImage bimage; try { bimage = ImageIO.read(structURL); diff --git a/poi/src/test/java/org/apache/poi/hssf/usermodel/TestHSSFDateUtil.java b/poi/src/test/java/org/apache/poi/hssf/usermodel/TestHSSFDateUtil.java index 2949dbeeee..61cd1aba69 100644 --- a/poi/src/test/java/org/apache/poi/hssf/usermodel/TestHSSFDateUtil.java +++ b/poi/src/test/java/org/apache/poi/hssf/usermodel/TestHSSFDateUtil.java @@ -27,6 +27,7 @@ import java.util.TimeZone; import org.apache.poi.hssf.HSSFTestDataSamples; import org.apache.poi.hssf.model.InternalWorkbook; +import org.apache.poi.ss.usermodel.DataFormatter; import org.apache.poi.ss.usermodel.DateUtil; import org.apache.poi.util.LocaleUtil; import org.junit.jupiter.api.AfterAll; @@ -60,7 +61,7 @@ class TestHSSFDateUtil { HSSFWorkbook workbook = HSSFTestDataSamples.openSampleWorkbook("DateFormats.xls"); HSSFSheet sheet = workbook.getSheetAt(0); - InternalWorkbook wb = workbook.getWorkbook(); + InternalWorkbook wb = workbook.getWorkbook(); assertNotNull(wb); HSSFRow row; @@ -115,4 +116,27 @@ class TestHSSFDateUtil { workbook.close(); } + + @Test + void testIsADateFormat() throws IOException { + try (HSSFWorkbook workbook = new HSSFWorkbook()) { + HSSFSheet sheet = workbook.createSheet(); + HSSFRow row = sheet.createRow(0); + HSSFCell cell = row.createCell(0); + cell.setCellValue(45825.5); // 2025-06-17 (midday) + HSSFCellStyle style = workbook.createCellStyle(); + style.setDataFormat(workbook.createDataFormat().getFormat("DD MMMM, YYYY hh:mm:ss.000 AM/PM")); + cell.setCellStyle(style); + DateUtil.enableThreadLocalCache(false); + try { + assertTrue(DateUtil.isCellDateFormatted(cell), "cell is date formatted?"); + DataFormatter formatter = new DataFormatter(); + String formattedValue = formatter.formatCellValue(cell); + assertEquals("17 June, 2025 12:00:00.000 PM", formattedValue); + } finally { + DateUtil.enableThreadLocalCache(true); + } + } + } + } diff --git a/poi/src/test/java/org/apache/poi/hssf/usermodel/TestHSSFRowCopyRowFrom.java b/poi/src/test/java/org/apache/poi/hssf/usermodel/TestHSSFRowCopyRowFrom.java new file mode 100644 index 0000000000..67dcc38f46 --- /dev/null +++ b/poi/src/test/java/org/apache/poi/hssf/usermodel/TestHSSFRowCopyRowFrom.java @@ -0,0 +1,130 @@ +/* ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ + +package org.apache.poi.hssf.usermodel; + +import org.apache.commons.io.output.UnsynchronizedByteArrayOutputStream; +import org.apache.poi.ss.usermodel.Cell; +import org.apache.poi.ss.usermodel.CellCopyContext; +import org.apache.poi.ss.usermodel.CellCopyPolicy; +import org.apache.poi.ss.usermodel.CellStyle; +import org.apache.poi.ss.usermodel.CreationHelper; +import org.apache.poi.ss.usermodel.DateUtil; +import org.apache.poi.ss.usermodel.Row; +import org.apache.poi.ss.usermodel.Sheet; +import org.apache.poi.ss.usermodel.Workbook; +import org.junit.jupiter.api.Test; + +import java.io.ByteArrayInputStream; +import java.io.ByteArrayOutputStream; +import java.io.IOException; +import java.io.OutputStream; +import java.nio.file.Files; +import java.nio.file.Paths; +import java.time.LocalDateTime; +import java.time.LocalTime; +import java.time.format.DateTimeFormatter; +import java.util.Iterator; + +public class TestHSSFRowCopyRowFrom { + @Test + void testCopyFrom() throws IOException { + CellCopyPolicy cellCopyPolicy = new CellCopyPolicy.Builder() + .cellFormula(false) // NOTE: setting to false allows for copying the evaluated formula value. + .cellStyle(CellCopyPolicy.DEFAULT_COPY_CELL_STYLE_POLICY) + .cellValue(CellCopyPolicy.DEFAULT_COPY_CELL_VALUE_POLICY) + .condenseRows(CellCopyPolicy.DEFAULT_CONDENSE_ROWS_POLICY) + .copyHyperlink(CellCopyPolicy.DEFAULT_COPY_HYPERLINK_POLICY) + .mergeHyperlink(CellCopyPolicy.DEFAULT_MERGE_HYPERLINK_POLICY) + .mergedRegions(CellCopyPolicy.DEFAULT_COPY_MERGED_REGIONS_POLICY) + .rowHeight(CellCopyPolicy.DEFAULT_COPY_ROW_HEIGHT_POLICY) + .build(); + + final LocalDateTime localDateTime = LocalDateTime.of(2023, 1, 1, 0, 0, 0); + final LocalDateTime nonValidExcelDate = LocalDateTime.of(1899, 12, 31, 0, 0, 0); + final Object[][] data = { + {"transaction_id", "transaction_date", "transaction_time"}, + {75, localDateTime, nonValidExcelDate.plusHours(9).plusMinutes(53).plusSeconds(44).toLocalTime()}, + {78, localDateTime, nonValidExcelDate.plusHours(9).plusMinutes(55).plusSeconds(16).toLocalTime()} + }; + + final UnsynchronizedByteArrayOutputStream workbookOutputStream = + UnsynchronizedByteArrayOutputStream.builder().get(); + try (Workbook workbook = new HSSFWorkbook()) { + final Sheet sheet = workbook.createSheet("SomeSheetName"); + populateSheet(sheet, data); + setCellStyles(sheet, workbook); + workbook.write(workbookOutputStream); + } + + try (HSSFWorkbook originalWorkbook = new HSSFWorkbook(workbookOutputStream.toInputStream())) { + final Iterator<Sheet> originalSheetsIterator = originalWorkbook.sheetIterator(); + final CellCopyContext cellCopyContext = new CellCopyContext(); + + while (originalSheetsIterator.hasNext()) { + final HSSFSheet originalSheet = (HSSFSheet) originalSheetsIterator.next(); + final String originalSheetName = originalSheet.getSheetName(); + final Iterator<Row> originalRowsIterator = originalSheet.rowIterator(); + + try (HSSFWorkbook newWorkbook = new HSSFWorkbook()) { + final HSSFSheet newSheet = newWorkbook.createSheet(originalSheetName); + while (originalRowsIterator.hasNext()) { + HSSFRow originalRow = (HSSFRow) originalRowsIterator.next(); + HSSFRow newRow = newSheet.createRow(originalRow.getRowNum()); + newRow.copyRowFrom(originalRow, cellCopyPolicy, cellCopyContext); + } + } + } + } + } + + private static void populateSheet(Sheet sheet, Object[][] data) { + int rowCount = 0; + for (Object[] dataRow : data) { + Row row = sheet.createRow(rowCount++); + int columnCount = 0; + + for (Object field : dataRow) { + Cell cell = row.createCell(columnCount++); + if (field instanceof String) { + cell.setCellValue((String) field); + } else if (field instanceof Integer) { + cell.setCellValue((Integer) field); + } else if (field instanceof Long) { + cell.setCellValue((Long) field); + } else if (field instanceof LocalDateTime) { + cell.setCellValue((LocalDateTime) field); + } else if (field instanceof LocalTime) { + cell.setCellValue(DateUtil.convertTime(DateTimeFormatter.ISO_LOCAL_TIME.format((LocalTime) field))); + } + } + } + } + + void setCellStyles(Sheet sheet, Workbook workbook) { + CreationHelper creationHelper = workbook.getCreationHelper(); + CellStyle dayMonthYearCellStyle = workbook.createCellStyle(); + dayMonthYearCellStyle.setDataFormat(creationHelper.createDataFormat().getFormat("dd/mm/yyyy")); + CellStyle hourMinuteSecond = workbook.createCellStyle(); + hourMinuteSecond.setDataFormat((short) 21); // 21 represents format h:mm:ss + for (int rowNum = sheet.getFirstRowNum() + 1; rowNum < sheet.getLastRowNum() + 1; rowNum++) { + Row row = sheet.getRow(rowNum); + row.getCell(1).setCellStyle(dayMonthYearCellStyle); + row.getCell(2).setCellStyle(hourMinuteSecond); + } + } +} diff --git a/poi/src/test/java/org/apache/poi/hssf/util/TestHSSFColor.java b/poi/src/test/java/org/apache/poi/hssf/util/TestHSSFColor.java index 059dbb28b3..1bde058114 100644 --- a/poi/src/test/java/org/apache/poi/hssf/util/TestHSSFColor.java +++ b/poi/src/test/java/org/apache/poi/hssf/util/TestHSSFColor.java @@ -17,6 +17,7 @@ package org.apache.poi.hssf.util; +import java.awt.Color; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertTrue; @@ -56,4 +57,15 @@ final class TestHSSFColor { triplets.get(HSSFColorPredefined.YELLOW.getHexString()) ); } + + @Test + void testRgbAndColorWorkTheSame() { + Color color = java.awt.Color.YELLOW; + @SuppressWarnings("deprecation") + HSSFColor fromColor = new HSSFColor(10, 20, color); + HSSFColor fromRgb = new HSSFColor(10, 20, color.getRGB()); + + assertEquals(fromColor, fromRgb, "Both colors are equal"); + assertEquals(fromColor.hashCode(), fromRgb.hashCode(), "Both have the same hash code"); + } } diff --git a/poi/src/test/java/org/apache/poi/poifs/filesystem/TestPOIFSStream.java b/poi/src/test/java/org/apache/poi/poifs/filesystem/TestPOIFSStream.java index dcbf5145a0..9dd6043ae1 100644 --- a/poi/src/test/java/org/apache/poi/poifs/filesystem/TestPOIFSStream.java +++ b/poi/src/test/java/org/apache/poi/poifs/filesystem/TestPOIFSStream.java @@ -2734,6 +2734,15 @@ final class TestPOIFSStream { } } + @Test + void testDeepData() throws IOException { + try (InputStream stream = POIDataSamples.getPOIFSInstance().openResourceAsStream("deep-data.bin")) { + IOException ex = assertThrows(IOException.class, + () -> new POIFSFileSystem(stream)); + assertEquals("Property tree too deep, likely a corrupt file", ex.getMessage()); + } + } + @Disabled("Takes a long time to run") @Test void performance() throws Exception { @@ -2781,4 +2790,5 @@ final class TestPOIFSStream { } } } + } diff --git a/poi/src/test/java/org/apache/poi/ss/format/TestCellFormat.java b/poi/src/test/java/org/apache/poi/ss/format/TestCellFormat.java index d9572117f4..feb56716a7 100644 --- a/poi/src/test/java/org/apache/poi/ss/format/TestCellFormat.java +++ b/poi/src/test/java/org/apache/poi/ss/format/TestCellFormat.java @@ -20,6 +20,7 @@ import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertNotNull; import static org.junit.jupiter.api.Assertions.assertTrue; +import java.awt.Color; import java.io.IOException; import java.text.ParseException; import java.text.SimpleDateFormat; @@ -33,6 +34,7 @@ import javax.swing.JLabel; import org.apache.poi.hssf.usermodel.HSSFWorkbook; import org.apache.poi.hssf.util.HSSFColor; import org.apache.poi.ss.usermodel.Cell; +import org.apache.poi.ss.usermodel.CellType; import org.apache.poi.ss.usermodel.DateUtil; import org.apache.poi.ss.usermodel.Row; import org.apache.poi.ss.usermodel.Sheet; @@ -1041,11 +1043,129 @@ class TestCellFormat { @Test void testNamedColors() { - assertTrue(CellFormatPart.NAMED_COLORS.size() >= HSSFColor.HSSFColorPredefined.values().length); - Stream.of("GREEN", "Green", "RED", "Red", "BLUE", "Blue", "YELLOW", "Yellow") - .map(CellFormatPart.NAMED_COLORS::get) + // Make sure we have all standard named colors defined + // and are returned as non-null regardless of case + Stream.of("black", "white", "red", "green", "blue", "yellow", "magenta", "cyan", + "Black", "White", "Red", "Green", "Blue", "Yellow", "Magenta", "Cyan", + "BLACK", "WHITE", "RED", "GREEN", "BLUE", "YELLOW", "MAGENTA", "CYAN") + .map(CellFormatPart::getColor) .forEach(Assertions::assertNotNull); } + + @Test + void testIndexedColorsExist() { + // Make sure the standard indexed colors are returned correctly and regardless of case + for (int i = 0; i < 56; ++i) { + assertNotNull(CellFormatPart.getColor("Color " + (i + 1))); + assertNotNull(CellFormatPart.getColor("COLOR" + (i + 1))); + assertNotNull(CellFormatPart.getColor("color" + (i + 1))); + } + } + + @Test + void verifyNamedColors() { + assertEquals(CellFormatPart.getColor("Black"), new Color(0x000000)); + assertEquals(CellFormatPart.getColor("white"), new Color(0xFFFFFF)); + assertEquals(CellFormatPart.getColor("RED"), new Color(0xFF0000)); + assertEquals(CellFormatPart.getColor("Green"), new Color(0x00FF00)); + assertEquals(CellFormatPart.getColor("blue"), new Color(0x0000FF)); + assertEquals(CellFormatPart.getColor("YELLOW"), new Color(0xFFFF00)); + assertEquals(CellFormatPart.getColor("Magenta"), new Color(0xFF00FF)); + assertEquals(CellFormatPart.getColor("cyan"), new Color(0x00FFFF)); + } + + @Test + void verifyIndexedColors() { + assertEquals(CellFormatPart.getColor("Color1"), CellFormatPart.getColor("black")); + assertEquals(CellFormatPart.getColor("color2"), CellFormatPart.getColor("white")); + assertEquals(CellFormatPart.getColor("Color3"), CellFormatPart.getColor("red")); + assertEquals(CellFormatPart.getColor("color4"), CellFormatPart.getColor("green")); + assertEquals(CellFormatPart.getColor("Color5"), CellFormatPart.getColor("blue")); + assertEquals(CellFormatPart.getColor("color6"), CellFormatPart.getColor("yellow")); + assertEquals(CellFormatPart.getColor("Color7"), CellFormatPart.getColor("magenta")); + assertEquals(CellFormatPart.getColor("color8"), CellFormatPart.getColor("cyan")); + assertEquals(CellFormatPart.getColor("Color9"), new Color(0x800000)); + assertEquals(CellFormatPart.getColor("color10"), new Color(0x008000)); + assertEquals(CellFormatPart.getColor("Color11"), new Color(0x000080)); + assertEquals(CellFormatPart.getColor("color12"), new Color(0x808000)); + assertEquals(CellFormatPart.getColor("Color13"), new Color(0x800080)); + assertEquals(CellFormatPart.getColor("color14"), new Color(0x008080)); + assertEquals(CellFormatPart.getColor("Color15"), new Color(0xC0C0C0)); + assertEquals(CellFormatPart.getColor("color16"), new Color(0x808080)); + assertEquals(CellFormatPart.getColor("Color17"), new Color(0x9999FF)); + assertEquals(CellFormatPart.getColor("COLOR18"), new Color(0x993366)); + assertEquals(CellFormatPart.getColor("Color19"), new Color(0xFFFFCC)); + assertEquals(CellFormatPart.getColor("color20"), new Color(0xCCFFFF)); + assertEquals(CellFormatPart.getColor("Color21"), new Color(0x660066)); + assertEquals(CellFormatPart.getColor("COLOR22"), new Color(0xFF8080)); + assertEquals(CellFormatPart.getColor("Color23"), new Color(0x0066CC)); + assertEquals(CellFormatPart.getColor("color24"), new Color(0xCCCCFF)); + assertEquals(CellFormatPart.getColor("Color25"), new Color(0x000080)); + assertEquals(CellFormatPart.getColor("color26"), new Color(0xFF00FF)); + assertEquals(CellFormatPart.getColor("Color27"), new Color(0xFFFF00)); + assertEquals(CellFormatPart.getColor("COLOR28"), new Color(0x00FFFF)); + assertEquals(CellFormatPart.getColor("Color29"), new Color(0x800080)); + assertEquals(CellFormatPart.getColor("color30"), new Color(0x800000)); + assertEquals(CellFormatPart.getColor("Color31"), new Color(0x008080)); + assertEquals(CellFormatPart.getColor("Color32"), new Color(0x0000FF)); + assertEquals(CellFormatPart.getColor("Color33"), new Color(0x00CCFF)); + assertEquals(CellFormatPart.getColor("Color34"), new Color(0xCCFFFF)); + assertEquals(CellFormatPart.getColor("Color35"), new Color(0xCCFFCC)); + assertEquals(CellFormatPart.getColor("Color36"), new Color(0xFFFF99)); + assertEquals(CellFormatPart.getColor("Color37"), new Color(0x99CCFF)); + assertEquals(CellFormatPart.getColor("Color38"), new Color(0xFF99CC)); + assertEquals(CellFormatPart.getColor("Color39"), new Color(0xCC99FF)); + assertEquals(CellFormatPart.getColor("Color40"), new Color(0xFFCC99)); + assertEquals(CellFormatPart.getColor("Color41"), new Color(0x3366FF)); + assertEquals(CellFormatPart.getColor("Color42"), new Color(0x33CCCC)); + assertEquals(CellFormatPart.getColor("Color43"), new Color(0x99CC00)); + assertEquals(CellFormatPart.getColor("Color44"), new Color(0xFFCC00)); + assertEquals(CellFormatPart.getColor("Color45"), new Color(0xFF9900)); + assertEquals(CellFormatPart.getColor("Color46"), new Color(0xFF6600)); + assertEquals(CellFormatPart.getColor("Color47"), new Color(0x666699)); + assertEquals(CellFormatPart.getColor("Color48"), new Color(0x969696)); + assertEquals(CellFormatPart.getColor("Color49"), new Color(0x003366)); + assertEquals(CellFormatPart.getColor("Color50"), new Color(0x339966)); + assertEquals(CellFormatPart.getColor("Color51"), new Color(0x003300)); + assertEquals(CellFormatPart.getColor("Color52"), new Color(0x333300)); + assertEquals(CellFormatPart.getColor("Color53"), new Color(0x993300)); + assertEquals(CellFormatPart.getColor("Color54"), new Color(0x993366)); + assertEquals(CellFormatPart.getColor("Color55"), new Color(0x333399)); + assertEquals(CellFormatPart.getColor("Color56"), new Color(0x333333)); + } + + @Test + void testColorsInWorkbook() throws IOException { + // Create a workbook, row and cell to test with + try (Workbook wb = new HSSFWorkbook()) { + Sheet sheet = wb.createSheet(); + Row row = sheet.createRow(0); + Cell cell = row.createCell(0); + CellFormatResult result; + CellFormat cf = CellFormat.getInstance( + "[GREEN]#,##0.0;[RED]\\(#,##0.0\\);[COLOR22]\"===\";[COLOR 8]\\\"@\\\""); + + cell.setCellValue(100.0); + result = cf.apply(cell); + assertEquals("100.0", result.text); + assertEquals(result.textColor, CellFormatPart.getColor("color 4")); + + cell.setCellValue(-50.0); + result = cf.apply(cell); + assertEquals("(50.0)", result.text); + assertEquals(result.textColor, CellFormatPart.getColor("red")); + + cell.setCellValue("foo"); + result = cf.apply(cell); + assertEquals("\"foo\"", result.text); + assertEquals(result.textColor, CellFormatPart.getColor("cyan")); + + cell.setCellValue(0.0); + result = cf.apply(cell); + assertEquals("===", result.text); + assertEquals(result.textColor, CellFormatPart.getColor("color 22")); + } + } @Test void testElapsedSecondsRound() { diff --git a/poi/src/test/java/org/apache/poi/ss/formula/atp/TestAnalysisToolPak.java b/poi/src/test/java/org/apache/poi/ss/formula/atp/TestAnalysisToolPak.java new file mode 100644 index 0000000000..2861cab7f0 --- /dev/null +++ b/poi/src/test/java/org/apache/poi/ss/formula/atp/TestAnalysisToolPak.java @@ -0,0 +1,75 @@ +/* ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ + +package org.apache.poi.ss.formula.atp; + +import org.apache.poi.hssf.usermodel.HSSFCell; +import org.apache.poi.hssf.usermodel.HSSFSheet; +import org.apache.poi.hssf.usermodel.HSSFWorkbook; +import org.apache.poi.ss.formula.OperationEvaluationContext; +import org.apache.poi.ss.formula.eval.ErrorEval; +import org.apache.poi.ss.formula.eval.ValueEval; +import org.apache.poi.ss.formula.functions.FreeRefFunction; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; + +public class TestAnalysisToolPak { + private static class NullFunction implements FreeRefFunction { + @Override + public ValueEval evaluate(ValueEval[] args, OperationEvaluationContext ec) { + return ErrorEval.DIV_ZERO; + } + } + + @Test + void testOverrideKnownButUnimplemented() { + // JIS is a known function in Excel, but it is not implemented in POI + AnalysisToolPak.registerFunction("JIS", new NullFunction()); + try (HSSFWorkbook workbook = new HSSFWorkbook()) { + HSSFSheet sheet = workbook.createSheet("Sheet1"); + HSSFCell cell = sheet.createRow(0).createCell(0); + cell.setCellFormula("JIS(\"test\")"); + workbook.getCreationHelper().createFormulaEvaluator().evaluateAll(); + assertEquals(ErrorEval.DIV_ZERO.getErrorCode(), cell.getErrorCellValue()); + } catch (Exception e) { + throw new RuntimeException(e); + } + } + + @Test + void testOverrideUnknown() { + assertThrows(IllegalArgumentException.class, () -> { + AnalysisToolPak.registerFunction("UNKNOWN", new NullFunction()); + }); + } + + @Test + void testOverrideUnknownButForceAllowed() { + AnalysisToolPak.registerFunction("FAKE", new NullFunction(), true); + try (HSSFWorkbook workbook = new HSSFWorkbook()) { + HSSFSheet sheet = workbook.createSheet("Sheet1"); + HSSFCell cell = sheet.createRow(0).createCell(0); + cell.setCellFormula("FAKE(\"test\")"); + workbook.getCreationHelper().createFormulaEvaluator().evaluateAll(); + assertEquals(ErrorEval.DIV_ZERO.getErrorCode(), cell.getErrorCellValue()); + } catch (Exception e) { + throw new RuntimeException(e); + } + } +} diff --git a/poi/src/test/java/org/apache/poi/ss/formula/function/ExcelCetabFunctionExtractor.java b/poi/src/test/java/org/apache/poi/ss/formula/function/ExcelCetabFunctionExtractor.java index 87c0dcd1f3..3d6f525d2b 100644 --- a/poi/src/test/java/org/apache/poi/ss/formula/function/ExcelCetabFunctionExtractor.java +++ b/poi/src/test/java/org/apache/poi/ss/formula/function/ExcelCetabFunctionExtractor.java @@ -149,7 +149,7 @@ public final class ExcelCetabFunctionExtractor { public void addFunction(int funcIx, boolean hasFootnote, String funcName, int minParams, int maxParams, String returnClass, String paramClasses, String volatileFlagStr) { - boolean isVolatile = volatileFlagStr.length() > 0; + boolean isVolatile = !volatileFlagStr.isEmpty(); Integer funcIxKey = Integer.valueOf(funcIx); if(!_groupFunctionIndexes.add(funcIxKey)) { diff --git a/poi/src/test/java/org/apache/poi/ss/formula/function/ExcelFileFormatDocFunctionExtractor.java b/poi/src/test/java/org/apache/poi/ss/formula/function/ExcelFileFormatDocFunctionExtractor.java index b131071abf..11dca94104 100644 --- a/poi/src/test/java/org/apache/poi/ss/formula/function/ExcelFileFormatDocFunctionExtractor.java +++ b/poi/src/test/java/org/apache/poi/ss/formula/function/ExcelFileFormatDocFunctionExtractor.java @@ -26,6 +26,8 @@ import java.io.UncheckedIOException; import java.io.UnsupportedEncodingException; import java.math.BigInteger; import java.net.MalformedURLException; +import java.net.URI; +import java.net.URISyntaxException; import java.net.URL; import java.net.URLConnection; import java.nio.charset.StandardCharsets; @@ -169,9 +171,9 @@ public final class ExcelFileFormatDocFunctionExtractor { public void addFunction(int funcIx, boolean hasFootnote, String funcName, int minParams, int maxParams, String returnClass, String paramClasses, String volatileFlagStr) { - boolean isVolatile = volatileFlagStr.length() > 0; + boolean isVolatile = !volatileFlagStr.isEmpty(); - Integer funcIxKey = Integer.valueOf(funcIx); + Integer funcIxKey = funcIx; if(!_groupFunctionIndexes.add(funcIxKey)) { throw new RuntimeException("Duplicate function index (" + funcIx + ")"); } @@ -209,7 +211,7 @@ public final class ExcelFileFormatDocFunctionExtractor { throw new RuntimeException("changing function '" + funcName + "' definition without foot-note"); } - _allFunctionsByIndex.remove(Integer.valueOf(fdPrev.getIndex())); + _allFunctionsByIndex.remove(fdPrev.getIndex()); } } @@ -326,7 +328,7 @@ public final class ExcelFileFormatDocFunctionExtractor { processTableRow(cellData, noteFlags); } else if(matchesRelPath(TABLE_CELL_RELPATH_NAMES)) { _rowData.add(_textNodeBuffer.toString().trim()); - _rowNoteFlags.add(Boolean.valueOf(_cellHasNote)); + _rowNoteFlags.add(_cellHasNote); _textNodeBuffer.setLength(0); } } @@ -350,7 +352,7 @@ public final class ExcelFileFormatDocFunctionExtractor { } int funcIx = parseInt(funcIxStr); - boolean hasFootnote = noteFlags[i + 1].booleanValue(); + boolean hasFootnote = noteFlags[i + 1]; String funcName = cellData[i + 1]; int minParams = parseInt(cellData[i + 2]); int maxParams = parseInt(cellData[i + 3]); @@ -577,8 +579,8 @@ public final class ExcelFileFormatDocFunctionExtractor { private static File downloadSourceFile() { URL url; try { - url = new URL("http://sc.openoffice.org/" + SOURCE_DOC_FILE_NAME); - } catch (MalformedURLException e) { + url = new URI("http://sc.openoffice.org/" + SOURCE_DOC_FILE_NAME).toURL(); + } catch (MalformedURLException | URISyntaxException e) { throw new RuntimeException(e); } diff --git a/poi/src/test/java/org/apache/poi/ss/formula/functions/TestEDate.java b/poi/src/test/java/org/apache/poi/ss/formula/functions/TestEDate.java index d55fdcf5e8..77a2c53482 100644 --- a/poi/src/test/java/org/apache/poi/ss/formula/functions/TestEDate.java +++ b/poi/src/test/java/org/apache/poi/ss/formula/functions/TestEDate.java @@ -41,7 +41,7 @@ class TestEDate { checkValue(1, 0, 1d); checkValue(0, 1, 31d); checkValue(1, 1, 32d); - checkValue(0, 0, /* BAD_DATE! */ -1.0d); + checkValue(0, 0, 0.0d); checkValue(0, -2, /* BAD_DATE! */ -1.0d); checkValue(0, -3, /* BAD_DATE! */ -1.0d); checkValue(49104, 0, 49104d); @@ -112,14 +112,14 @@ class TestEDate { @Test void testEDateBlankValueEval() { NumberEval evaluate = (NumberEval) new EDate().evaluate(new ValueEval[]{BlankEval.instance, new NumberEval(0)}, null); - assertEquals(-1.0d, evaluate.getNumberValue(), 0); + assertEquals(0.0d, evaluate.getNumberValue(), 0); } @Test void testEDateBlankRefValueEval() { EDate eDate = new EDate(); NumberEval result = (NumberEval) eDate.evaluate(new ValueEval[]{new RefEvalImplementation(BlankEval.instance), new NumberEval(0)}, null); - assertEquals(-1.0d, result.getNumberValue(), 0, "0 startDate triggers BAD_DATE currently, thus -1.0!"); + assertEquals(0.0d, result.getNumberValue(), 0, "0 startDate triggers BAD_DATE currently, thus -1.0!"); result = (NumberEval) eDate.evaluate(new ValueEval[]{new NumberEval(1), new RefEvalImplementation(BlankEval.instance)}, null); assertEquals(1.0d, result.getNumberValue(), 0, "Blank is handled as 0 otherwise"); diff --git a/poi/src/test/java/org/apache/poi/ss/formula/functions/TestEOMonth.java b/poi/src/test/java/org/apache/poi/ss/formula/functions/TestEOMonth.java index c1e1349909..2587f8f49b 100644 --- a/poi/src/test/java/org/apache/poi/ss/formula/functions/TestEOMonth.java +++ b/poi/src/test/java/org/apache/poi/ss/formula/functions/TestEOMonth.java @@ -64,7 +64,7 @@ class TestEOMonth { void testEOMonthBadDateValues() { checkValue(0.0, -2, BAD_DATE); checkValue(0.0, -3, BAD_DATE); - checkValue(DATE_1900_01_31, -1, BAD_DATE); + checkValue(DATE_1900_01_31, -2, BAD_DATE); } private void checkValue(double startDate, int monthInc, double expectedResult) { diff --git a/poi/src/test/java/org/apache/poi/ss/formula/functions/TestNumericFunction.java b/poi/src/test/java/org/apache/poi/ss/formula/functions/TestNumericFunction.java index 632c53ad39..6343cb1a06 100644 --- a/poi/src/test/java/org/apache/poi/ss/formula/functions/TestNumericFunction.java +++ b/poi/src/test/java/org/apache/poi/ss/formula/functions/TestNumericFunction.java @@ -69,7 +69,7 @@ final class TestNumericFunction { void testDOLLAR() { Locale defaultLocale = LocaleUtil.getUserLocale(); try { - LocaleUtil.setUserLocale(new Locale("en", "US")); + LocaleUtil.setUserLocale(new Locale.Builder().setLanguage("en").setRegion("US").build()); HSSFWorkbook wb = new HSSFWorkbook(); HSSFCell cell = wb.createSheet().createRow(0).createCell(0); HSSFFormulaEvaluator fe = new HSSFFormulaEvaluator(wb); @@ -89,7 +89,7 @@ final class TestNumericFunction { void testDOLLARIreland() { Locale defaultLocale = LocaleUtil.getUserLocale(); try { - LocaleUtil.setUserLocale(new Locale("en", "IE")); + LocaleUtil.setUserLocale(new Locale.Builder().setLanguage("en").setRegion("IE").build()); HSSFWorkbook wb = new HSSFWorkbook(); HSSFCell cell = wb.createSheet().createRow(0).createCell(0); HSSFFormulaEvaluator fe = new HSSFFormulaEvaluator(wb); @@ -104,7 +104,7 @@ final class TestNumericFunction { void testDOLLARSpain() { Locale defaultLocale = LocaleUtil.getUserLocale(); try { - LocaleUtil.setUserLocale(new Locale("es", "ES")); + LocaleUtil.setUserLocale(new Locale.Builder().setLanguage("es").setRegion("ES").build()); HSSFWorkbook wb = new HSSFWorkbook(); HSSFCell cell = wb.createSheet().createRow(0).createCell(0); HSSFFormulaEvaluator fe = new HSSFFormulaEvaluator(wb); @@ -119,7 +119,7 @@ final class TestNumericFunction { void testDOLLARJapan() { Locale defaultLocale = LocaleUtil.getUserLocale(); try { - LocaleUtil.setUserLocale(new Locale("ja", "JP")); + LocaleUtil.setUserLocale(new Locale.Builder().setLanguage("ja").setRegion("JP").build()); HSSFWorkbook wb = new HSSFWorkbook(); HSSFCell cell = wb.createSheet().createRow(0).createCell(0); HSSFFormulaEvaluator fe = new HSSFFormulaEvaluator(wb); @@ -135,7 +135,7 @@ final class TestNumericFunction { void testDOLLARDenmark() { Locale defaultLocale = LocaleUtil.getUserLocale(); try { - LocaleUtil.setUserLocale(new Locale("da", "DK")); + LocaleUtil.setUserLocale(new Locale.Builder().setLanguage("da").setRegion("DK").build()); HSSFWorkbook wb = new HSSFWorkbook(); HSSFCell cell = wb.createSheet().createRow(0).createCell(0); HSSFFormulaEvaluator fe = new HSSFFormulaEvaluator(wb); diff --git a/poi/src/test/java/org/apache/poi/ss/formula/functions/TestSheet.java b/poi/src/test/java/org/apache/poi/ss/formula/functions/TestSheet.java new file mode 100644 index 0000000000..894db09814 --- /dev/null +++ b/poi/src/test/java/org/apache/poi/ss/formula/functions/TestSheet.java @@ -0,0 +1,89 @@ +/* ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ + +package org.apache.poi.ss.formula.functions; + +import org.apache.poi.hssf.usermodel.*; +import org.apache.poi.ss.formula.OperationEvaluationContext; +import org.apache.poi.ss.usermodel.CellType; +import org.apache.poi.ss.usermodel.FormulaError; +import org.junit.jupiter.api.Test; + +import java.io.IOException; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +final class TestSheet { + + private static final OperationEvaluationContext ec = new OperationEvaluationContext(null, null, 2, 0, 2, null); + + @Test + void testSheetFunctionWithRealWorkbook() throws IOException { + try (HSSFWorkbook wb = new HSSFWorkbook()) { + // Add three sheets: Sheet1, Sheet2, Sheet3 + HSSFSheet sheet1 = wb.createSheet("Sheet1"); + HSSFSheet sheet2 = wb.createSheet("Sheet2"); + HSSFSheet sheet3 = wb.createSheet("Sheet3"); + + // Add data + sheet1.createRow(0).createCell(0).setCellValue(123); // A1 in Sheet1 + sheet2.createRow(1).createCell(0).setCellValue(456); // A2 in Sheet2 + + HSSFFormulaEvaluator fe = new HSSFFormulaEvaluator(wb); + + // Define formulas and expected results + String[] formulas = { + "SHEET()", + "SHEET(A1)", + "SHEET(A1:B5)", + "SHEET(Sheet2!A2)", + "SHEET(\"Sheet3\")", + "SHEET(\"invalid\")" + }; + + Object[] expected = { + 1.0, // current sheet + 1.0, // A1 in same sheet + 1.0, // A1:B5 in same sheet + 2.0, // Sheet2!A2 + 3.0, // Sheet3 + FormulaError.NA.getCode() // unknown sheet → #N/A + }; + + // Write formulas to separate cells and evaluate + HSSFRow formulaRow = sheet1.createRow(1); + for (int i = 0; i < formulas.length; i++) { + String formula = formulas[i]; + HSSFCell cell = formulaRow.createCell(i); + cell.setCellFormula(formula); + CellType resultType = fe.evaluateFormulaCell(cell); + + if (expected[i] instanceof Double) { + assertEquals(CellType.NUMERIC, resultType, + "Unexpected cell type for formula: " + formula); + assertEquals((Double) expected[i], cell.getNumericCellValue(), + "Unexpected numeric result for formula: " + formula); + } else if (expected[i] instanceof Byte) { + assertEquals(CellType.ERROR, resultType, + "Unexpected cell type for formula: " + formula); + assertEquals((byte) expected[i], cell.getErrorCellValue(), + "Unexpected error code for formula: " + formula); + } + } + } + } +} diff --git a/poi/src/test/java/org/apache/poi/ss/usermodel/BaseTestCell.java b/poi/src/test/java/org/apache/poi/ss/usermodel/BaseTestCell.java index e69b5abbb2..e42a662813 100644 --- a/poi/src/test/java/org/apache/poi/ss/usermodel/BaseTestCell.java +++ b/poi/src/test/java/org/apache/poi/ss/usermodel/BaseTestCell.java @@ -33,6 +33,7 @@ import java.io.IOException; import java.nio.charset.StandardCharsets; import java.time.LocalDate; import java.time.LocalDateTime; +import java.time.LocalTime; import java.time.ZoneOffset; import java.util.Calendar; import java.util.Date; @@ -47,6 +48,8 @@ import org.apache.poi.ss.SpreadsheetVersion; import org.apache.poi.ss.formula.eval.NotImplementedException; import org.apache.poi.ss.util.CellRangeAddress; import org.apache.poi.util.LocaleUtil; +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.BeforeAll; import org.junit.jupiter.api.Test; /** @@ -56,6 +59,7 @@ import org.junit.jupiter.api.Test; @SuppressWarnings("deprecation") public abstract class BaseTestCell { + protected static TimeZone userTimeZone; protected final ITestDataProvider _testDataProvider; /** @@ -65,6 +69,19 @@ public abstract class BaseTestCell { _testDataProvider = testDataProvider; } + @BeforeAll + public static void setTimeZone() { + userTimeZone = LocaleUtil.getUserTimeZone(); + LocaleUtil.setUserTimeZone(TimeZone.getTimeZone("CET")); + LocaleUtil.setUserLocale(Locale.US); + } + + @AfterAll + public static void resetTimeZone() { + LocaleUtil.setUserTimeZone(userTimeZone); + LocaleUtil.setUserLocale(Locale.ROOT); + } + @Test void testSetValues() throws Exception { try (Workbook book = _testDataProvider.createWorkbook()) { @@ -348,6 +365,9 @@ public abstract class BaseTestCell { dateStyle.setDataFormat(formatId); r.getCell(7).setCellStyle(dateStyle); + // null rich text + r.createCell(8).setCellValue(factory.createRichTextString(null)); // blank + assertEquals("FALSE", r.getCell(0).toString(), "Boolean"); assertEquals("TRUE", r.getCell(1).toString(), "Boolean"); assertEquals("1.5", r.getCell(2).toString(), "Numeric"); @@ -357,9 +377,8 @@ public abstract class BaseTestCell { assertEquals("", r.getCell(6).toString(), "Blank"); // toString on a date-formatted cell displays dates as dd-MMM-yyyy, which has locale problems with the month String dateCell1 = r.getCell(7).toString(); - assertTrue(dateCell1.startsWith("02-"), "Date (Day)"); - assertTrue(dateCell1.endsWith("-2010"), "Date (Year)"); - + assertEquals("2/2/10 0:00", dateCell1); + assertEquals("", r.getCell(8).toString(), "Blank"); //Write out the file, read it in, and then check cell values try (Workbook wb2 = _testDataProvider.writeOutAndReadBack(wb1)) { @@ -373,6 +392,7 @@ public abstract class BaseTestCell { assertEquals("", r.getCell(6).toString(), "Blank"); String dateCell2 = r.getCell(7).toString(); assertEquals(dateCell1, dateCell2, "Date"); + assertEquals("", r.getCell(8).toString(), "Blank"); } } } @@ -1408,6 +1428,27 @@ public abstract class BaseTestCell { } @Test + void testZeroDate() throws IOException { + try (Workbook wb = _testDataProvider.createWorkbook()) { + Cell cellA1 = getInstance(wb); + cellA1.setCellValue(1.0); + assertEquals(LocalDate.parse("1900-01-01"), + cellA1.getLocalDateTimeCellValue().toLocalDate()); + + cellA1.setCellValue(0.0); + // this value is not strictly correct but our time only support relies on this + // time only means cells that have values with just times but no date parts + assertEquals(LocalDate.parse("1899-12-31"), + cellA1.getLocalDateTimeCellValue().toLocalDate()); + + cellA1.setCellValue(0.5); + assertEquals(LocalTime.parse("12:00"), + cellA1.getLocalDateTimeCellValue().toLocalTime()); + + } + } + + @Test protected void setCellType_FORMULA_onAnArrayFormulaCell_doesNothing() throws IOException { try (Workbook wb = _testDataProvider.createWorkbook()) { Cell cell = getInstance(wb); @@ -1432,6 +1473,36 @@ public abstract class BaseTestCell { verify(cell).setBlank(); } + @Test + protected void setCellNullString() throws IOException { + try (Workbook wb = _testDataProvider.createWorkbook()) { + Cell cell = getInstance(wb); + + cell.setCellValue((String)null); + + // setting string "null" leads to a BLANK cell + assertEquals(CellType.BLANK, cell.getCellType()); + assertEquals("", cell.getStringCellValue()); + assertEquals("", cell.toString()); + + cell.setCellType(CellType.STRING); + + // forcing to string type leads to STRING cell, but still empty strings + assertEquals(CellType.STRING, cell.getCellType()); + assertEquals("", cell.getStringCellValue()); + assertEquals("", cell.toString()); + + try (Workbook wb2 = _testDataProvider.writeOutAndReadBack(wb)) { + // read first sheet, first row, first cell + Cell cellBack = wb2.iterator().next().iterator().next().iterator().next(); + + assertEquals(CellType.STRING, cell.getCellType()); + assertEquals("", cell.getStringCellValue()); + assertEquals("", cell.toString()); + } + } + } + private Cell getInstance(Workbook wb) { return wb.createSheet().createRow(0).createCell(0); } diff --git a/poi/src/test/java/org/apache/poi/ss/usermodel/BaseTestConditionalFormatting.java b/poi/src/test/java/org/apache/poi/ss/usermodel/BaseTestConditionalFormatting.java index 49f944635b..64f585608a 100644 --- a/poi/src/test/java/org/apache/poi/ss/usermodel/BaseTestConditionalFormatting.java +++ b/poi/src/test/java/org/apache/poi/ss/usermodel/BaseTestConditionalFormatting.java @@ -531,7 +531,7 @@ public abstract class BaseTestConditionalFormatting { // Sanity check data assertEquals("Values", s.getRow(0).getCell(0).toString()); - assertEquals("10.0", s.getRow(2).getCell(0).toString()); + assertEquals(10.0, s.getRow(2).getCell(0).getNumericCellValue()); // Check we found all the conditional formatting rules we should have SheetConditionalFormatting sheetCF = s.getSheetConditionalFormatting(); diff --git a/poi/src/test/java/org/apache/poi/ss/usermodel/BaseTestFormulaEvaluator.java b/poi/src/test/java/org/apache/poi/ss/usermodel/BaseTestFormulaEvaluator.java index def6e2c185..cbd3438e74 100644 --- a/poi/src/test/java/org/apache/poi/ss/usermodel/BaseTestFormulaEvaluator.java +++ b/poi/src/test/java/org/apache/poi/ss/usermodel/BaseTestFormulaEvaluator.java @@ -357,7 +357,7 @@ public abstract class BaseTestFormulaEvaluator { eval.evaluateInCell(cell); - assertEquals("3.0", cell.toString()); + assertEquals(3.0, cell.getNumericCellValue()); } } @@ -621,7 +621,6 @@ public abstract class BaseTestFormulaEvaluator { assertNotNull(eval.evaluateInCell(cell)); - assertEquals("3.0", cell.toString()); assertEquals(CellType.NUMERIC, cell.getCellType()); assertEquals(3.0, cell.getNumericCellValue(), 0.01); } diff --git a/poi/src/test/java/org/apache/poi/ss/usermodel/TestDataFormatter.java b/poi/src/test/java/org/apache/poi/ss/usermodel/TestDataFormatter.java index 0d49bee3ab..b1fced30a5 100644 --- a/poi/src/test/java/org/apache/poi/ss/usermodel/TestDataFormatter.java +++ b/poi/src/test/java/org/apache/poi/ss/usermodel/TestDataFormatter.java @@ -937,7 +937,7 @@ class TestDataFormatter { // 2017-12-01 09:54:33 which is 42747.412892397523 as double DataFormatter dfDE = new DataFormatter(Locale.GERMANY); DataFormatter dfZH = new DataFormatter(Locale.PRC); - DataFormatter dfIE = new DataFormatter(new Locale("GA", "IE")); + DataFormatter dfIE = new DataFormatter(new Locale.Builder().setLanguage("GA").setRegion("IE").build()); double date = 42747.412892397523; String format = "dd MMMM yyyy HH:mm:ss"; assertEquals("12 Januar 2017 09:54:33", dfDE.formatRawCellContents(date, -1, format)); diff --git a/poi/src/test/java/org/apache/poi/ss/usermodel/TestDateUtil.java b/poi/src/test/java/org/apache/poi/ss/usermodel/TestDateUtil.java index 615e2f1d72..2a44fb0c38 100644 --- a/poi/src/test/java/org/apache/poi/ss/usermodel/TestDateUtil.java +++ b/poi/src/test/java/org/apache/poi/ss/usermodel/TestDateUtil.java @@ -183,6 +183,7 @@ class TestDateUtil { // Cell show "２０１６年１２月８日" assertTrue(DateUtil.isADateFormat(178, "[DBNum3][$-804]yyyy\"\u5e74\"m\"\u6708\"d\"\u65e5\";@")); } + /** * Checks the date conversion functions in the DateUtil class. */ @@ -190,16 +191,16 @@ class TestDateUtil { void dateConversion() { // Iterating over the hours exposes any rounding issues. - Calendar cal = LocaleUtil.getLocaleCalendar(2002,JANUARY,1,0,1,1); + Calendar cal = LocaleUtil.getLocaleCalendar(2002, JANUARY, 1, 0, 1, 1); for (int hour = 0; hour < 24; hour++) { double excelDate = DateUtil.getExcelDate(cal.getTime(), false); assertEquals(cal.getTime().getTime(), DateUtil.getJavaDate(excelDate, false).getTime(), - "getJavaDate: Checking hour = " + hour); + "getJavaDate: Checking hour = " + hour); LocalDateTime ldt = LocalDateTime.ofInstant(cal.toInstant(), cal.getTimeZone().toZoneId()); assertEquals(ldt, DateUtil.getLocalDateTime(excelDate, false), - "getLocalDateTime: Checking hour = " + hour); + "getLocalDateTime: Checking hour = " + hour); cal.add(Calendar.HOUR_OF_DAY, 1); } @@ -208,23 +209,23 @@ class TestDateUtil { double excelDate = 36526.0; // with 1900 windowing, excelDate is Jan. 1, 2000 // with 1904 windowing, excelDate is Jan. 2, 2004 - cal.set(2000,JANUARY,1,0,0,0); // Jan. 1, 2000 + cal.set(2000, JANUARY, 1, 0, 0, 0); // Jan. 1, 2000 Date dateIf1900 = cal.getTime(); - cal.add(Calendar.YEAR,4); // now Jan. 1, 2004 - cal.add(Calendar.DATE,1); // now Jan. 2, 2004 + cal.add(Calendar.YEAR, 4); // now Jan. 1, 2004 + cal.add(Calendar.DATE, 1); // now Jan. 2, 2004 Date dateIf1904 = cal.getTime(); // 1900 windowing - assertEquals(dateIf1900.getTime(), DateUtil.getJavaDate(excelDate,false).getTime(), - "Checking 1900 Date Windowing"); + assertEquals(dateIf1900.getTime(), DateUtil.getJavaDate(excelDate, false).getTime(), + "Checking 1900 Date Windowing"); // 1904 windowing - assertEquals(dateIf1904.getTime(), DateUtil.getJavaDate(excelDate,true).getTime(), - "Checking 1904 Date Windowing"); + assertEquals(dateIf1904.getTime(), DateUtil.getJavaDate(excelDate, true).getTime(), + "Checking 1904 Date Windowing"); // 1900 windowing (LocalDateTime) - assertEquals(LocalDateTime.of(2000,1,1,0,0), DateUtil.getLocalDateTime(excelDate,false), - "Checking 1900 Date Windowing"); + assertEquals(LocalDateTime.of(2000, 1, 1, 0, 0), DateUtil.getLocalDateTime(excelDate, false), + "Checking 1900 Date Windowing"); // 1904 windowing (LocalDateTime) - assertEquals(LocalDateTime.of(2004,1,2,0,0), DateUtil.getLocalDateTime(excelDate,true), - "Checking 1904 Date Windowing"); + assertEquals(LocalDateTime.of(2004, 1, 2, 0, 0), DateUtil.getLocalDateTime(excelDate, true), + "Checking 1904 Date Windowing"); } /** @@ -233,7 +234,7 @@ class TestDateUtil { */ @Test void excelConversionOnDSTStart() { - Calendar cal = LocaleUtil.getLocaleCalendar(2004,MARCH,28,0,0,0); + Calendar cal = LocaleUtil.getLocaleCalendar(2004, MARCH, 28, 0, 0, 0); for (int hour = 0; hour < 24; hour++) { // Skip 02:00 CET as that is the Daylight change time @@ -250,18 +251,18 @@ class TestDateUtil { assertEquals(hour, differenceInHours, "Checking " + hour + " hour on Daylight Saving Time start date"); assertEquals(javaDate.getTime(), DateUtil.getJavaDate(excelDate, false).getTime(), - "Checking " + hour + " hour on Daylight Saving Time start date"); + "Checking " + hour + " hour on Daylight Saving Time start date"); // perform the same checks with LocalDateTime - LocalDateTime localDate = LocalDateTime.of(2004,3,28,hour,0,0); + LocalDateTime localDate = LocalDateTime.of(2004, 3, 28, hour, 0, 0); double excelLocalDate = DateUtil.getExcelDate(localDate, false); double differenceLocalDate = excelLocalDate - Math.floor(excelLocalDate); int differenceLocalDateInHours = (int) (differenceLocalDate * 24 * 60 + 0.5) / 60; assertEquals(hour, differenceLocalDateInHours, - "Checking " + hour + " hour on Daylight Saving Time start date (LocalDateTime)"); + "Checking " + hour + " hour on Daylight Saving Time start date (LocalDateTime)"); assertEquals(localDate, DateUtil.getLocalDateTime(excelLocalDate, false), - "Checking " + hour + " hour on Daylight Saving Time start date (LocalDateTime)"); + "Checking " + hour + " hour on Daylight Saving Time start date (LocalDateTime)"); } } @@ -271,7 +272,7 @@ class TestDateUtil { */ @Test void javaConversionOnDSTStart() { - Calendar cal = LocaleUtil.getLocaleCalendar(2004,MARCH,28,0,0,0); + Calendar cal = LocaleUtil.getLocaleCalendar(2004, MARCH, 28, 0, 0, 0); double excelDate = DateUtil.getExcelDate(cal.getTime(), false); double oneHour = 1.0 / 24; double oneMinute = oneHour / 60; @@ -287,14 +288,14 @@ class TestDateUtil { Date javaDate = DateUtil.getJavaDate(excelDate, false); double actDate = DateUtil.getExcelDate(javaDate, false); assertEquals(excelDate, actDate, oneMinute, - "Checking " + hour + " hours on Daylight Saving Time start date"); + "Checking " + hour + " hours on Daylight Saving Time start date"); // perform the same check with LocalDateTime cal.set(Calendar.HOUR_OF_DAY, hour); LocalDateTime localDate = DateUtil.getLocalDateTime(excelDate, false); double actLocalDate = DateUtil.getExcelDate(localDate, false); assertEquals(excelDate, actLocalDate, oneMinute, - "Checking " + hour + " hours on Daylight Saving Time start date (LocalDateTime)"); + "Checking " + hour + " hours on Daylight Saving Time start date (LocalDateTime)"); } } @@ -304,7 +305,7 @@ class TestDateUtil { */ @Test void excelConversionOnDSTEnd() { - Calendar cal = LocaleUtil.getLocaleCalendar(2004,OCTOBER,31,0,0,0); + Calendar cal = LocaleUtil.getLocaleCalendar(2004, OCTOBER, 31, 0, 0, 0); for (int hour = 0; hour < 24; hour++) { cal.set(Calendar.HOUR_OF_DAY, hour); Date javaDate = cal.getTime(); @@ -312,18 +313,18 @@ class TestDateUtil { double difference = excelDate - Math.floor(excelDate); int differenceInHours = (int) (difference * 24 * 60 + 0.5) / 60; assertEquals(hour, differenceInHours, - "Checking " + hour + " hour on Daylight Saving Time end date"); + "Checking " + hour + " hour on Daylight Saving Time end date"); assertEquals(javaDate.getTime(), DateUtil.getJavaDate(excelDate, false).getTime(), - "Checking " + hour + " hour on Daylight Saving Time start date"); + "Checking " + hour + " hour on Daylight Saving Time start date"); // perform the same checks using LocalDateTime - LocalDateTime localDate = LocalDateTime.of(2004,10,31,hour,0,0); + LocalDateTime localDate = LocalDateTime.of(2004, 10, 31, hour, 0, 0); double excelLocalDate = DateUtil.getExcelDate(localDate, false); int differenceLocalDateInHours = (int) (difference * 24 * 60 + 0.5) / 60; assertEquals(hour, differenceLocalDateInHours, - "Checking " + hour + " hour on Daylight Saving Time end date (LocalDateTime)"); + "Checking " + hour + " hour on Daylight Saving Time end date (LocalDateTime)"); assertEquals(localDate, DateUtil.getLocalDateTime(excelLocalDate, false), - "Checking " + hour + " hour on Daylight Saving Time start date (LocalDateTime)"); + "Checking " + hour + " hour on Daylight Saving Time start date (LocalDateTime)"); } } @@ -333,7 +334,7 @@ class TestDateUtil { */ @Test void javaConversionOnDSTEnd() { - Calendar cal = LocaleUtil.getLocaleCalendar(2004,OCTOBER,31,0,0,0); + Calendar cal = LocaleUtil.getLocaleCalendar(2004, OCTOBER, 31, 0, 0, 0); double excelDate = DateUtil.getExcelDate(cal.getTime(), false); double oneHour = 1.0 / 24; double oneMinute = oneHour / 60; @@ -341,12 +342,12 @@ class TestDateUtil { cal.set(Calendar.HOUR_OF_DAY, hour); Date javaDate = DateUtil.getJavaDate(excelDate, false); assertEquals(excelDate, DateUtil.getExcelDate(javaDate, false), oneMinute, - "Checking " + hour + " hours on Daylight Saving Time start date"); + "Checking " + hour + " hours on Daylight Saving Time start date"); // perform the same checks using LocalDateTime LocalDateTime localDate = DateUtil.getLocalDateTime(excelDate, false); assertEquals(excelDate, DateUtil.getExcelDate(localDate, false), oneMinute, - "Checking " + hour + " hours on Daylight Saving Time start date"); + "Checking " + hour + " hours on Daylight Saving Time start date"); } } @@ -358,12 +359,11 @@ class TestDateUtil { TimeZone userTZ = LocaleUtil.getUserTimeZone(); LocaleUtil.setUserTimeZone(TimeZone.getTimeZone("CET")); try { - Calendar cal = LocaleUtil.getLocaleCalendar(2002,JANUARY,1,12,1,1); + Calendar cal = LocaleUtil.getLocaleCalendar(2002, JANUARY, 1, 12, 1, 1); Date expected = cal.getTime(); // Iterating over the hours exposes any rounding issues. - for (int hour = -12; hour <= 12; hour++) - { + for (int hour = -12; hour <= 12; hour++) { String id = "GMT" + (hour < 0 ? "" : "+") + hour + ":00"; cal.setTimeZone(TimeZone.getTimeZone(id)); cal.set(Calendar.HOUR_OF_DAY, 12); @@ -383,14 +383,14 @@ class TestDateUtil { // Same, no change assertEquals( - DateUtil.getJavaDate(excelDate, false).getTime(), - DateUtil.getJavaDate(excelDate, false, cet).getTime() + DateUtil.getJavaDate(excelDate, false).getTime(), + DateUtil.getJavaDate(excelDate, false, cet).getTime() ); // London vs Copenhagen, should differ by an hour Date cetDate = DateUtil.getJavaDate(excelDate, false); Date ldnDate = DateUtil.getJavaDate(excelDate, false, ldn); - assertEquals(ldnDate.getTime() - cetDate.getTime(), 60*60*1000); + assertEquals(ldnDate.getTime() - cetDate.getTime(), 60 * 60 * 1000); } finally { LocaleUtil.setUserTimeZone(userTZ); } @@ -402,19 +402,19 @@ class TestDateUtil { @Test void identifyDateFormats() { // First up, try with a few built in date formats - short[] builtins = new short[] { 0x0e, 0x0f, 0x10, 0x16, 0x2d, 0x2e }; + short[] builtins = new short[]{0x0e, 0x0f, 0x10, 0x16, 0x2d, 0x2e}; for (short builtin : builtins) { String formatStr = HSSFDataFormat.getBuiltinFormat(builtin); - assertTrue( DateUtil.isInternalDateFormat(builtin) ); - assertTrue( DateUtil.isADateFormat(builtin,formatStr) ); + assertTrue(DateUtil.isInternalDateFormat(builtin)); + assertTrue(DateUtil.isADateFormat(builtin, formatStr)); } // Now try a few built-in non date formats - builtins = new short[] { 0x01, 0x02, 0x17, 0x1f, 0x30 }; + builtins = new short[]{0x01, 0x02, 0x17, 0x1f, 0x30}; for (short builtin : builtins) { String formatStr = HSSFDataFormat.getBuiltinFormat(builtin); - assertFalse( DateUtil.isInternalDateFormat(builtin) ); - assertFalse( DateUtil.isADateFormat(builtin,formatStr) ); + assertFalse(DateUtil.isInternalDateFormat(builtin)); + assertFalse(DateUtil.isADateFormat(builtin, formatStr)); } // Now for some non-internal ones @@ -422,10 +422,10 @@ class TestDateUtil { int numBuiltins = HSSFDataFormat.getNumberOfBuiltinBuiltinFormats(); assertTrue(numBuiltins < 60); short formatId = 60; - assertFalse( DateUtil.isInternalDateFormat(formatId) ); + assertFalse(DateUtil.isInternalDateFormat(formatId)); // Valid ones first - String[] formats = new String[] { + String[] formats = new String[]{ "yyyy-mm-dd", "yyyy/mm/dd", "yy/mm/dd", "yy/mmm/dd", "dd/mm/yy", "dd/mm/yyyy", "dd/mmm/yy", "dd-mm-yy", "dd-mm-yyyy", @@ -453,7 +453,7 @@ class TestDateUtil { } // Then time based ones too - formats = new String[] { + formats = new String[]{ "yyyy-mm-dd hh:mm:ss", "yyyy/mm/dd HH:MM:SS", "mm/dd HH:MM", "yy/mmm/dd SS", "mm/dd HH:MM AM", "mm/dd HH:MM am", @@ -468,7 +468,7 @@ class TestDateUtil { } // Then invalid ones - formats = new String[] { + formats = new String[]{ "yyyy*mm*dd", "0.0", "0.000", "0%", "0.0%", @@ -505,7 +505,7 @@ class TestDateUtil { Date date32 = df.parse("1900-02-01"); assertEquals(32.0, DateUtil.getExcelDate(date32), 0.00001); assertEquals(32.0, DateUtil.getExcelDate(DateUtil.toLocalDateTime(date32)), 0.00001); - Date dateMinus1 = df.parse("1899-12-31"); + Date dateMinus1 = df.parse("1899-12-30"); assertEquals(/* BAD_DATE! */ -1.0, DateUtil.getExcelDate(dateMinus1), 0.00001); assertEquals(/* BAD_DATE! */ -1.0, DateUtil.getExcelDate(DateUtil.toLocalDateTime(dateMinus1)), 0.00001); } @@ -521,13 +521,13 @@ class TestDateUtil { assertEquals(38074.00, DateUtil.getExcelDate(createDate(2004, MARCH, 28), false), 0.00001); // perform the same checks using LocalDateTime - assertEquals(59.0, DateUtil.getExcelDate(LocalDateTime.of(1900, 2, 28, 0,0), false), 0.00001); - assertEquals(61.0, DateUtil.getExcelDate(LocalDateTime.of(1900, 3, 1, 0,0), false), 0.00001); + assertEquals(59.0, DateUtil.getExcelDate(LocalDateTime.of(1900, 2, 28, 0, 0), false), 0.00001); + assertEquals(61.0, DateUtil.getExcelDate(LocalDateTime.of(1900, 3, 1, 0, 0), false), 0.00001); - assertEquals(37315.00, DateUtil.getExcelDate(LocalDateTime.of(2002, 2, 28, 0,0), false), 0.00001); - assertEquals(37316.00, DateUtil.getExcelDate(LocalDateTime.of(2002, 3, 1, 0,0), false), 0.00001); - assertEquals(37257.00, DateUtil.getExcelDate(LocalDateTime.of(2002, 1, 1, 0,0), false), 0.00001); - assertEquals(38074.00, DateUtil.getExcelDate(LocalDateTime.of(2004, 3, 28, 0,0), false), 0.00001); + assertEquals(37315.00, DateUtil.getExcelDate(LocalDateTime.of(2002, 2, 28, 0, 0), false), 0.00001); + assertEquals(37316.00, DateUtil.getExcelDate(LocalDateTime.of(2002, 3, 1, 0, 0), false), 0.00001); + assertEquals(37257.00, DateUtil.getExcelDate(LocalDateTime.of(2002, 1, 1, 0, 0), false), 0.00001); + assertEquals(38074.00, DateUtil.getExcelDate(LocalDateTime.of(2004, 3, 28, 0, 0), false), 0.00001); } @Test @@ -578,7 +578,7 @@ class TestDateUtil { /** * @param month zero based - * @param day one based + * @param day one based */ private static Date createDate(int year, int month, int day) { return createDate(year, month, day, 0, 0); @@ -586,7 +586,7 @@ class TestDateUtil { /** * @param month zero based - * @param day one based + * @param day one based */ private static Date createDate(int year, int month, int day, int hour, int minute) { Calendar c = LocaleUtil.getLocaleCalendar(year, month, day, hour, minute, 0); @@ -599,27 +599,27 @@ class TestDateUtil { @Test void absoluteDay() { // 1 Jan 1900 is 1 day after 31 Dec 1899 - Calendar cal = LocaleUtil.getLocaleCalendar(1900,JANUARY,1,0,0,0); + Calendar cal = LocaleUtil.getLocaleCalendar(1900, JANUARY, 1, 0, 0, 0); assertEquals(1, DateUtil.absoluteDay(cal, false), "Checking absolute day (1 Jan 1900)"); - LocalDateTime ldt = LocalDateTime.of(1900,1,1,0,0,0); + LocalDateTime ldt = LocalDateTime.of(1900, 1, 1, 0, 0, 0); assertEquals(1, DateUtil.absoluteDay(ldt, false), "Checking absolute day (1 Jan 1900) (LocalDateTime)"); // 1 Jan 1901 is 366 days after 31 Dec 1899 - ldt = LocalDateTime.of(1901,1,1,0,0,0); - cal.set(1901,JANUARY,1,0,0,0); + ldt = LocalDateTime.of(1901, 1, 1, 0, 0, 0); + cal.set(1901, JANUARY, 1, 0, 0, 0); assertEquals(366, DateUtil.absoluteDay(ldt, false), "Checking absolute day (1 Jan 1901) (LocalDateTime)"); } @Test void absoluteDayYearTooLow() { - Calendar cal = LocaleUtil.getLocaleCalendar(1899,JANUARY,1,0,0,0); + Calendar cal = LocaleUtil.getLocaleCalendar(1899, JANUARY, 1, 0, 0, 0); assertThrows(IllegalArgumentException.class, () -> DateUtil.absoluteDay(cal, false)); - cal.set(1903,JANUARY,1,0,0,0); + cal.set(1903, JANUARY, 1, 0, 0, 0); assertThrows(IllegalArgumentException.class, () -> DateUtil.absoluteDay(cal, true)); // same for LocalDateTime - assertThrows(IllegalArgumentException.class, () -> DateUtil.absoluteDay(LocalDateTime.of(1899,1,1,0,0,0), false)); - assertThrows(IllegalArgumentException.class, () -> DateUtil.absoluteDay(LocalDateTime.of(1903,1,1,0,0,0), true)); + assertThrows(IllegalArgumentException.class, () -> DateUtil.absoluteDay(LocalDateTime.of(1899, 1, 1, 0, 0, 0), false)); + assertThrows(IllegalArgumentException.class, () -> DateUtil.absoluteDay(LocalDateTime.of(1903, 1, 1, 0, 0, 0), true)); } @Test @@ -627,7 +627,7 @@ class TestDateUtil { final double delta = 1E-7; // a couple of digits more accuracy than strictly required assertEquals(0.5, DateUtil.convertTime("12:00"), delta); - assertEquals(2.0/3, DateUtil.convertTime("16:00"), delta); + assertEquals(2.0 / 3, DateUtil.convertTime("16:00"), delta); assertEquals(0.0000116, DateUtil.convertTime("0:00:01"), delta); assertEquals(0.7330440, DateUtil.convertTime("17:35:35"), delta); } @@ -657,7 +657,7 @@ class TestDateUtil { /** * User reported a datetime issue in POI-2.5: - * Setting Cell's value to Jan 1, 1900 without a time doesn't return the same value set to + * Setting Cell's value to Jan 1, 1900 without a time doesn't return the same value set to */ @Test void bug19172() throws IOException { @@ -713,4 +713,22 @@ class TestDateUtil { assertEquals(0, ldtRound.getMinute()); assertEquals(0, ldtRound.getSecond()); } -} + + @Test + void timeOnly() { + final double d = 22.0 / 24.0; // 22:00 (10pm) + final SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ", LocaleUtil.getUserLocale()); + sdf.setTimeZone(LocaleUtil.getUserTimeZone()); + final Date date = DateUtil.getJavaDate(d, false); + assertEquals("1899-12-31T22:00:00.000+0000", sdf.format(date)); + + final Date date1904 = DateUtil.getJavaDate(d, true); + assertEquals("1904-01-01T22:00:00.000+0000", sdf.format(date1904)); + + final double d0 = DateUtil.getExcelDate(date, false); + assertEquals(d, d0); + + final double d1 = DateUtil.getExcelDate(date1904, true); + assertEquals(d, d1, 1E-10); + } +}
\ No newline at end of file diff --git a/poi/src/test/java/org/apache/poi/ss/usermodel/TestExcelStyleDateFormatter.java b/poi/src/test/java/org/apache/poi/ss/usermodel/TestExcelStyleDateFormatter.java index b3ccd06a4c..f905470f88 100644 --- a/poi/src/test/java/org/apache/poi/ss/usermodel/TestExcelStyleDateFormatter.java +++ b/poi/src/test/java/org/apache/poi/ss/usermodel/TestExcelStyleDateFormatter.java @@ -58,11 +58,12 @@ class TestExcelStyleDateFormatter { formatter.setDateFormatSymbols(DateFormatSymbols.getInstance(locale)); String result = formatter.format(d, sb, fp).toString(); - String msg = "Failed testDates for locale " + locale + ", provider: " + provider + - " and date " + d + ", having: " + result; int actIdx = localeIndex(locale); + String msg = "Failed testDates for locale " + locale + ", provider: " + provider + + " and date " + d + ", having actIdx: " + actIdx + " and result '" + result + "' (" + result.length() + ")"; + assertNotNull(result, msg); assertTrue(result.length() > actIdx, msg); assertEquals(expected.charAt(month), result.charAt(actIdx), msg); @@ -102,15 +103,15 @@ class TestExcelStyleDateFormatter { public static Stream<Arguments> initializeLocales() throws ParseException { Object[][] locExps = { { Locale.GERMAN, "JFMAMJJASOND" }, - { new Locale("de", "AT"), "JFMAMJJASOND" }, + { new Locale.Builder().setLanguage("de").setRegion("AT").build(), "JFMAMJJASOND" }, { Locale.UK, "JFMAMJJASOND" }, - { new Locale("en", "IN"), "JFMAMJJASOND" }, - { new Locale("in", "ID"), "JFMAMJJASOND" }, + { new Locale.Builder().setLanguage("en").setRegion("IN").build(), "JFMAMJJASOND" }, + { new Locale.Builder().setLanguage("in").setRegion("ID").build(), "JFMAMJJASOND" }, { Locale.FRENCH, "jfmamjjasond" }, - { new Locale("ru", "RU"), "\u044f\u0444\u043c\u0430\u043c\u0438\u0438\u0430\u0441\u043e\u043d\u0434" }, + { new Locale.Builder().setLanguage("ru").setRegion("RU").build(), "\u044f\u0444\u043c\u0430\u043c\u0438\u0438\u0430\u0441\u043e\u043d\u0434" }, { Locale.CHINESE, localeIndex(Locale.CHINESE) == 0 ? "\u4e00\u4e8c\u4e09\u56db\u4e94\u516d\u4e03\u516b\u4e5d\u5341\u5341\u5341" : "123456789111" }, - { new Locale("tr", "TR"), "\u004f\u015e\u004d\u004e\u004d\u0048\u0054\u0041\u0045\u0045\u004b\u0041" }, - { new Locale("hu", "HU"), "\u006a\u0066\u006d\u00e1\u006d\u006a\u006a\u0061\u0073\u006f\u006e\u0064" } + { new Locale.Builder().setLanguage("tr").setRegion("TR").build(), "\u004f\u015e\u004d\u004e\u004d\u0048\u0054\u0041\u0045\u0045\u004b\u0041" }, + { new Locale.Builder().setLanguage("hu").setRegion("HU").build(), "\u006a\u0066\u006d\u00e1\u006d\u006a\u006a\u0061\u0073\u006f\u006e\u0064" } }; String[] dates = { diff --git a/poi/src/test/java/org/apache/poi/ss/util/BaseTestCellUtil.java b/poi/src/test/java/org/apache/poi/ss/util/BaseTestCellUtil.java index 9784e080b5..fb2200ba57 100644 --- a/poi/src/test/java/org/apache/poi/ss/util/BaseTestCellUtil.java +++ b/poi/src/test/java/org/apache/poi/ss/util/BaseTestCellUtil.java @@ -22,6 +22,7 @@ import org.apache.poi.ss.usermodel.*; import org.junit.jupiter.api.Test; import java.io.IOException; +import java.util.EnumMap; import java.util.HashMap; import java.util.Map; @@ -339,7 +340,7 @@ public abstract class BaseTestCellUtil { // Add multiple border properties to cell should create a single new style int styCnt1 = wb.getNumCellStyles(); - Map<CellPropertyType, Object> props = new HashMap<>(); + EnumMap<CellPropertyType, Object> props = new EnumMap<>(CellPropertyType.class); props.put(CellPropertyType.BORDER_TOP, BorderStyle.THIN); props.put(CellPropertyType.BORDER_BOTTOM, BorderStyle.THIN); props.put(CellPropertyType.BORDER_LEFT, BorderStyle.THIN); @@ -574,7 +575,7 @@ public abstract class BaseTestCellUtil { protected void setFillForegroundColorBeforeFillBackgroundColorEnumByEnum() throws IOException { try (Workbook wb1 = _testDataProvider.createWorkbook()) { Cell A1 = wb1.createSheet().createRow(0).createCell(0); - Map<CellPropertyType, Object> properties = new HashMap<>(); + EnumMap<CellPropertyType, Object> properties = new EnumMap<>(CellPropertyType.class); properties.put(CellPropertyType.FILL_PATTERN, FillPatternType.BRICKS); properties.put(CellPropertyType.FILL_FOREGROUND_COLOR, IndexedColors.BLUE.index); properties.put(CellPropertyType.FILL_BACKGROUND_COLOR, IndexedColors.RED.index); diff --git a/poi/src/test/java/org/apache/poi/ss/util/BaseTestCellUtilCopy.java b/poi/src/test/java/org/apache/poi/ss/util/BaseTestCellUtilCopy.java index ea214e815d..14d3fa00a1 100644 --- a/poi/src/test/java/org/apache/poi/ss/util/BaseTestCellUtilCopy.java +++ b/poi/src/test/java/org/apache/poi/ss/util/BaseTestCellUtilCopy.java @@ -146,6 +146,33 @@ public abstract class BaseTestCellUtilCopy { wb.close(); } + @Test + public final void testCopyCellTime() throws IOException { + try( + Workbook srcWb = createNewWorkbook(); + Workbook destWb = createNewWorkbook() + ) { + final Row rowS = srcWb.createSheet("Sheet1").createRow(0); + final Row rowD = destWb.createSheet("Sheet1").createRow(0); + srcCell = rowS.createCell(0); + destCell = rowD.createCell(0); + + srcCell.setCellValue(22.0/24.0); + + final CellStyle style = srcWb.createCellStyle(); + style.setDataFormat((short) 0x12); // time format + srcCell.setCellStyle(style); + + final CreationHelper createHelper = srcWb.getCreationHelper(); + + final CellCopyPolicy policy = new CellCopyPolicy.Builder().build(); + CellUtil.copyCell(srcCell, destCell, policy, new CellCopyContext()); + + assertEquals(srcCell.getNumericCellValue(), destCell.getNumericCellValue()); + assertEquals(srcCell.getCellStyle().getDataFormatString(), destCell.getCellStyle().getDataFormatString()); + } + } + private void setUp_testCopyCellFrom_CellCopyPolicy() { @SuppressWarnings("resource") final Workbook wb = createNewWorkbook(); diff --git a/poi/src/test/java/org/apache/poi/ss/util/TestCellUtil.java b/poi/src/test/java/org/apache/poi/ss/util/TestCellUtil.java new file mode 100644 index 0000000000..b7defbef99 --- /dev/null +++ b/poi/src/test/java/org/apache/poi/ss/util/TestCellUtil.java @@ -0,0 +1,36 @@ +/* ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ +package org.apache.poi.ss.util; + +import org.apache.poi.ss.usermodel.CellPropertyType; +import org.junit.jupiter.api.Test; + +import java.util.Arrays; + +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Test for CellUtil constants + */ +class TestCellUtil { + @Test + void testNamePropertyMap() { + Arrays.stream(CellPropertyType.values()).forEach(cellPropertyType -> + assertTrue(CellUtil.namePropertyMap.containsValue(cellPropertyType), + "missing " + cellPropertyType)); + } +} diff --git a/poi/src/test/java/org/apache/poi/ss/util/TestDateFormatConverter.java b/poi/src/test/java/org/apache/poi/ss/util/TestDateFormatConverter.java index 059426289e..59c8acf695 100644 --- a/poi/src/test/java/org/apache/poi/ss/util/TestDateFormatConverter.java +++ b/poi/src/test/java/org/apache/poi/ss/util/TestDateFormatConverter.java @@ -130,7 +130,7 @@ final class TestDateFormatConverter { void testJDK8EmptyLocale() { // JDK 8 seems to add an empty locale-string to the list returned via DateFormat.getAvailableLocales() // therefore we now cater for this special locale as well - String prefix = getPrefixForLocale(new Locale("")); + String prefix = getPrefixForLocale(new Locale.Builder().build()); assertEquals("", prefix); } diff --git a/poi/src/test/java/org/apache/poi/util/DefaultTempFileCreationStrategyTest.java b/poi/src/test/java/org/apache/poi/util/DefaultTempFileCreationStrategyTest.java index 4e4f6b779e..d60e4da8ac 100644 --- a/poi/src/test/java/org/apache/poi/util/DefaultTempFileCreationStrategyTest.java +++ b/poi/src/test/java/org/apache/poi/util/DefaultTempFileCreationStrategyTest.java @@ -20,11 +20,14 @@ package org.apache.poi.util; import static org.apache.poi.util.DefaultTempFileCreationStrategy.DELETE_FILES_ON_EXIT; import static org.apache.poi.util.DefaultTempFileCreationStrategy.POIFILES; import static org.apache.poi.util.TempFile.JAVA_IO_TMPDIR; +import static org.junit.jupiter.api.Assertions.assertNotNull; import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; import java.io.File; import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; import org.apache.commons.io.FileUtils; import org.junit.jupiter.api.AfterEach; @@ -59,16 +62,62 @@ class DefaultTempFileCreationStrategyTest { checkGetFile(strategy); } - private static void checkGetFile(DefaultTempFileCreationStrategy strategy) throws IOException { - File file = strategy.createTempFile("POITest", ".tmp"); + @Test + void testProvidedDir() throws IOException { + DefaultTempFileCreationStrategy parentStrategy = new DefaultTempFileCreationStrategy(); + File dir = parentStrategy.createTempDirectory("testProvidedDir"); + assertNotNull(dir, "Failed to create temp directory"); try { - assertTrue(file.getParentFile().exists(), - "Failed for " + file.getParentFile()); + assertTrue(Files.isDirectory(dir.toPath()), "File is not a directory: " + dir); + DefaultTempFileCreationStrategy testStrategy = new DefaultTempFileCreationStrategy(dir); + checkGetFileAndPath(testStrategy, dir.toPath()); + } finally { + // Clean up the directory after the test + FileUtils.deleteDirectory(dir); + } + } - assertTrue(file.exists(), - "Failed for " + file); + @Test + void testProvidedDirThreadLocal() throws IOException { + DefaultTempFileCreationStrategy parentStrategy = new DefaultTempFileCreationStrategy(); + File dir = parentStrategy.createTempDirectory("testProvidedDir"); + assertNotNull(dir, "Failed to create temp directory"); + try { + assertTrue(Files.isDirectory(dir.toPath()), "File is not a directory: " + dir); + DefaultTempFileCreationStrategy testStrategy = new DefaultTempFileCreationStrategy(dir); + TempFile.setThreadLocalTempFileCreationStrategy(testStrategy); + checkGetFileAndPath(dir.toPath()); } finally { - assertTrue(file.delete()); + // Clean up the directory after the test + FileUtils.deleteDirectory(dir); + TempFile.setThreadLocalTempFileCreationStrategy(null); + } + } + + @Test + void testProvidedDirNotExists() throws IOException { + DefaultTempFileCreationStrategy parentStrategy = new DefaultTempFileCreationStrategy(); + File dir = parentStrategy.createTempDirectory("testProvidedDir"); + assertNotNull(dir, "Failed to create temp directory"); + assertTrue(dir.delete(), "directory not deleted: " + dir); + try { + DefaultTempFileCreationStrategy testStrategy = new DefaultTempFileCreationStrategy(dir); + checkGetFileAndPath(testStrategy, dir.toPath()); + } finally { + // Clean up the directory after the test + FileUtils.deleteDirectory(dir); + } + } + + @Test + void testProvidedDirIsActuallyAPlainFile() throws IOException { + DefaultTempFileCreationStrategy parentStrategy = new DefaultTempFileCreationStrategy(); + File dir = parentStrategy.createTempFile("test123", ".tmp"); + assertNotNull(dir, "Failed to create temp file"); + try { + assertThrows(IllegalArgumentException.class, () -> new DefaultTempFileCreationStrategy(dir)); + } finally { + dir.delete(); } } @@ -106,10 +155,11 @@ class DefaultTempFileCreationStrategyTest { } @Test - void testCustomDir() throws IOException { + void testCustomDirExists() throws IOException { File dirTest = File.createTempFile("POITest", ".dir"); try { assertTrue(dirTest.delete()); + assertTrue(dirTest.mkdir()); DefaultTempFileCreationStrategy strategy = new DefaultTempFileCreationStrategy(dirTest); checkGetFile(strategy); @@ -119,11 +169,12 @@ class DefaultTempFileCreationStrategyTest { } @Test - void testCustomDirExists() throws IOException { + void testCustomDirAndPoiFilesExists() throws IOException { File dirTest = File.createTempFile("POITest", ".dir"); try { assertTrue(dirTest.delete()); assertTrue(dirTest.mkdir()); + assertTrue(new File(dirTest, POIFILES).mkdir()); DefaultTempFileCreationStrategy strategy = new DefaultTempFileCreationStrategy(dirTest); checkGetFile(strategy); @@ -132,18 +183,35 @@ class DefaultTempFileCreationStrategyTest { } } - @Test - void testCustomDirAndPoiFilesExists() throws IOException { - File dirTest = File.createTempFile("POITest", ".dir"); + private static void checkGetFile(DefaultTempFileCreationStrategy strategy) throws IOException { + checkGetFileAndPath(strategy, null); + } + + private static void checkGetFileAndPath(DefaultTempFileCreationStrategy strategy, + Path path) throws IOException { + File file = strategy.createTempFile("POITest", ".tmp"); + testFileAndPath(file, path); + } + + private static void checkGetFileAndPath(Path path) throws IOException { + File file = TempFile.createTempFile("POITest", ".tmp"); + testFileAndPath(file, path); + } + + private static void testFileAndPath(File file, Path path) throws IOException { try { - assertTrue(dirTest.delete()); - assertTrue(dirTest.mkdir()); - assertTrue(new File(dirTest, POIFILES).mkdir()); + if (path != null) { + assertTrue(file.toPath().startsWith(path), + "File path does not start with expected path: " + path); + } - DefaultTempFileCreationStrategy strategy = new DefaultTempFileCreationStrategy(dirTest); - checkGetFile(strategy); + assertTrue(file.getParentFile().exists(), + "Failed for " + file.getParentFile()); + + assertTrue(file.exists(), + "Failed for " + file); } finally { - FileUtils.deleteDirectory(dirTest); + assertTrue(file.delete()); } } -}
\ No newline at end of file +} diff --git a/poi/src/test/java/org/apache/poi/util/ExceptionUtilTest.java b/poi/src/test/java/org/apache/poi/util/ExceptionUtilTest.java index d5d4fdd77a..d78e679789 100644 --- a/poi/src/test/java/org/apache/poi/util/ExceptionUtilTest.java +++ b/poi/src/test/java/org/apache/poi/util/ExceptionUtilTest.java @@ -42,7 +42,7 @@ class ExceptionUtilTest { assertTrue(ExceptionUtil.isFatal(new VirtualMachineError(){})); } - + @SuppressForbidden("Test with ThreadDeath on purpose here") @Test void testThreadDeath() { assertTrue(ExceptionUtil.isFatal(new ThreadDeath())); diff --git a/poi/src/test/java/org/apache/poi/util/TestIOUtils.java b/poi/src/test/java/org/apache/poi/util/TestIOUtils.java index bb12f9932e..9c026b14d4 100644 --- a/poi/src/test/java/org/apache/poi/util/TestIOUtils.java +++ b/poi/src/test/java/org/apache/poi/util/TestIOUtils.java @@ -41,6 +41,7 @@ import java.nio.charset.StandardCharsets; import org.apache.commons.io.output.UnsynchronizedByteArrayOutputStream; import org.apache.poi.EmptyFileException; import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.BeforeAll; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.parallel.Isolated; @@ -110,8 +111,25 @@ final class TestIOUtils { } @Test - void testToByteArrayNegativeLength() { - assertThrows(RecordFormatException.class, () -> IOUtils.toByteArray(data123(), -1)); + void testToByteArrayNegativeLength() throws IOException { + final byte[] array = new byte[]{1, 2, 3, 4, 5, 6, 7}; + IOUtils.setByteArrayMaxOverride(30 * 1024 * 1024); + try (ByteArrayInputStream is = new ByteArrayInputStream(array)) { + assertArrayEquals(array, IOUtils.toByteArray(is, -1, 100)); + } finally { + IOUtils.setByteArrayMaxOverride(-1); + } + } + + @Test + void testToByteArrayNegativeLength2() throws IOException { + final byte[] array = new byte[]{1, 2, 3, 4, 5, 6, 7}; + IOUtils.setByteArrayMaxOverride(30 * 1024 * 1024); + try (ByteArrayInputStream is = new ByteArrayInputStream(array)) { + assertArrayEquals(array, IOUtils.toByteArray(is, -1)); + } finally { + IOUtils.setByteArrayMaxOverride(-1); + } } @Test @@ -558,6 +576,64 @@ final class TestIOUtils { assertEquals(4, ret.length); } + @Test + void testNewFile() throws IOException { + final File parent = TempFile.createTempDirectory("create-file-test"); + try { + final String path0 = windowsPathIfNecessary("path/to/file.txt"); + final File outFile = IOUtils.newFile(parent, path0); + assertTrue(outFile.getAbsolutePath().endsWith(path0), + "unexpected path: " + outFile.getAbsolutePath()); + } finally { + assertTrue(parent.delete()); + } + } + + @Test + void testAllowedPathTraversal() throws IOException { + final File parent = TempFile.createTempDirectory("path-traversal-test"); + try { + // this path is ok because it doesn't walk out of the parent directory + final String path0 = windowsPathIfNecessary("a/b/c/../d/e/../../f/g/./h"); + File outFile = IOUtils.newFile(parent, path0); + assertTrue(outFile.getAbsolutePath().endsWith(path0), + "unexpected path: " + outFile.getAbsolutePath()); + } finally { + assertTrue(parent.delete()); + } + } + + @Test + void testAllowedPathTraversal2() throws IOException { + final File parent = TempFile.createTempDirectory("path-traversal-test"); + try { + // this path is ok because it doesn't walk out of the parent directory + // the initial slash is ignored and the generated path is relative to the parent directory + final String path0 = windowsPathIfNecessary("/a/b/c.txt"); + File outFile = IOUtils.newFile(parent, path0); + assertTrue(outFile.getAbsolutePath().endsWith(path0), + "unexpected path: " + outFile.getAbsolutePath()); + } finally { + assertTrue(parent.delete()); + } + } + + @Test + void testDisallowedPathTraversal() throws IOException { + final File parent = TempFile.createTempDirectory("path-traversal-test"); + try { + final String path0 = windowsPathIfNecessary("../a/b/c.txt"); + Assertions.assertThrows(IOException.class, () -> IOUtils.newFile(parent, path0)); + } finally { + assertTrue(parent.delete()); + } + } + + private static String windowsPathIfNecessary(String path) { + // this is a workaround for the Windows file system which doesn't allow slashes in file names + return File.separatorChar == '/' ? path : path.replace('/', File.separatorChar); + } + /** * This returns 0 for the first call to skip and then reads * as requested. This tests that the fallback to read() works. diff --git a/poi/src/test/java/org/apache/poi/util/TestThreadLocalTempFile.java b/poi/src/test/java/org/apache/poi/util/TestThreadLocalTempFile.java new file mode 100644 index 0000000000..86161e59ac --- /dev/null +++ b/poi/src/test/java/org/apache/poi/util/TestThreadLocalTempFile.java @@ -0,0 +1,68 @@ +/* ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +==================================================================== */ +package org.apache.poi.util; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.io.IOException; +import java.io.UncheckedIOException; +import java.nio.file.Path; + +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.RepeatedTest; +import org.junit.jupiter.api.io.TempDir; + +class TestThreadLocalTempFile { + @AfterEach + void tearDown() { + TempFile.setTempFileCreationStrategy(new DefaultTempFileCreationStrategy()); + } + + @RepeatedTest(2) // Repeat it to ensure testing the case + void testThreadLocalStrategy(@TempDir Path tmpDir) { + Path rootDir = tmpDir.toAbsolutePath().normalize(); + Path globalTmpDir = rootDir.resolve("global-tmp-dir"); + Path localTmpDir1 = rootDir.resolve("local-tmp-dir1"); + Path localTmpDir2 = rootDir.resolve("local-tmp-dir2"); + + TempFile.setTempFileCreationStrategy(new DefaultTempFileCreationStrategy(globalTmpDir.toFile())); + assertTempFileIn(globalTmpDir); + + String result = TempFile.withStrategy(new DefaultTempFileCreationStrategy(localTmpDir1.toFile()), () -> { + assertTempFileIn(localTmpDir1); + String nestedResult = TempFile.withStrategy(new DefaultTempFileCreationStrategy(localTmpDir2.toFile()), () -> { + assertTempFileIn(localTmpDir2); + return "nested-test-result"; + }); + assertTempFileIn(localTmpDir1); + return "my-test-result-" + nestedResult; + }); + assertTempFileIn(globalTmpDir); + assertEquals("my-test-result-nested-test-result", result); + } + + private static void assertTempFileIn(Path expectedDir) { + Path tempFile; + try { + tempFile = TempFile.createTempFile("tmp-prefix", ".tmp").toPath(); + } catch (IOException e) { + throw new UncheckedIOException(e); + } + assertTrue(tempFile.startsWith(expectedDir), tempFile.toString()); + } +} diff --git a/src/documentation/README.txt b/src/documentation/README.txt new file mode 100644 index 0000000000..9bc261b2f1 --- /dev/null +++ b/src/documentation/README.txt @@ -0,0 +1,7 @@ +This is the base documentation directory. + +skinconf.xml # This file customizes Forrest for your project. In it, you + # tell forrest the project name, logo, copyright info, etc + +sitemap.xmap # Optional. This sitemap is consulted before all core sitemaps. + # See http://forrest.apache.org/docs/project-sitemap.html diff --git a/src/documentation/RELEASE-NOTES.txt b/src/documentation/RELEASE-NOTES.txt new file mode 100644 index 0000000000..c394295b0a --- /dev/null +++ b/src/documentation/RELEASE-NOTES.txt @@ -0,0 +1,42 @@ +The Apache POI project is pleased to announce the release of POI @VERSION@. +Featured are a handful of new areas of functionality, and numerous bug fixes. + +See the downloads page for source distributions: https://poi.apache.org/download.html + +Release Notes + +Changes +------------ +The most notable changes in this release are: + +@List changes here@ + +A full list of changes is available in the change log: https://poi.apache.org/changes.html. +People interested should also follow the dev mailing list to track further progress. + +Release Contents +---------------- + +This release comes in source form: + - source archive you can build POI from (poi-src-@VERSION@-@DSTAMP@.zip or poi-src-@VERSION@-@DSTAMP@.tar.gz) + Unpack the archive and use the following command to build all POI components with JDK 1.8 or higher: + + gradle jar + + Pre-built versions of all POI components are also available in the central Maven repository + under Group ID "org.apache.poi" and Version "@VERSION@" + +All release artifacts are accompanied by SHA checksums and PGP signatures +that you can use to verify the authenticity of your download. +The public key used for the PGP signature can be found at +https://downloads.apache.org/poi/KEYS + +About Apache POI +----------------------- + +Apache POI is well-known in the Java field as a library for reading and +writing Microsoft Office file formats, such as Excel, PowerPoint, Word, +Visio, Publisher and Outlook. It supports both the older (OLE2) and +new (OOXML - Office Open XML) formats. + +See https://poi.apache.org/ for more details diff --git a/src/documentation/cli.xconf b/src/documentation/cli.xconf new file mode 100644 index 0000000000..88ca2fd763 --- /dev/null +++ b/src/documentation/cli.xconf @@ -0,0 +1,328 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!--+ + | This is the Apache Cocoon command line configuration file. + | Here you give the command line interface details of where + | to find various aspects of your Cocoon installation. + | + | If you wish, you can also use this file to specify the URIs + | that you wish to generate. + | + | The current configuration information in this file is for + | building the Cocoon documentation. Therefore, all links here + | are relative to the build context dir, which, in the build.xml + | file, is set to ${build.context} + | + | Options: + | verbose: increase amount of information presented + | to standard output (default: false) + | follow-links: whether linked pages should also be + | generated (default: true) + | precompile-only: precompile sitemaps and XSP pages, but + | do not generate any pages (default: false) + | confirm-extensions: check the mime type for the generated page + | and adjust filename and links extensions + | to match the mime type + | (e.g. text/html->.html) + | + | Note: Whilst using an xconf file to configure the Cocoon + | Command Line gives access to more features, the use of + | command line parameters is more stable, as there are + | currently plans to improve the xconf format to allow + | greater flexibility. If you require a stable and + | consistent method for accessing the CLI, it is recommended + | that you use the command line parameters to configure + | the CLI. See documentation at: + | http://cocoon.apache.org/2.1/userdocs/offline/ + | http://wiki.apache.org/cocoon/CommandLine + | + +--> + +<cocoon verbose="true" + follow-links="true" + precompile-only="false" + confirm-extensions="false"> + + <!--+ + | The context directory is usually the webapp directory + | containing the sitemap.xmap file. + | + | The config file is the cocoon.xconf file. + | + | The work directory is used by Cocoon to store temporary + | files and cache files. + | + | The destination directory is where generated pages will + | be written (assuming the 'simple' mapper is used, see + | below) + +--> + <context-dir>.</context-dir> + <config-file>WEB-INF/cocoon.xconf</config-file> + <work-dir>../tmp/cocoon-work</work-dir> + <dest-dir>../site</dest-dir> + + <!--+ + | A checksum file can be used to store checksums for pages + | as they are generated. When the site is next generated, + | files will not be written if their checksum has not changed. + | This means that it will be easier to detect which files + | need to be uploaded to a server, using the timestamp. + | + | The default path is relative to the core webapp directory. + | An asolute path can be used. + +--> + <!-- <checksums-uri>build/work/checksums</checksums-uri>--> + + <!--+ + | Broken link reporting options: + | Report into a text file, one link per line: + | <broken-links type="text" report="filename"/> + | Report into an XML file: + | <broken-links type="xml" report="filename"/> + | Ignore broken links (default): + | <broken-links type="none"/> + | + | Two attributes to this node specify whether a page should + | be generated when an error has occured. 'generate' specifies + | whether a page should be generated (default: true) and + | extension specifies an extension that should be appended + | to the generated page's filename (default: none) + | + | Using this, a quick scan through the destination directory + | will show broken links, by their filename extension. + +--> + <broken-links type="xml" + file="../brokenlinks.xml" + generate="false" + extension=".error" + show-referrers="true"/> + + <!--+ + | Load classes at startup. This is necessary for generating + | from sites that use SQL databases and JDBC. + | The <load-class> element can be repeated if multiple classes + | are needed. + +--> + <!-- + <load-class>org.firebirdsql.jdbc.Driver</load-class> + --> + + <!--+ + | Configures logging. + | The 'log-kit' parameter specifies the location of the log kit + | configuration file (usually called logkit.xconf. + | + | Logger specifies the logging category (for all logging prior + | to other Cocoon logging categories taking over) + | + | Available log levels are: + | DEBUG: prints all level of log messages. + | INFO: prints all level of log messages except DEBUG + | ones. + | WARN: prints all level of log messages except DEBUG + | and INFO ones. + | ERROR: prints all level of log messages except DEBUG, + | INFO and WARN ones. + | FATAL_ERROR: prints only log messages of this level + +--> + <!-- <logging log-kit="WEB-INF/logkit.xconf" logger="cli" level="ERROR" /> --> + + <!--+ + | Specifies the filename to be appended to URIs that + | refer to a directory (i.e. end with a forward slash). + +--> + <default-filename>index.html</default-filename> + + <!--+ + | Specifies a user agent string to the sitemap when + | generating the site. + | + | A generic term for a web browser is "user agent". Any + | user agent, when connecting to a web server, will provide + | a string to identify itself (e.g. as Internet Explorer or + | Mozilla). It is possible to have Cocoon serve different + | content depending upon the user agent string provided by + | the browser. If your site does this, then you may want to + | use this <user-agent> entry to provide a 'fake' user agent + | to Cocoon, so that it generates the correct version of your + | site. + | + | For most sites, this can be ignored. + +--> + <!-- + <user-agent>Cocoon Command Line Environment 2.1</user-agent> + --> + + <!--+ + | Specifies an accept string to the sitemap when generating + | the site. + | User agents can specify to an HTTP server what types of content + | (by mime-type) they are able to receive. E.g. a browser may be + | able to handle jpegs, but not pngs. The HTTP accept header + | allows the server to take the browser's capabilities into account, + | and only send back content that it can handle. + | + | For most sites, this can be ignored. + +--> + + <accept>*/*</accept> + + <!--+ + | Specifies which URIs should be included or excluded, according + | to wildcard patterns. + | + | These includes/excludes are only relevant when you are following + | links. A link URI must match an include pattern (if one is given) + | and not match an exclude pattern, if it is to be followed by + | Cocoon. It can be useful, for example, where there are links in + | your site to pages that are not generated by Cocoon, such as + | references to api-documentation. + | + | By default, all URIs are included. If both include and exclude + | patterns are specified, a URI is first checked against the + | include patterns, and then against the exclude patterns. + | + | Multiple patterns can be given, using muliple include or exclude + | nodes. + | + | The order of the elements is not significant, as only the first + | successful match of each category is used. + | + | Currently, only the complete source URI can be matched (including + | any URI prefix). Future plans include destination URI matching + | and regexp matching. If you have requirements for these, contact + | dev@cocoon.apache.org. + +--> + + <exclude pattern="**/"/> + <exclude pattern="api/**"/> + <!-- POI Customisation - allow us to have an index page at /apidocs/ --> + <exclude pattern="**apidocs/dev/**"/> + <exclude pattern="**apidocs/3.*/**"/> + <exclude pattern="**apidocs/4.*/**"/> + +<!-- + This is a workaround for FOR-284 "link rewriting broken when + linking to xml source views which contain site: links". + See the explanation there and in declare-broken-site-links.xsl +--> + <exclude pattern="site:**"/> + <exclude pattern="ext:**"/> + <exclude pattern="lm:**"/> + <exclude pattern="**/site:**"/> + <exclude pattern="**/ext:**"/> + <exclude pattern="**/lm:**"/> + + <!-- Exclude tokens used in URLs to ASF mirrors (interpreted by a CGI) --> + <exclude pattern="[preferred]/**"/> + <exclude pattern="[location]"/> + + <!-- <include-links extension=".html"/>--> + + <!--+ + | <uri> nodes specify the URIs that should be generated, and + | where required, what should be done with the generated pages. + | They describe the way the URI of the generated file is created + | from the source page's URI. There are three ways that a generated + | file URI can be created: append, replace and insert. + | + | The "type" attribute specifies one of (append|replace|insert): + | + | append: + | Append the generated page's URI to the end of the source URI: + | + | <uri type="append" src-prefix="documents/" src="index.html" + | dest="build/dest/"/> + | + | This means that + | (1) the "documents/index.html" page is generated + | (2) the file will be written to "build/dest/documents/index.html" + | + | replace: + | Completely ignore the generated page's URI - just + | use the destination URI: + | + | <uri type="replace" src-prefix="documents/" src="index.html" + | dest="build/dest/docs.html"/> + | + | This means that + | (1) the "documents/index.html" page is generated + | (2) the result is written to "build/dest/docs.html" + | (3) this works only for "single" pages - and not when links + | are followed + | + | insert: + | Insert generated page's URI into the destination + | URI at the point marked with a * (example uses fictional + | zip protocol) + | + | <uri type="insert" src-prefix="documents/" src="index.html" + | dest="zip://*.zip/page.html"/> + | + | This means that + | (1) + | + | In any of these scenarios, if the dest attribute is omitted, + | the value provided globally using the <dest-dir> node will + | be used instead. + +--> + <!-- + <uri type="replace" + src-prefix="samples/" + src="hello-world/hello.html" + dest="build/dest/hello-world.html"/> + --> + + <!--+ + | <uri> nodes can be grouped together in a <uris> node. This + | enables a group of URIs to share properties. The following + | properties can be set for a group of URIs: + | * follow-links: should pages be crawled for links + | * confirm-extensions: should file extensions be checked + | for the correct mime type + | * src-prefix: all source URIs should be + | pre-pended with this prefix before + | generation. The prefix is not + | included when calculating the + | destination URI + | * dest: the base destination URI to be + | shared by all pages in this group + | * type: the method to be used to calculate + | the destination URI. See above + | section on <uri> node for details. + | + | Each <uris> node can have a name attribute. When a name + | attribute has been specified, the -n switch on the command + | line can be used to tell Cocoon to only process the URIs + | within this URI group. When no -n switch is given, all + | <uris> nodes are processed. Thus, one xconf file can be + | used to manage multiple sites. + +--> + <!-- + <uris name="mirrors" follow-links="false"> + <uri type="append" src="mirrors.html"/> + </uris> + --> + + <!--+ + | File containing URIs (plain text, one per line). + +--> + <!-- + <uri-file>uris.txt</uri-file> + --> +</cocoon> diff --git a/src/documentation/content/locationmap.xml b/src/documentation/content/locationmap.xml new file mode 100644 index 0000000000..4f5ab0941b --- /dev/null +++ b/src/documentation/content/locationmap.xml @@ -0,0 +1,41 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<locationmap xmlns="http://apache.org/forrest/locationmap/1.0"> + <components> + <matchers default="lm"> + <matcher + name="lm" + src="org.apache.forrest.locationmap.WildcardLocationMapHintMatcher"/> + </matchers> + </components> + <locator> +<!-- + To locate all your source documents in a slide repository you can do: + + <match pattern="tabs.xml"> + <location src="http://127.0.0.1:8080/slide/files/tabs.xml"/> + </match> + <match pattern="site.xml"> + <location src="http://127.0.0.1:8080/slide/files/site.xml"/> + </match> + <match pattern="**.xml"> + <location src="http://127.0.0.1:8080/slide/files/{1}.xml"/> + </match> + --> + </locator> +</locationmap> diff --git a/src/documentation/content/xdocs/apidocs/index.xml b/src/documentation/content/xdocs/apidocs/index.xml new file mode 100644 index 0000000000..8266786b10 --- /dev/null +++ b/src/documentation/content/xdocs/apidocs/index.xml @@ -0,0 +1,85 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - Javadocs</title> + <authors> + <person id="PD" name="POI Developers" email="dev@poi.apache.org" /> + </authors> + </header> + + <body> + <section><title>Apache POI Javadocs</title> + <p> + The Javadocs for the latest (development) version of Apache POI + can be <a href="dev/index.html">accessed online here</a>, or build + from a <a href="site:git">source code checkout</a> + by running the <em>javadocs</em> Ant task. The + <a href="dev/index.html">latest (development) Javadocs</a> are generally + updated every few weeks, so may lag the most recent development slightly. + </p> + <p> + For recent releases, the Javadocs for the latest stable release + each the family can also be browsed online: + </p> + <ul> + <li><a href="ext:apidocs/v50">Apache POI 5.0.x Javadocs</a></li> + <li><a href="ext:apidocs/v41">Apache POI 4.1.x Javadocs</a></li> + <li><a href="ext:apidocs/v40">Apache POI 4.0.x Javadocs</a></li> + <li><a href="ext:apidocs/v317">Apache POI 3.17 Javadocs</a></li> + </ul> + + <section><title>Older Releases</title> + <p> + For every release of Apache POI, the specific Javadocs for that + version are available with the release. + </p> + <p> + Maven / Gradle / IDE users are able to fetch the javadocs for each + of the Apache POI jars from Maven Central (or your preferred Maven + mirror). These are made available with the <em>javadoc</em> classifier, + e.g. <em>group: 'org.apache.poi', name: 'poi', version: '4.1.1', + classifier: 'javadoc'</em> + </p> + <p> + If you have downloaded the <em>binary (bin)</em> release, then you + can find the Javadocs within the download in the <em>/docs/apidocs/</em> + folder. + </p> + <p> + If you have downloaded the <em>source (src)</em> release, then you + need to build your own copy. Run the <em>javadocs</em> ant task + to have the Javadocs built, the build will tell you the output + directory at the end (it varies slightly between POI versions). + </p> + </section> +</section> +</body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/casestudies.xml b/src/documentation/content/xdocs/casestudies.xml new file mode 100644 index 0000000000..af370b1138 --- /dev/null +++ b/src/documentation/content/xdocs/casestudies.xml @@ -0,0 +1,451 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - Case Studies</title> + <authors> + <person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/> + <person id="CR" name="Cameron Riley" email="crileyNO@SPAMekmail.com"/> + <person id="DF" name="David Fisher" email="dfisher@jmlafferty.com"/> + <person id="DS" name="Dominik Stadler" email="centic@apache.org"/> + </authors> + </header> + + <body> + <section> + <title>Introduction</title> + <p> + A number of people are using POI for a variety of purposes. As with + any new API or technology, the first question people generally ask + is not "how can I" but rather "Who else is doing what I'm about to + do?" This is understandable with the abysmal success rate in the + software business. These case statements are meant to help create + confidence and understanding. + </p> + </section> + <section> + <title>Submitting a Case Study</title> + <p> + We are actively seeking case studies for this page (after all it + just started). To submit a case study, either + <a href="site:guidelines"> + submit a patch for this page</a> or email it to the + <a href="site:mailinglists">mailing list + </a> (with [PATCH] prefixed subject, please). + </p> + </section> + <section> + <title>Case Studies</title> + + <section><title>Manticore Projects - VBox Financial Reporting Software</title> + <p> + <em>Andreas Reichel, Managing Consultant</em><br/><br/> + </p> + <p> + <strong>Use Case for Apache POI in VBox Financial Reporting Software</strong><br/> + <a href="https://manticore-projects.com/">Manticore Projects</a> specializes in Financial Valuation, + Accounting, and Reporting under IFRS 9, IFRS 16, and IFRS 17. The software extensively leverages + Apache POI for importing, exporting, and visualizing data, making it a cornerstone of the solutions. + </p> + <p> + <strong>SQL Sheet Integration for Data Capture</strong><br/> + The software uses and supports <a href="https://github.com/panchmp/sqlsheet">SQL Sheet</a> to build + "Data Capture Sheets", allowing end-users to seamlessly upload structured data via Microsoft Excel + spreadsheets into applications. <a href="https://github.com/panchmp/sqlsheet">SQL Sheet</a>, a JDBC driver + for XLS/XLSX files based on Apache POI, transforms worksheets into database tables, enabling access + through plain SQL and JDBC MetaData. + </p> + <p> + <strong>Streamlined Excel Exports for Controllers and Auditors</strong><br/> + Within VBox applications, Apache POI enables interactive export of UI content, such as data tables, into + formatted Excel spreadsheets. This functionality provides financial controllers and auditors with easy + access to complex data and calculations in a familiar format. + </p> + <p> + <strong>ETL-VBox Report Builder for Regulatory Compliance</strong><br/> + + The <a href="https://manticore-projects.com/VBox/etl.html">ETL-VBox Report Builder</a> uses Apache POI + to create spreadsheet-based form reports, a critical requirement for regulatory reporting. Regulatory + bodies often provide specific MS Excel templates with multiple sheets representing data forms and fields.<br/> + With Apache POI, the software visualizes these Excel templates directly in the UI, mimicking the Excel + experience. Non-technical users can drag and drop records or values from data cubes into the spreadsheet + interface. This "data to cell-range" mapping is stored and used to populate the workbook automatically, + ensuring reports are generated accurately and on time—such as during daily end-of-day processes.<br/> + One of the standout benefits of this approach is the platform independent separation of report templates + (including corporate design styles, formulas, and charts) from the actual data. By leveraging Apache POI, + it bridges the gap between structured data and Excels flexibility, delivering the best of both worlds for + end-users who love working in Excel. + </p> + <p> + <strong>Why Apache POI?</strong><br/> + Apache POI has proven to be a high-performance and robust library. It is supported by comprehensive + documentation and an excellent community of developers. At + <a href="https://manticore-projects.com/">Manticore Projects</a>, we are proud + contributors to this vibrant community and deeply value the collaboration that drives the evolution of this + indispensable tool.<br/> + By integrating Apache POI into our software, we empower users with intuitive and powerful features for + financial reporting, helping them meet their regulatory and operational needs with confidence. + </p> + </section> + + <section><title>WriteExcel Utilities</title> + <p> + This WriteExcel distribution package found at <a href="https://stevepritchard.ca/home/WriteExcel/overview.htm">WriteExcel Utilities</a> contains source, + documentation, examples, build tools and precompiled classes that wrap the Apache POI Excel interface. + </p> + <p> + WriteExcel creates a Workbook file using a simple interface that uses formatted strings as the primary way + of passing information to the support methods which interpret the strings and issue the necessary POI method calls. + Access to the <code>Workbook</code> object allows the POI methods to be called directly for cases not handled by the interface. + </p> + <p> + An existing Workbook file can be used as a template source so that sheets can be copied and then left intact, modified and/or supplemented. + </p> + <p> + The creation of Workbooks containing charts is supported by using an existing Workbook file as a template that contains one or more charts + and using WriteExcel to modify the data that the chart refers to. + </p> + <p> + The ReadExcelFile component of the package can be used to selectively iterate across existing Workbooks (or Workbooks under construction) and create + Java objects with the selected data which can then be forwarded for further processing. + <br/><br/> + WriteExcel was used to produce the monthly reporting files for a church accounting system among other things. + <br/><br/> + Steve Pritchard<br/> + Rexcel Systems Inc.<br/> + July, 2019<br/> + <a href="https://stevepritchard.ca">Steve Pritchard Utilities</a> + </p> + </section> + + <section><title>Processing biometric scanner logs - Glassbeam</title> + <p> + As a small startup there is no attendance management system in place. So they have a manual register where + they record attendance. There also is a biometric scanner to allow entries through the office gates, + which again maintains logs of entries. + Instead of establishing an attendance management system, they decided to make use of these biometric scanner logs and generate an + excel report instead. + </p> + <p> + A <a href="http://www.shivamkapoor.com/blogs/technology/2019/07/10/code-design-template-for-apache-poi-based-excel-writers/">blog post</a> describes how + the startup uses Apache POI to generate reports about attendance of employees based on biometric scanner logs. + </p> + <p> + A fully working solution can be found on <a href="https://github.com/codingkapoor/essl-attendance-report-generator">Github</a>. + </p> + </section> + + <section><title>REWOO Scope</title> + <p> + <a href="http://www.rewoo.de/">REWOO Scope</a> is a modern and easy to use web-based enterprise content management system. It supports knowledge workers and managers in making the right decisions based upon all relevant information. + </p> + <p> + The system uses Apache POI to extract information stored within excel files and use it transparently within REWOO Scope. Thus, POI allows our customers to work in their standard office environment while also having all important information in the REWO Scope system. + </p> + </section> + + <section><title>QuestionPro</title> + <p> + <a href="http://www.questionpro.com">QuestionPro</a> is an online service allowing businesses and individuals to create, deploy and do in-depth analysis of Online Surveys. The technology is build on open-source frameworks like Struts, Velocity, POI, Lucene ... the List goes on. The application deployment is on a Linux Application Cluster farm with a Mysql database. + </p> + <p> + There are quite a few competitors delivering similar solutions using Microsoft Technologies like asp and .net. One of the distinct advantages our competitors had over us was the ability to generate Excel Spreadsheets, Access Databases (MDB) etc. on the fly using the Component Object Model (COM) - since their servers were running IIS and they had access to the COM registry and such. + </p> + <p> + QuestionPro's initial solution was to generate CSV files. This was easy however it was a cumbersome process for our clients to download the CSV files and then import them into Excel. Moreover, formatting information could not be preserved or captured using the CSV format. This is where POI came to our rescue. With a POI based solution, we could generate a full report with multiple sheets and all the analytical reports. To keep the solution scalable, we had a dedicated cluster for generating out the reports. + </p> + <p> + + The Apache-POI project has helped QuestionPro compete with the other players in the marketplace with proprietary technology. It leveled the playing field with respect to reporting and data analysis solutions. It helped in opening doors into closed solutions like Microsoft's CDF. Today about 100 excel reports are generated daily, each with about 10-30 sheets in them. + </p> + + <p> + Vivek Bhaskaran + </p> + <p> + <a href="http://www.questionpro.com">QuestionPro, Inc</a> + </p> + + <p> + POI In Action - <a href="http://www.questionpro.com/marketing/SurveyReport-289.xls">http://www.questionpro.com/marketing/SurveyReport-289.xls</a> + </p> + + </section> + + <section><title>Sunshine Systems</title> + <p> + <a href="http://www.sunshinesys.com/">Sunshine Systems</a> developed a + POI based reporting solution for a price optimization software package which + is used by major retail chains. + </p> + <p>The solution allowed the retailer's merchandise planners and managers to request a + markdown decision support reports and price change reports using a standard browser + The users could specify report type, report options, as well as company, +division, + and department filter criteria. Report generation took place in the +multi-threaded + application server and was capable of supporting many simultaneous report requests. + </p> + <p>The reporting application collected business information from the price +optimization + application's Oracle database. The data was aggregated and summarized + based upon the + specific report type and filter criteria requested by the user. The +final report was + rendered as a Microsoft Excel spreadsheet using the POI HSSF API and + was stored on + the report database server for that specific user as a BLOB. Reports + could be + seamlessly and easily viewed using the same browser. + </p> + <p>The retailers liked the solution because they had instantaneous access + to critical + business data through an extremely easy to use browser interface. They + did not need + to train the broader user community on all the complexities of the optimization + application. Furthermore, the reports were generated in an Excel spreadsheet +format, + which everyone was familiar with and which also allowed further data + analysis using + standard Excel features. + </p> + <p>Rob Stevenson (rstevenson at sunshinesys dot com) + </p> + </section> + <section> + <title>Bank of Lithuania</title> + <p> + The + <a href="http://www.lbank.lt/">Bank of Lithuania</a> + reports financial statistical data to Excel format using the + <a href="https://poi.apache.org/">Apache POI</a> + project's + <a href="site:spreadsheet"> + HSSF</a> API. The system is based on Oracle JServer and + utilizes a Java stored procedure that outputs to XLS format + using the HSSF API. - Arian Lashkov (alaskov at lbank.lt) + </p> + </section> +<!-- <section>--> +<!-- <title>Bit Tracker by Tracker Inc., and ThinkVirtual</title>--> +<!-- <p>--> +<!-- Bit Tracker (http://www.bittracker.com/) is the world's first and only web-based drill bit tracking system to manage your company's critical bit information and use that data to its full potential. It manages all bit related data, including their usage, locations, how they were used, and results such as rate of penetration and dull grade after use. This data needs to be available in Excel format for backwards compatibility and other uses in the industry. After using CSV and HTML formats, we needed something better for creating the spreadsheets and POI is the answer. It works great and was easy to implement. Kudos to the POI team.--> +<!-- </p>--> +<!-- <p>--> +<!-- Travis Reeder (travis at thinkvirtual dot com)--> +<!-- </p>--> +<!-- </section>--> + <section> + <title>Edwards And Kelcey Technology</title> + <p> + Edwards and Kelcey Technology (http://www.ekcorp.com/) developed a + Facility + Management and Maintenance System for the Telecommunications industry + based + on Turbine and Velocity. Originally the invoicing was done with a simple + CSV + sheet which was then marked up by accounts and customized for each client. + As growth has been consistent with the application, the requirement for + invoices that need not be touched by hand increased. POI provided the + solution to this issue, integrating easily and transparently into the + system. POI HSSF was used to create the invoices directly from the server + in + Excel 97 format and now services over 150 unique invoices per month. + </p> + <p> + Cameron Riley (crileyNO@ SPAMekmail.com) + </p> + </section> + <section> + <title>ClickFind</title> + <p> + <a href="http://www.clickfind.com/">ClickFind Inc.</a> used the POI + projects HSSF API to provide their medical + research clients with an Excel export from their electronic data + collection web service Data Collector 3.0. The POI team's assistance + allowed ClickFind to give their clients a data format that requires less + technical expertise than the XML format used by the Data Collector + application. This was important to ClickFind as many of their current + and potential clients are already using Excel in their day-to-day + operations and in established procedures for handling their generated + clinical data. - Jared Walker (jared.walker at clickfind.com) + </p> + </section> + <section> + <title>IKAN Software NV</title> + <p>In addition to Change Management and Database Modelling, IKAN Software NV + (http://www.ikan.be/) develops and supports its own ETL + (Extract/Transform/Load) tools.</p> + + <p>IKAN's latest product is this domain is called ETL4ALL + (http://www.ikan.be/etl4all/). ETL4ALL is an open source tool + allowing data transfer from and to virtually any data source. Users can + combine and examine data stored in relational databases, XML databases, PDF + files, EDI, CSV files, etc. + </p> + + <p>It is obvious that Microsoft Excel files are also supported. + POI has been used to successfully implement this support in ETL4ALL.</p> + </section> + <section> + <title>JM Lafferty Associates, Inc.</title> + <p> + On its <a href="http://www.forecastworks.com/public/">ForecastWorks</a> website + <a href="http://www.jmlafferty.com/">JM Lafferty Associates, Inc.</a> produces dynamic on demand + financial analyses of companies and institutional funds. The pages produced are selected and exported + in several file formats including PPT and XLS. + </p> + <ul> + <li>The PPT files produced are of high quality which is on a par with similar PDF files.</li> + <li>The XLS files produced contain a complex forecasting model built from a template with a VBA Macro.</li> + </ul> + <p> + David Fisher (dfisher@jmlafferty.com) + </p> + </section> + + <section> + <title>iDATA Development Ltd (IDD)</title> + <p> + <a href="http://www.iexlsoftware.com/">IDD</a> have developed the iEXL product to + generate Excel spreadsheets directly on the Iseries/AS400 IBM I on Power platform. + </p> + <p> + Professional spreadsheets created via a menu system. Some basic programming is required for more complex options. + When programming is required it can be carried out using RPG, SQL, QUERY, JAVA, COBOL etc. + In other words your existing staffs knowledge + </p> + <p> + Design spreadsheets with: + </p> + <ul> + <li>Fonts down to cell level</li> + <li>Colours (Background and text) down to cell level</li> + <li>Shading down to cell level</li> + <li>Cell patterns down to cell level</li> + <li>Cell initialization</li> + <li>Freeze Panes</li> + <li>Passwords</li> + <li>Images/Pictures both static and dynamic</li> + <li>Headings</li> + <li>Page breaks</li> + <li>Sheet breaks</li> + <li>Text insertion and much more</li> + <li>Functions/Formula</li> + <li>Merge cells</li> + <li>Row Height</li> + <li>Cell text alignment</li> + <li>Text Rotation </li> + <li>50 Database files per workbook.</li> + <li>E-mail the spreadsheet</li> + </ul> + <p> + The product name is 'iEXL' and has been live on both European and North American systems for over four years. + It is being used in preference to more established commercial products which our clients have already purchased. + This is due to cost and ease of use. + </p> + <p> + All spreadsheets can be archived if required so that historical spreadsheets can be retrieved. + </p> + <p> + The system has benefits for all departments within an organisation. + Examples of this are accounts department for things such as aged trial balance, + distribution department for ASN’s, warehousing for stock figures, IS for security reporting etc. + </p> + <p> + Clients have at this point (June 2012) created over 300 spreadsheets which in turn have generated over + 500,000 E-mails. iEXL has a menu driven email system. + </p> + <p> + Due to the Apache-POI project IDD have been able to create the IEXL product. + This is a well priced product which allows companies of all sizes access to a product that opens up their reporting capabilities + </p> + <p> + Within the <a href="http://www.iexlsoftware.com/">iEXLSOFTWARE.COM</a> website you will find a full user manual, + installation instructions, a call log (Ticket) system and a downloadable 45 day trial version. + </p> + <p> + <em>Author: Mark.D.Golden</em> + </p> + </section> + <section> + <title>Ugly Duckling</title> + <p> + <a href="http://uglyduckling.nl/">Ugly Duckling</a> focus on Software, Management and Finance. + We have recently been using Apache POI to create tools for the mortgage group of + <a href="https://www.abnamro.nl/en/personal/index.html">ABN AMRO</a> in the Netherlands. + During this project we created a number of what we call 'Robots' using the HSSF API. + </p> + <p> + These <a href="http://uglyduckling.nl/work/robots/">robots</a> run as services on the network and + help automate the processing of large amounts of data. Our Robots can be used to spot problems that + a human might not, and also to automate repetitive tasks. + </p> + <p> + We found Apache POI to be extremely useful. We took the base API, wrapped it in a builder pattern and + thus created a DSL with a fluid interface. Throughout the project we enjoyed very much working with + Apache POI and found it to be very reliable. + </p> + </section> + + <section> + <title>Deutsche Bahn</title> + + <p>Deutsche Bahn uses POI's HWPF component to process complex specification documents stored in the legacy Microsoft Word file format.</p> + <p> + In a joint effort with other international partners, <a href="http://fahrweg.dbnetze.com/fahrweg-en/start/company_aboutus/">Deutsche Bahn Netz AG</a>, + the owner of the German rail infrastructure, developed a novel software toolchain to facilitate the creation of an interoperable on-board component + for a pan-European train protection system. One part of this toolchain is a domain-specific specification processor which reads the relevant + requirements documents using Apache POI, enhances them and ultimately stores their contents as <a href="http://www.omg.org/spec/ReqIF/">ReqIF</a>. + Contrary to DOC, this XML-based file format allows for proper traceability and versioning in a multi-tenant environment. Thus, it lends itself much + better to the management and interchange of large sets of system requirements. The resulting ReqIF files are then consumed by the various tools in + the later stages of the software development process. + </p> + <p> + Currently available, off-the-shelf software for requirement import performed very poorly on the original specification documents due to their + structural complexity and heterogeneous formatting. POI not only helped to create a superior solution thanks to its rich API. Because of its + open-source nature it also plays a key role in ensuring the maintainability of the resulting system which is expected to stay in operation for + many decades to come. + </p> + <p> + POI has seen various enhancements for this challenging application. Most notably, these include the addition of extensive list numbering support, + a feature which is now part of Apache TIKA. Numerous smaller improvements, such as support for table cell background shadings, interpretation of + certain kinds of OfficeDrawings, and proper conversion of special characters, also helped to derive meaning from the input files. See + <a href="http://nbn-resolving.de/urn:nbn:de:bsz:14-qucosa-182866">here</a> for details. + </p> + <p> + This work was funded by the German Federal Ministry of Education and Research (Grant No. 01IS12021) in the context of the ITEA2 project + <a href="http://openetcs.org/">openETCS</a>. + </p> + </section> + + </section> + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/changes.xml b/src/documentation/content/xdocs/changes.xml new file mode 100644 index 0000000000..9fecf0a1e4 --- /dev/null +++ b/src/documentation/content/xdocs/changes.xml @@ -0,0 +1,786 @@ +<?xml version="1.0" encoding="UTF-8"?><!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE changes PUBLIC "-//APACHE//DTD Changes POI//EN" "changes-poi.dtd"> + +<changes> + <contexts> + <context id="OOXML" title="OOXML"/> + <context id="OPC" title="OPC"/> + <context id="POI_Overall" title="POI Overall"/> + <context id="HSSF" title="Horrible SpreadSheet Format"/> + <context id="XSSF" title="ooXml SpreadSheet Format"/> + <context id="SXSSF" title="Streaming ooXml SpreadSheet Format"/> + <context id="SS_Common" title="SpreadSheet Common"/> + <context id="HSLF" title="Horrible SlideShow Format"/> + <context id="XSLF" title="ooXml SlideShow Format"/> + <context id="SL_Common" title="SlideShow Common"/> + <context id="HWPF" title="Horrible WordProcessor Format"/> + <context id="XWPF" title="ooXml WordProcessor Format"/> + <context id="HDF" title="Horrible Document Format"/> + <context id="HPSF" title="Horrible PropertySet Format"/> + <context id="HDGF" title="Horrible Dreadful Graph Format"/> + <context id="XDGF" title="ooXml Dreadful Graph Format"/> + <context id="DDF" title="Dreadful Drawing Format"/> + <context id="XDDF" title="ooXml Dreadful Drawing Format"/> + <context id="HMEF" title="Horrible Mail Encoder Format"/> + <context id="HSMF" title="Horrible Senseless Format"/> + <context id="HPBF" title="Horrible Peep Book Format"/> + <context id="HWMF" title="Horrible Wannabe Metafile Format"/> + <context id="HEMF" title="Horrible Ermahgerd Metafile Format"/> + <context id="POIFS" title="Poor Obfuscation Implementation FileSystem"/> + </contexts> + + <!-- + ACTION ATTRIBUTES: + + type: fix, add, remove, update, unknown + + fixes-bug: a comma-separated list of bugzilla bugs or github-## + + breaks-compatibility: used whenever an intentional (or unintentional?) backwards compatibility + was introduced without having a deprecation warning for at least 2 final releases. + Use a value of "true" to indicate a breakage. Otherwise, omit this attribute. + + context: a space-separated list of modules related to the change. Use POI, OOXML, OPC, etc to refer + to changes to core POI code rather than listing all of the modules, or SS Common and SL Common + when referring to both H??F and X??F formats. + --> + + <section id="previous_releases"> + <title>Previous releases</title> + <p>The change log for <a href="site:changes3x">POI 3.x</a> and + <a href="site:changespre3x">older releases</a> + can be found in the history section. + </p> + </section> + + <release version="5.5.0" date="2025-??-??"> + <summary> + <summary-item>Upgrade batik dependency to 1.19</summary-item> + <summary-item>Upgrade bouncycastle dependency to 1.81</summary-item> + <summary-item>Upgrade commons-codec dependency to 1.19.0</summary-item> + <summary-item>Upgrade commons-collections4 dependency to 4.5.0</summary-item> + <summary-item>Upgrade commons-compress dependency to 1.28.0</summary-item> + <summary-item>Upgrade commons-io dependency to 2.20.0</summary-item> + <summary-item>Upgrade pdfbox dependency to 3.0.5</summary-item> + <summary-item>Upgrade xmlsec dependency to 3.0.6</summary-item> + <summary-item>Upgrade JaCoCo code-coverage tooling to 0.8.13</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="66687" context="SXSSF">Combination of XSSF and SXSSF may result in invalid files</action> + <action type="fix" fixes-bug="69646" context="SXSSF">SXSSF: check for null _fd instance in dispose call</action> + <action type="fix" fixes-bug="69667" context="HSSF">Handle slightly broken WriteAccessRecord gracefully</action> + <action type="fix" fixes-bug="69669" context="HSLF">Fix issue where Slide addTitle corrupts the ppt file</action> + <action type="fix" fixes-bug="69720" context="XWPF">Support null alignment values in XWPFParagraph</action> + <action type="fix" fixes-bug="69727" context="XSSF">Decrease count when we remove merged regions</action> + <action type="fix" fixes-bug="69744" context="XWPF">Support all possible alignment values for docx tables</action> + <action type="fix" fixes-bug="github-770" context="XSLF">Issue in setBulletStyle in XSLFTextParagraph</action> + <action type="add" fixes-bug="github-803" context="SS_Common">Add support for SHEET function</action> + <action type="add" fixes-bug="github-804" context="XWPF">Add getters and setters for XWPFTable indentation</action> + <action type="fix" fixes-bug="github-864" context="XDDF">Remove deprecated method XDDFChartData getSeries()</action> + </actions> + </release> + + <release version="5.4.1" date="2025-04-06"> + <summary> + <summary-item>Note: JDK 24 will change behavior of locale providers, some formatting might be different when upgrading</summary-item> + <summary-item>Upgrade commons-codec dependency to 1.18.0</summary-item> + <summary-item>Upgrade bouncycastle dependency to 1.80</summary-item> + <summary-item>Upgrade pdfbox dependency to 3.0.4</summary-item> + <summary-item>Upgrade graphics2d dependency to 3.0.3</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="69618" context="OOXML">ZipPackage save should check that intermediate steps succeed</action> + <action type="add" fixes-bug="github-775" context="OOXML">Allow some OPC compliance checks to be tuned</action> + <action type="fix" fixes-bug="66260" context="XWPF">Add getNumberOfTexts() method</action> + <action type="fix" fixes-bug="68094" context="SXSSF">Allow to use SXSSFSheet.setArbitraryExtraWidth() to define an adjustment-factor when auto-sizing columns</action> + <action type="fix" fixes-bug="57603" context="HWPF">Fix reading/writing of documents with many columns</action> + <action type="fix" fixes-bug="65190" context="SS_Common">Handle decimal format '0#' the same way as Excel</action> + <action type="fix" fixes-bug="66425" context="POI_Overall">Multiple fixes found by fuzzing Apache POI via oss-fuzz</action> + <action type="add" fixes-bug="66260" context="XWPF">Add getNumberOfTexts method to XWPFRun</action> + <action type="fix" fixes-bug="69315" context="HSMF">Continue processing properties after multivalued properties</action> + <action type="fix" fixes-bug="69529" context="XSSF">Streamed reading: Log failures to format formulas and numbers instead of stopping processing</action> + <action type="fix" fixes-bug="69536" context="SXSSF">Fix arbitrary extra width support</action> + <action type="fix" fixes-bug="69555" context="SXSSF">Handle extra issue where FontSystem is missing</action> + <action type="fix" fixes-bug="69583" context="SS_Common">Cell copy support does not handle Time only values properly</action> + <action type="fix" fixes-bug="69681" context="SS_Common">Issue with date/time formats that leave a space before the AM/PM part</action> + <action type="add" fixes-bug="69714" context="POI_Overall">Allow custom TempFileCreationStrategy per thread</action> + </actions> + </release> + + <release version="5.4.0" date="2025-01-08"> + <summary> + <summary-item>Add support for SOURCE_DATE_EPOCH to allow to create reproducible binary files without creation/modification-timestamp being set</summary-item> + <summary-item>Breaking change: Some invalid content in the compressed file-formats for xlsx/docx/pptx/... now fail parsing to prevent handling malicious input incorrectly</summary-item> + <summary-item>Upgrade ant dependency to 1.10.15</summary-item> + <summary-item>Upgrade batik dependency to 1.18</summary-item> + <summary-item>Upgrade commons-codec dependency to 1.17.1</summary-item> + <summary-item>Upgrade commons-compress dependency to 1.27.1</summary-item> + <summary-item>Upgrade commons-io dependency to 2.18.0</summary-item> + <summary-item>Upgrade log4j-api dependency to 2.24.3 and add log4j-bom dependency</summary-item> + <summary-item>Upgrade pdfbox dependency to 3.0.3</summary-item> + <summary-item>Upgrade xmlbeans dependency to 5.3.0</summary-item> + <summary-item>Upgrade xmlsec dependency to 3.0.5</summary-item> + <summary-item>Upgrade JaCoCo code-coverage tooling to 0.8.12</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="github-653" context="HSSF">Adjust HSSFWorkbook.getSheet() to return the first case-insensitive match, similar to XSSF</action> + <action type="fix" fixes-bug="github-655" context="XWPF">Fix searching text in paragraphs when text is spread across multiple runs</action> + <action type="fix" fixes-bug="github-657" context="SXSSF">Support setting an arbitrary extra width value for column widths - not working - fixed in 69536 (5.4.1)</action> + <action type="fix" fixes-bug="github-670" context="XWPF">XWPFRun.getText should support delInstrText and noBreakHyphen</action> + <action type="fix" fixes-bug="github-672" context="XWPF">Support removing XWPF Styles</action> + <action type="fix" fixes-bug="github-673" context="OOXML">Add word10.xsd to poi-ooxml-full</action> + <action type="fix" fixes-bug="github-733" context="SS_Common">Fix issue with param order in MIRR function evaluation</action> + <action type="fix" fixes-bug="66590" context="POIFS">Number of blocks used by the property table missing from the file header</action> + <action type="fix" fixes-bug="69154" context="XSSF">Shifting columns with merged regions generates an error about overlapping regions</action> + <action type="fix" fixes-bug="69209" context="SS_Common">default ignoreMissingFontSystem to true</action> + <action type="fix" fixes-bug="69323" context="POI_Overall">DefaultTempFileCreationStrategy should worry about OS deleting the temp dir</action> + <action type="fix" fixes-bug="69411" context="XSSF">add XSSFReader.getSheetIterator</action> + <action type="fix" fixes-bug="69418" context="SS_Common">Issue when evaluating WORKDAY function that has a cell ref as 2nd param</action> + <action type="fix" fixes-bug="69620" context="OOXML">Throw exception if xlsx/docx/pptx contains duplicate file names</action> + </actions> + </release> + + <release version="5.3.0" date="2024-07-02"> + <summary> + <summary-item>Upgrade log4j-api dependency to 2.23.1</summary-item> + <summary-item>Upgrade commons-codec dependency to 1.17.0</summary-item> + <summary-item>Upgrade commons-compress dependency to 1.26.2</summary-item> + <summary-item>Upgrade commons-io dependency to 2.16.1</summary-item> + <summary-item>Upgrade pdfbox dependency to 3.0.2 and graphics2d dependency to 3.0.2</summary-item> + <summary-item>Upgrade xmlsec dependency to 3.0.4</summary-item> + <summary-item>Upgrade bouncycastle dependency to 1.79</summary-item> + <summary-item>Upgrade xmlbeans dependency to 5.2.1</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="63189" context="OOXML">Add support for hyperlink based relationships which are stored separately from other relationships</action> + <action type="fix" fixes-bug="68237" context="SXSSF">Some boolean attribute values are written as true instead of 1</action> + <action type="fix" fixes-bug="68703" context="XSLF">IllegalArgumentException: Unexpected color choice CTFontCollectionImpl when reading font color for a table cell</action> + <action type="fix" fixes-bug="68778" context="SXSSF">Fix issue in SXSSF when there are missing fonts</action> + <action type="fix" fixes-bug="68183" context="SXSSF">SXSSFWorkbook now removes temp files when closed - removing need for a separate dispose call</action> + <action type="add" fixes-bug="68987" context="OOXML">Support allowStoredEntriesWithDataDescriptor=true when reading zip data</action> + <action type="add" fixes-bug="69147" context="OOXML">Fix regression in date handling when evaluating TEXT function</action> + <action type="fix" fixes-bug="github-578" context="SXSSF">Rework exception handling for missing fonts to make it more robust</action> + <action type="fix" fixes-bug="github-601" context="XDGF">handle elliptical arcs that have colinear points</action> + <action type="add" fixes-bug="github-604" context="XDGF">Support for polylines</action> + <action type="add" fixes-bug="github-607" context="XWPF">Support SVGs in XWPF</action> + </actions> + </release> + + <release version="5.2.5" date="2023-11-25"> + <summary> + <summary-item>Upgrade commons-io dependency to 2.15.0</summary-item> + <summary-item>Upgrade commons-compress dependency to 1.25.0</summary-item> + <summary-item>Upgrade log4j-api dependency to 2.21.1</summary-item> + <summary-item>Upgrade xmlsec dependency to 3.0.3</summary-item> + <summary-item>Upgrade bouncycastle dependency to 1.77</summary-item> + <summary-item>Upgrade xmlbeans dependency to 5.2.0</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="67475" context="SS_Common">Better support for edge cases in TEXT function</action> + <action type="fix" fixes-bug="67510" context="XDDF">Fix issue where chart axes were defaulting to have blank number formats - which recent versions of Excel treat as corrupted.</action> + <action type="add" fixes-bug="67735" context="XWPF">Add Complex scripts support in XWPFRun</action> + <action type="fix" fixes-bug="67579" context="OOXML">POI 5.2.4 had a regression where it did not close user-provided InputStreams. In POI 5.2.5, user-provided InputStreams are again closed. There are new constructors that allow you to control whether the streams are closed.</action> + <action type="fix" fixes-bug="67785" context="XSSF">XSSFExcelExtractor does not format formula results like the streaming based extractor</action> + <action type="fix" fixes-bug="68094" context="XSSF">Improve cell width logic to avoid rounding issues</action> + <action type="fix" fixes-bug="github-505" context="SL_Common">DrawTextFragment height should include leading space</action> + </actions> + </release> + + <release version="5.2.4" date="2023-09-28"> + <summary> + <summary-item>Discontinued the binary packages to reduce maintenance overhead, please rebuild the sources locally or use Maven Central for binary files</summary-item> + <summary-item>Upgrade log4j-api dependency to 2.20.0</summary-item> + <summary-item>Upgrade xmlsec dependency to 3.0.2</summary-item> + <summary-item>Upgrade batik dependency to 1.17</summary-item> + <summary-item>Upgrade pdfbox dependency to 2.0.29, graphics2d to 0.43</summary-item> + <summary-item>Upgrade commons-codec dependency to 1.16.0</summary-item> + <summary-item>Upgrade commons-compress dependency to 1.24.0</summary-item> + <summary-item>Upgrade commons-io dependency to 2.13.0</summary-item> + <summary-item>Upgrade curvesapi dependency to 1.08</summary-item> + <summary-item>Upgrade SparseBitSet dependency to 1.3</summary-item> + <summary-item>Use jdk18on versions of bouncycastle jars (v1.76)</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="66598" context="XSSF">Fix invalid loop-condition when cleaning up CTCells</action> + <action type="fix" fixes-bug="47950" context="POI_Overall">make stream/directory name lookup in OLE2 case insensitive</action> + <action type="fix" fixes-bug="66521" context="POI_Overall">Provide a utility to clear all thread-locals to avoid reports of memory-leaks in web-application containers</action> + <action type="fix" fixes-bug="66436" context="POI_Overall">Fix handling padding when decrypting data</action> + <action type="fix" fixes-bug="54373" context="XSSF">Include alpha/transparency value when creating an XSSFColor from an AWT Color object</action> + <action type="fix" fixes-bug="62272" context="XSSF">Include alpha/transparency value when setting a color-value for a font</action> + <action type="fix" fixes-bug="65260" context="SXSSF">Fix graceful handling of missing font-system on the operating system</action> + <action type="fix" fixes-bug="65543" context="HSSF">Incomplete Shared String Tables were causing read failures</action> + <action type="fix" fixes-bug="66257" context="XSSF">NullPointerException in XSSFReader$SheetIterator.next()</action> + <action type="fix" fixes-bug="66278" context="XSLF">Multiple gradient stops at the exact same location causing a rendering failure</action> + <action type="add" fixes-bug="66301" context="HSMF">Add a method to properly write the header necessary for a MSG attachment</action> + <action type="fix" fixes-bug="66306" context="XSLF">Make XSLFDiagramGroupShape public</action> + <action type="fix" fixes-bug="66312" context="XWPF">Inserting paragraph into table from cursor</action> + <action type="add" fixes-bug="66347" context="XWPF">Add theme support to XWPF</action> + <action type="fix" fixes-bug="66365" context="XSSF">Fix issue where cells with formulas and cached results of string type do not properly support shared strings</action> + <action type="fix" fixes-bug="66399" context="XSLF">Text run highlight colors were ignored</action> + <action type="fix" fixes-bug="66401" context="SS_Common">Fix parsing formulas with sheet-names which contain single quotes</action> + <action type="fix" fixes-bug="66418" context="XSSF">Fix performance issue with XSSFSheet.groupRow</action> + <action type="fix" fixes-bug="66433" context="SS_Common">Improve boolean functions empty cell handling</action> + <action type="fix" fixes-bug="66473" context="SXSSF">Fix performance issue with SXSSFCell.getColumnIndex()</action> + <action type="fix" fixes-bug="66475" context="POI_Overall">SignatureConfig: remove ThreadLocals and deprecated code associated with them</action> + <action type="fix" fixes-bug="66514" context="POI_Overall">Remove support for zip/tgz release artifacts</action> + <action type="fix" fixes-bug="66532" context="SXSSF">Improve performance of SheetDataWriter outputEscapedString</action> + <action type="fix" fixes-bug="66584" context="OOXML">Ensure ZipPackage closes input stream when exceptions happen</action> + <action type="fix" fixes-bug="66614" context="SS_Common">Issue where OFFSET function applies limits that should only apply to xls format spreadsheets</action> + <action type="fix" fixes-bug="66644" context="POI_Overall">Make jar build reproducible</action> + <action type="fix" fixes-bug="66661" context="XSSF">Fix issue with adding table formulas</action> + <action type="fix" fixes-bug="66988" context="XWPF">XWPFTableCell: make setText fully replace the text and add appendText method to append</action> + <action type="fix" fixes-bug="67005" context="XSLF">Basic for reading audio files in pptx files</action> + <action type="fix" fixes-bug="67396" context="OOXML">Set standalone="yes" in XML declarations when writing OOXML format files</action> + </actions> + </release> + + <release version="5.2.3" date="2022-09-16"> + <summary> + <summary-item>Upgrade graphics2d dependency to 0.40, pdfbox to 2.0.26</summary-item> + <summary-item>Upgrade xmlsec dependency to 3.0.0</summary-item> + <summary-item>Upgrade xmlbeans dependency to 5.1.1</summary-item> + <summary-item>Upgrade log4j-api dependency to 2.18.0</summary-item> + <summary-item>Speed up processing of formulas with column-ranges, e.g. VLOOKUP(A4,$D:$E,2,0)</summary-item> + <summary-item>Speed up compilation of jar-files-only builds by avoiding direct dependency on test-execution</summary-item> + <summary-item>Avoid some more possible overly large memory allocations on certain input documents</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="51037" context="SS_Common">setDefaultColumnStyle() in XSSFSheet/SXSSFSheet was not working as expected</action> + <action type="add" fixes-bug="55330" context="SS_Common">add PageMargin enum</action> + <action type="add" fixes-bug="56155" context="OOXML">Support version property in CoreProperties</action> + <action type="add" fixes-bug="58468" context="SS_Common">Support DAYS function</action> + <action type="fix" fixes-bug="63575" context="XWPF">Support capitalized text in XWPFWordExtractor</action> + <action type="fix" fixes-bug="63576" context="HWPF">Support capitalized text in WordExtractor</action> + <action type="fix" fixes-bug="65562" context="SXSSF">SXSSF doesn't update dimension field</action> + <action type="fix" fixes-bug="65473" context="XSLF">When slides were copied, the text shapes were still referencing original slide</action> + <action type="fix" fixes-bug="65854" context="OOXML">Use revert() instead of close() when OPCPackage is opened read-only</action> + <action type="fix" fixes-bug="65973" context="XSSF">Row shifting does not properly handle hyperlinks that span multiple cells</action> + <action type="fix" fixes-bug="65988" context="SS_Common">RATE function fails in some cases</action> + <action type="fix" fixes-bug="65993" context="XSSF">change XSSFHyperlink code that copies HSSFWorkbook to respect cell ranges</action> + <action type="fix" fixes-bug="66022" context="SS_Common">Fix issue with parsing formulas that have sheet names containing certain chars</action> + <action type="fix" fixes-bug="66047" context="SS_Common">Fix rounding issue in MROUND function</action> + <action type="fix" fixes-bug="66079" context="XWPF">Fix bug where XWPFNumbering.removeAbstractNum removes by list index, not abstractNumId</action> + <action type="fix" fixes-bug="github-321" context="SS_Common">DataFormatter issue with rounding in some use cases</action> + <action type="add" fixes-bug="github-330" context="SS_Common">Support AVERAGEIF function</action> + <action type="fix" fixes-bug="66052" context="SS_Common">XSSFColor could not be used the same time as org.apache.poi.ss.util classes</action> + <action type="add" fixes-bug="66083" context="SS_Common">Support CEILING.MATH and FLOOR.MATH functions</action> + <action type="fix" fixes-bug="66087" context="SS_Common">support case insensitive matching in D* functions</action> + <action type="add" fixes-bug="66090" context="SS_Common">add support for DCOUNT, DCOUNTA, DAVERAGE, DSTDEV, DSTDEVP, DVAR, DVARP and DPRODUCT functions</action> + <action type="add" fixes-bug="66092" context="SS_Common">Add STDEVP, STDEVA, STDEVPA, VARA and VARPA functions</action> + <action type="add" fixes-bug="66093" context="SS_Common">add support for unimplemented subfunctions to SUBTOTAL function</action> + <action type="add" fixes-bug="66094" context="SS_Common">add support for STDEV.S, STDEV.P, VAR.S and VAR.P functions</action> + <action type="add" fixes-bug="66095" context="SS_Common">add support for POISSON.DIST function</action> + <action type="add" fixes-bug="66097" context="SS_Common">Support CEILING.PRECISE and FLOOR.PRECISE functions</action> + <action type="add" fixes-bug="66098" context="SS_Common">D* functions should support wildcard matches</action> + <action type="add" fixes-bug="66105" context="SS_Common">Support excel correl, covar, pearson and forecast functions</action> + <action type="fix" fixes-bug="66115" context="HSSF">Some Password protected XLS files are not read</action> + <action type="add" fixes-bug="66123" context="XSSF">Support the gte attribute with XSSFConditionalFormattingThreshold</action> + <action type="add" fixes-bug="66145" context="OOXML">generate poi-ooxml-full classes for dml-drawing xsd</action> + <action type="add" fixes-bug="66146" context="OOXML">generate poi-ooxml-full classes for threaded comment and word12 xsds</action> + <action type="fix" fixes-bug="66173" context="SS_Common">add Sheet createSplitPane(int xSplitPos, int ySplitPos, int leftmostColumn, int topRow, PaneType activePane) to eventually replace the existing createSplitPane method (that has a bug in XSSFSheet)</action> + <action type="fix" fixes-bug="github-360" context="HSSF">HSSFExtendedColor was not setting RGB colors properly</action> + <action type="add" fixes-bug="66176" context="XSLF">Integrate SmartArt diagrams from powerpoint presentations</action> + <action type="fix" fixes-bug="66181" context="SS_Common">POI's implementation of VALUE function did not properly handle empty string input</action> + <action type="fix" fixes-bug="66187" context="XWPF">Calling getTextHighlightColor() or getEmphasisMark() on XWPFRun can lead to corruption of file</action> + <action type="fix" fixes-bug="66211" context="XSSF">XSSFTable.updateHeaders did not work for Worksheets created using current Excel versions</action> + <action type="fix" fixes-bug="66212" context="XSSF">XSSFSheet.removeTable did not remove the links to the table part reference from the sheet</action> + <action type="fix" fixes-bug="66213" context="XSSF">XSSFWorkbook.cloneSheet does not clone XSSFTables linked from the sheet</action> + <action type="fix" fixes-bug="66215" context="XSSF">Shifting rows or columns can damage formulas in tables</action> + <action type="fix" fixes-bug="66216" context="XSSF">XSSFPivotTable.getPivotCacheDefinition() does not work properly when XSSFPivotTable was read from an existing *.xlsx file</action> + <action type="fix" fixes-bug="66230" context="SXSSF">SXSSFWorkbook should work even when fonts not installed on OS</action> + <action type="fix" fixes-bug="66242" context="XSLF">Issue with orphaned (in package) images and notes post slide removal</action> + </actions> + </release> + + <release version="5.2.2" date="2022-03-19"> + <summary> + <summary-item>Upgrade log4j-api dependency to 2.17.2 and graphics2d dependency to 0.35 as well as some test dependencies</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="65915" context="SS_Common">Fix issue where Boolean functions (AND, OR) do not work properly in array context</action> + <action type="add" fixes-bug="65934" context="XSLF">add removeTextParagraph to text box API</action> + <action type="add" fixes-bug="65935" context="XSLF">add removeTextRun to paragraph API</action> + <action type="fix" fixes-bug="65939" context="XSSF">Fix stackoverflow issue when removing formulas with circular references</action> + <action type="add" fixes-bug="65943" context="SXSSF">Support rich text strings in SXSSFWorkbook (only when shared string table is used)</action> + <action type="fix" fixes-bug="65946" context="OOXML">POIXMLPropertiesTextExtractor returns duplicate key for Core properties</action> + <action type="fix" fixes-bug="65950" context="POI_Overall">POI 5.2.1 can allocate byte arrays that are too big</action> + </actions> + </release> + + <release version="5.2.1" date="2022-03-03"> + <summary> + <summary-item>Upgrade curvesapi dependency to 1.07</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="65887" context="POI_Overall">IOUtils.toByteArray did not fully take into account value set by IOUtils.setByteArrayMaxOverride</action> + <action type="fix" fixes-bug="60541" context="SS_Common">Collapsing a column group was incorrectly implemented</action> + <action type="fix" fixes-bug="62857" context="SS_Common">DOLLAR function is not properly implemented</action> + <action type="fix" fixes-bug="65792" context="SS_Common">Multiplication in cell formulas can have small rounding issues</action> + <action type="fix" fixes-bug="65839" context="SS_Common">Picture resize can lead to infinite loop</action> + <action type="add" fixes-bug="65846" context="SS_Common">Add support for NUMBERVALUE function</action> + <action type="add" fixes-bug="65850" context="SS_Common">Add support for Normal Distribution functions</action> + <action type="add" fixes-bug="65870" context="SS_Common">Add support for BESSELJ function</action> + <action type="add" fixes-bug="65871" context="SS_Common">Add support for DOLLARDE and DOLLARFR functions</action> + <action type="add" fixes-bug="65879" context="SS_Common">Add support for WORKDAY.INTL functions</action> + <action type="fix" fixes-bug="65899" context="HMEF">Fix issue where malformed TNEF file can cause memory issues</action> + <action type="fix" fixes-bug="65908" context="OPC">XAdES-XL modifications due to specification check errors</action> + </actions> + </release> + + <release version="5.2.0" date="2022-01-14"> + <summary> + <summary-item>Refactor to XSSFReader, SharedStringsTable, CommentsTable and ThemesTable to make them more extensible</summary-item> + <summary-item>Upgrade log4j-api dependency to 2.17.1</summary-item> + <summary-item>Upgrade BouncyCastle dependency to 1.70</summary-item> + <summary-item>Upgrade PDFBox Graphics2d dependency to 0.34 and PDFBox dependency to 2.0.25</summary-item> + </summary> + <actions> + <action type="add" fixes-bug="65668" context="OOXML">upgrade to xmlsec 2.3.0 - make secure validation configurable</action> + <action type="add" fixes-bug="65672" context="OOXML">Digital Signature - set commitment type and purpose</action> + <action type="fix" fixes-bug="65676" context="XSSF">Issue in XSSFReader where string builder is not always cleared between cell reads</action> + <action type="add" fixes-bug="65694" context="HSLF">handle date/time fields and formats</action> + <action type="fix" fixes-bug="github-281" context="SS_Common">Cell Conditional Formatting: Change regex to account for decimals with no leading digit</action> + <action type="fix" fixes-bug="github-273" context="SS_Common">Log warning when long sheet names are trimmed</action> + <action type="add" fixes-bug="github-243" context="SS_Common">Add support for XLOOKUP and XMATCH functions</action> + <action type="add" fixes-bug="github-290" context="POI_Overall">Customize Spliterator implementations for better parallelism</action> + <action type="fix" fixes-bug="63211" context="SS_Common">DataFormatter incorrectly formats data formats with escaped percent character</action> + <action type="fix" fixes-bug="64732" context="XSSF">XSSFSheet.createTable generates corrupted file when a header's cell contains a line break</action> + <action type="fix" fixes-bug="65701" context="OOXML">Password Protecting a document when Saxon is on classpath can corrupt the output</action> + <action type="add" fixes-bug="65703" context="SS_Common">DataFormatter: add setUse4DigitYearsInAllDateFormats(boolean) method with default of false</action> + <action type="add" fixes-bug="65730" context="SS_Common">DataFormatter: add setUseCachedValuesForFormulaCells(boolean) method with default of false</action> + <action type="fix" fixes-bug="65715" context="OOXML">Fix issue in XSSFSheet getDrawingPatriarch</action> + <action type="fix" fixes-bug="65738" context="OOXML">Fix issue with excessive logging of invalid parts in OOXML files</action> + <action type="fix" fixes-bug="65766" context="SS_Common">Cell copy does not respect rich text</action> + <action type="fix" fixes-bug="65772" context="POI_Overall">stop using file deleteOnExit in DefaultTempFileCreationStrategy</action> + </actions> + </release> + + <release version="5.1.0" date="2021-11-01"> + <summary> + <summary-item>XDDF - bug fixes</summary-item> + <summary-item>Upgrade Batik dependency to 1.14</summary-item> + <summary-item>Upgrade BouncyCastle dependency to 1.69 (including adding dependency on bcutil jar)</summary-item> + <summary-item>Upgrade Commons-Compress dependency to 1.21</summary-item> + <summary-item>Upgrade XMLSec dependency to 2.2.3</summary-item> + <summary-item>Upgrade PDFBox Graphics2d dependency to 0.33 (and test with PDFBox 2.0.24)</summary-item> + <summary-item>Add commons-io 2.11.0 as a dependency</summary-item> + <summary-item>Upgrade XMLBeans to 5.0.2</summary-item> + <summary-item>Internal logging in POI now uses Apache Log4J 2</summary-item> + <summary-item>Small refactor to XSSFReader to make it more extensible - should not affect most users unless they subclass XSSFReader</summary-item> + <summary-item>By default, no DTDs will be accepted in XML files. This can be relaxed by setting POIXMLTypeLoader.DEFAULT_XML_OPTIONS.setDisallowDocTypeDeclaration(false).</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="github-221" context="XSLF">XSLFTable - revert addRow to behaviour before 4.1.2</action> + <action type="fix" fixes-bug="65016" context="XDDF">Don't throw exception on empty data source</action> + <action type="fix" fixes-bug="64950" context="XDDF">Set hole size for doughnut chart</action> + <action type="fix" fixes-bug="63901" context="XSSF">XSSFDrawing - import chart from other drawing</action> + <action type="fix" fixes-bug="63902" context="XSSF">XSSFWorkbook - reference cloned sheet in cloned chart data</action> + <action type="fix" fixes-bug="54470" context="XSSF">XSSFWorkbook - clone sheet with chart</action> + <action type="fix" fixes-bug="57835" context="XSLF">XSLFSlide - import slide notes when importing slide content</action> + <action type="add" fixes-bug="github-228" context="XDDF">Manipulate individual data point properties</action> + <action type="add" fixes-bug="65192" context="HSSF">Allow change of EncryptionMode</action> + <action type="add" fixes-bug="65206" context="POI_Overall">Migrate ant / maven to gradle build</action> + <action type="fix" fixes-bug="65228" context="XSLF">the method getCap() does not work correctly in xslf.usermodel.XSLFTextRun</action> + <action type="fix" fixes-bug="65214" context="OOXML">Document signed by POI reported as 'partially' signed</action> + <action type="fix" fixes-bug="65085" context="HSLF">LineRect shall throw more specific exceptions</action> + <action type="fix" fixes-bug="64844" context="SL_Common">Incorrect sizes of images in SVG</action> + <action type="add" fixes-bug="65304" context="POI_Overall">Add commons-io as a dependency</action> + <action type="fix" fixes-bug="64473" context="OOXML">Handle issue where OOXML file has metadata and metadata.xml</action> + <action type="add" fixes-bug="60924" context="SS_Common">Support IFS and SWITCH functions</action> + <action type="add" fixes-bug="64633" context="SS_Common">Support TEXTJOIN function</action> + <action type="fix" fixes-bug="65230" context="SS_Common">TRIM function should trim extra spaces between words</action> + <action type="fix" fixes-bug="65464" context="XSSF">Fix issue with removing parent formula when shared formulas are used</action> + <action type="add" fixes-bug="65467" context="SS_Common">Support IFNA function</action> + <action type="fix" fixes-bug="65471" context="XSSF">Add support for T literal in DateTime formats</action> + <action type="fix" fixes-bug="65475" context="SS_Common">SUMIF and SUMIFS functions do not properly handle #N/A values</action> + <action type="fix" fixes-bug="github-242" context="SS_Common">add support for MAXIFS, MINIFS, AVERAGEIFS functions</action> + <action type="fix" fixes-bug="65501" context="XSLF">Use viewbox when rendering SVG images</action> + <action type="add" fixes-bug="65581" context="OOXML">add optional support in ZipArchiveFakeEntry to use a temp file</action> + <action type="fix" fixes-bug="65595" context="SS_Common">Strip color formatting in headers and footers</action> + <action type="fix" fixes-bug="65606" context="SS_Common">Fix issues with WEEKNUM function evaluation</action> + <action type="fix" fixes-bug="65612" context="XSLF">XSLF CustomGeometry - replace XmlStreamReader access with XmlBeans delegate</action> + <action type="fix" fixes-bug="49202" context="SS_Common">Support PERCENTRANK and related functions</action> + <action type="fix" fixes-bug="64258" context="SS_Common">Support TDIST and related functions</action> + <action type="fix" fixes-bug="65490" context="XSSF">Better support for shared hyperlinks</action> + <action type="fix" fixes-bug="65042" context="OPC">Add support to ZipPackage to allow temp files to be used to save memory (useful for writing xlsx/pptx/docx files with pictures, etc.).</action> + <action type="fix" fixes-bug="65372" context="OPC">Allow ZipSecureFile.setMaxEntrySize to accept sizes above 4Gb</action> + <action type="fix" fixes-bug="65331" context="XWPF">Fix issue in XWPFTable.setTableAlignment(TableRowAlign tra)</action> + <action type="fix" fixes-bug="65623" context="OPC">Create XAdES-T signature with XAdESXLSignatureFacet</action> + <action type="fix" fixes-bug="62040" context="SS_Common">QUOTIENT function does not support cell references</action> + <action type="fix" fixes-bug="64542" context="OPC">Allow creation of POIFSFileSystem instances from FileChannels but with an optional flag to prevent POI from closing the channel</action> + <action type="fix" fixes-bug="65452" context="SS_Common">WorkbookFactory.create(File, ...) should throw exception if the input file is not in a supported format</action> + <action type="fix" fixes-bug="65551" context="XSLF">Incorrect fetching paragraph and text runs props from master shape</action> + <action type="fix" fixes-bug="65634" context="XSLF">SlideShowFactory.create(File, ...) should throw exception if the input file is not in a supported format</action> + <action type="fix" fixes-bug="65648" context="SXSSF">Remove finalizer on SXSSF SheetDataWriter</action> + <action type="fix" fixes-bug="65650" context="POI_Overall">Use image/x-pict as mime type for pict format pictures (previous versions used a mix of image/pict and image/x-pict)</action> + <action type="fix" fixes-bug="65653" context="HSLF">HSLF FillType for texture and background color fills ignored</action> + </actions> + </release> + + <release version="5.0.0" date="2021-01-20"> + <summary> + <summary-item>Upgrade to ECMA-376 5th edition (transitional) schemas - expect API breaks when using XmlBeans directly<br/> + some smaller changes are necessary when code is using the low-level CT... classes </summary-item> + <summary-item>Change artifact names of poi-/ooxml-schemas to poi-ooxml-lite/full</summary-item> + <summary-item>ooxml-security is part of poi-ooxml-full (known as ooxml-schemas) now and won't be provided separately</summary-item> + <summary-item>updated dependencies to XMLSec 2.2.1, Bouncycastle 1.68, Commons-Codec 1.15, Commons-Compress 1.20</summary-item> + <summary-item>XWPF - improvements in table and paragraph</summary-item> + <summary-item>XSLF - improvements for paragraph</summary-item> + <summary-item>provide JigSaw modules - some classes moved between packages for the JDK 9+ support, e.g. + ExtractorFactory, so imports need to be adjusted</summary-item> + <summary-item>removed dependencies to jaxb</summary-item> + <summary-item>removed deprecated code</summary-item> + <summary-item>new experimental DeferredSXSSFWorkbook which creates fewer temp files by lazily generating rows (see DeferredGeneration in poi-examples)</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="64494" context="XSSF">Ensure "applyAlignment" in cell-styles is enabled when necessary</action> + <action type="fix" fixes-bug="64450" context="OOXML">Allow to parse a file where the relationship-id is an empty string</action> + <action type="fix" fixes-bug="64750" context="XSSF">Do not use CTDataValidations.getCount(), instead only rely on getDataValidationArray</action> + <action type="fix" fixes-bug="64986" context="SS_Common">Support missing or blank match_type for function Match</action> + <action type="fix" fixes-bug="64838" context="XWPF">Do not populate cells with a paragraph when loading an existing document</action> + <action type="fix" fixes-bug="65009" context="HSLF">Use correct index for 1-based pictures</action> + <action type="fix" fixes-bug="64460" context="XSSF">Fix invalid moving of merged regions</action> + <action type="fix" fixes-bug="64791" context="HSSF">Use proper position for the WriteAccessRecord</action> + <action type="fix" fixes-bug="64238" context="SS_Common">Make LOOKUP functions deal with empty last arg correctly</action> + <action type="fix" fixes-bug="64322" context="POIFS">Improve performance of reading OLE2 files</action> + <action type="add" fixes-bug="64393" context="SS_Common">Handle MissingArgEval in relational operators</action> + <action type="add" fixes-bug="64420" context="XSSF">Avoid NullPointerException in XSSFReader.SheetIterator.next() if files contain macros</action> + <action type="add" fixes-bug="github-177" context="SS_Common">Avoid NullPointerException if RangeCopier encounters empty/missing rows</action> + <action type="add" fixes-bug="63294" context="SS_Common">Add some more methods to allow to use CellType everywhere</action> + <action type="fix" context="XSSF">Fix regression introduced via Bug 60845: There are more items in CTBorder that need to be handled in equals()</action> + <action type="fix" fixes-bug="63845" context="XWPF">Adjust handling of formula-cells to fix regression with missing re-calculation introduced in 4.1.0</action> + <action type="fix" fixes-bug="55966" context="XWPF">Include content control text in word extraction also if it is part of a paragraph</action> + <action type="fix" fixes-bug="64244" context="XSSF">Take the replacement of RichText strings into account when computing length of strings</action> + <action type="add" context="SS_Common">SS method to check if a Named Range is hidden or not</action> + <action type="add" context="SS_Common">SS method to check if a Named Range is hidden or not</action> + <action type="add" fixes-bug="github-167" context="HSMF">HSMF enhancements - NamedIdChunk, MultiValueChunks, ByteChunkDeferred</action> + <action type="fix" context="SS_Common">Fix incorrect handling of format which should not produce any digit for zero</action> + <action type="fix" fixes-bug="58896,52834" context="SS_Common">Speed up auto-sizing of columns when the sheet contains merged regions</action> + <action type="fix" fixes-bug="64186" context="OPC">Decrease usage of ThreadLocals in XML Signature API</action> + <action type="fix" fixes-bug="64213" context="SS_Common">Picture.resize(double scale) scales width wrong for small pictures and when dx1 is set</action> + <action type="fix" fixes-bug="63712" context="OPC">upgrading xmlsec causes junit tests to fail</action> + <action type="fix" fixes-bug="64241" context="XSLF">XSLF - Wrong scheme colors used when rendering</action> + <action type="fix" fixes-bug="63624" context="XWPF">Method setText in XWPFTableCell updates the xml and also updates the runs and iruns</action> + <action type="fix" fixes-bug="github-170" context="XWPF">XWPFTableCell does not process bodyElements when handle paragraph</action> + <action type="fix" fixes-bug="github-171" context="XWPF">XWPFNumbering.addAbstractNum will definitely throw an exception</action> + <action type="fix" fixes-bug="64301" context="OPC">Allow try-with-resources with OPCPackage.revert()</action> + <action type="fix" fixes-bug="63745" context="HSSF">Add traversing and debugging interface to HSSF</action> + <action type="fix" fixes-bug="64350" context="POI_Overall">Sonar fix - "Iterator.next()" methods should throw "NoSuchElementException"</action> + <action type="fix" fixes-bug="57843" context="HWPF">RuntimeException on extracting text from Word 97-2004 Document</action> + <action type="fix" fixes-bug="55505" context="HSSF">CountryRecord not found</action> + <action type="fix" fixes-bug="64387" context="POIFS">Big POIFS stream result in OOM</action> + <action type="add" fixes-bug="64411" context="POI_Overall" breaks-compatibility="true">Provide JigSaw modules</action> + <action type="fix" fixes-bug="64441" context="SS_Common">Synchronize code that initialises WorkbookFactory</action> + <action type="add" fixes-bug="63819" context="SS_Common">Support DateValue function</action> + <action type="add" fixes-bug="github-179" context="SS_Common">Add an option for RangeCopier.copyRange() also clone styles</action> + <action type="fix" fixes-bug="63290" context="XSLF">Retrieve default run properties from paragraph</action> + <action type="add" fixes-bug="64512" context="POIFS">Ole10Native aka embedded / object packager - handle UTF16 variants</action> + <action type="fix" fixes-bug="64561" context="XWPF">XWPFSDTContent.getText() is empty for nested SDT elements</action> + <action type="fix" fixes-bug="64595" context="SXSSF">Missing quoting of pre-evaluated string values in formula cells causes corrupt files</action> + <action type="fix" fixes-bug="64693" context="HEMF">POI HwmfGraphics cannot read the embedded document title</action> + <action type="fix" fixes-bug="64716" context="HWMF">WMF font typeface charset encoding error</action> + <action type="fix" fixes-bug="64773" context="POI_Overall">Visual signatures for .xlsx/.docx</action> + <action type="fix" fixes-bug="64817" context="POIFS">Fix issue in testXLSXinPPT</action> + <action type="fix" fixes-bug="github-193" context="SS_Common">Change TRUNC implementation to use MathX</action> + <action type="add" fixes-bug="64867" context="SL_Common">Provide PDF rendering with PPTX2PNG</action> + <action type="fix" fixes-bug="64964" context="SS_Common">Converting cell values to boolean should throw IllegalStateException instead of RuntimeException when conversion is not possible</action> + <action type="fix" fixes-bug="64971" context="XSSF">XSSFFont setCharset(FontCharset) should use latest class instead of deprecated one</action> + <action type="fix" fixes-bug="60397" context="XSSF">Improve performance of cell merge</action> + <action type="fix" fixes-bug="github-206" context="SXSSF">Improve performance of SXSSF cell evaluation</action> + <action type="fix" fixes-bug="64976" context="SS_Common">Change some methods to return ints instead of shorts (Font and CellStyle)</action> + <action type="fix" fixes-bug="56205" context="OOXML" breaks-compatibility="true">Upgrade OOXML schema to 3rd edition (transitional)</action> + <action type="fix" fixes-bug="64979" context="OOXML">Change artifact names of poi-/ooxml-schemas</action> + <action type="fix" fixes-bug="64981" context="OOXML" breaks-compatibility="true">Upgrade OOXML schema to 5th edition (transitional)</action> + <action type="fix" fixes-bug="64876" context="XSLF">Unable to convert pptx to pdf</action> + <action type="fix" fixes-bug="65026" context="POI_Overall">Migrate tests to Junit 5</action> + <action type="add" fixes-bug="github-207" context="POI_Overall">Use SLF4J instead of commons-logging - use jcl-over-slf4j</action> + <action type="fix" fixes-bug="65061" context="XSSF">Handle VmlDrawings containing spreadsheet-ml default namespace</action> + <action type="fix" fixes-bug="65063" context="HSLF">WMF parsing failed on closed empty polygon</action> + <action type="fix" fixes-bug="github-198" context="POI_Overall">Remove jdk.charset module dependency for spreadsheets generation</action> + <action type="fix" fixes-bug="github-196" context="OOXML">Delete unused certificate exceptions</action> + <action type="fix" fixes-bug="github-191" context="SS_Common">Fix RuntimeException on array formula referencing blank cell</action> + <action type="fix" fixes-bug="github-189" context="SS_Common">Move date parsing logic to DateParser</action> + <action type="fix" fixes-bug="github-187" context="XSSF">Add length validation for Excel DataValidations that are list literals</action> + <action type="fix" fixes-bug="github-184" context="SXSSF">New EmittingSXSSFWorkbook</action> + <action type="fix" fixes-bug="github-176" context="XSSF">Remove limit on number of rules in XSSFSheetConditionalFormatting</action> + <action type="fix" fixes-bug="github-177" context="HSSF">Avoid NullPointerException if RangeCopier encounters empty/missing rows</action> + </actions> + </release> + + <release version="4.1.2" date="2020-02-17"> + <summary> + <summary-item>Removed a lot of internal uses of StringBuffers</summary-item> + <summary-item>XDDF - some work on better chart support</summary-item> + <summary-item>Common SL / EMF - ongoing rendering fixes</summary-item> + <summary-item>XSLF - OOM fixes when parsing arbitrary shape ids + a new dependency to SparseBitSet 1.2</summary-item> + <summary-item>updated dependencies to Bouncycastle 1.64</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="64015" context="POI_Overall">Swap zaxxer.com:SparseBitSet for java.util.BitSet</action> + <action type="fix" fixes-bug="63788" context="XWPF">When removing AbstractNum match by abstractNumId, not list index</action> + <action type="fix" fixes-bug="63940" context="POI_Overall">Avoid endless loop/out of memory on string-replace with empty search string</action> + <action type="fix" fixes-bug="63700" context="POI_Overall">Make D* functions work with numeric result column</action> + <action type="fix" fixes-bug="63960" context="SXSSF">Write pre-evaluated string-values in formula cells with the correct type</action> + <action type="fix" fixes-bug="63984" context="POI_Overall">Function AND / OR should treat missing parameters as FALSE</action> + <action type="fix" fixes-bug="63749" context="POI_Overall">Make getFirstRowNum() and getFirstCellNum() return -1 consistently with empty data</action> + <action type="fix" fixes-bug="63569" context="POI_Overall">Make IOUtils.setByteArrayMaxOverride() work correctly</action> + <action type="add" context="XSLF">Add, insert and remove columns on XSLFTable</action> + <action type="fix" fixes-bug="63842" context="POI_Overall">Fix issue with fractions where the whole number part is too large to store as an int</action> + <action type="fix" fixes-bug="63889" context="XDDF">Produce valid PPTX file with several chart series</action> + <action type="fix" fixes-bug="63918" context="SL_Common XSLF">Fix texture fill - scale stretched images correctly</action> + <action type="add" context="XDDF">Add Doughnut chart data series support</action> + <action type="fix" fixes-bug="63955" context="HMEF">HMEFContentsExtractor fails to extract content from winmail.dat</action> + <action type="fix" fixes-bug="63927" context="POI_Overall">Inconsistent mapping of Norwegian locales for date formats</action> + <action type="fix" fixes-bug="github-163" context="XSSF">Add set level numbering on XWPFParagraph</action> + <action type="fix" fixes-bug="github-164" context="XSSF">Fix Bug in XSSFTable.setCellReferences when table is single cell</action> + <action type="fix" fixes-bug="64004" context="POI_Overall">Replace Cloneable / clone() with copy constructor</action> + <action type="fix" fixes-bug="64036" context="POI_Overall">Replace reflection calls in factories for Java 9+</action> + <action type="fix" fixes-bug="64044" context="POI_Overall">Fix issue with setCellValue(LocalDate) not supporting nulls properly</action> + <action type="fix" fixes-bug="64088" context="SL_Common XSLF">SlideShow rendering fixes</action> + <action type="fix" fixes-bug="64098" context="XWPF">XWPFRun: Whitespace in text not preserved if starting with tab character.</action> + <action type="fix" fixes-bug="64108" context="POI_Overall">unsafe pipe character ("|") in Relationship target attribute is not being encoded into a '%7C'.</action> + <action type="fix" fixes-bug="github-166" context="XDDF">Expose invert if negative on bar charts</action> + <action type="fix" fixes-bug="63998" context="HSSF">Support commas, exclamation marks correctly in AreaReference</action> + <action type="fix" fixes-bug="64045" context="XSSF">XSSFWorkbook constructor doesn't close ZipFile if an exception occurs</action> + <action type="fix" fixes-bug="64130" context="HSSF">Regression in OldSheetRecord</action> + </actions> + </release> + + <release version="4.1.1" date="2019-10-20"> + <summary> + <summary-item>XSSF: Memory improvements which use much less memory while writing large xlsx files</summary-item> + <summary-item>XDDF: Improved chart support: more types and some API changes around angles and width units</summary-item> + <summary-item>updated dependencies to Bouncycastle 1.62, Commons-Codec 1.13, Commons-Collections4 4.4, Commons-Compress 1.19</summary-item> + <summary-item>XWPF: Additional API methods</summary-item> + <summary-item>XSSF: Fixes to XSSFSheet.addMergedRegion() and XSSFRow.shiftRows()</summary-item> + <summary-item>EMF/HSLF: Rendering fixes</summary-item> + <summary-item>CVE-2019-12415 - XML External Entity (XXE) Processing in Apache POI</summary-item> + </summary> + <actions> + <action type="add" fixes-bug="63774" context="POI_Overall">Cache pids to speed up custom properties "add" method</action> + <action type="add" fixes-bug="63779" context="SS_Common">Add support for the new Java date/time API added in Java 8</action> + <action type="fix" fixes-bug="59322" context="HWPF">Avoid NullPointerException when reading Word Document with tables and a cell with a null descriptor</action> + <action type="fix" fixes-bug="61490" context="HWPF">Read cells of tables correctly in cases where the last cell is not 'fake'</action> + <action type="fix" context="HWPF">Do not use WeakReference for parents in Ranges to avoid spurious failures in tests</action> + <action type="fix" fixes-bug="63657" context="XSSF">Fix regression with memory usage in XSSFRow.onDocumentWrite and some other temporary memory leaks</action> + <action type="fix" fixes-bug="63842" context="SS_Common">FractionFormat casts whole part of the value into 'int'</action> + <action type="fix" fixes-bug="63818" context="HSLF">Allow multiple charsets for same font typeface</action> + <action type="fix" fixes-bug="63768" context="XSSF">XSSFExportToXml adjust settings on SchemaFactory</action> + <action type="fix" fixes-bug="63541" context="XSLF">NullPointerException from XSLFSimpleShape.getAnchor for empty xfrm tags</action> + <action type="add" fixes-bug="63745" context="POI_Overall">Add traversing and debugging interface</action> + <action type="fix" fixes-bug="57423,62711" context="XSSF">Fix regression when XSSFRow.shiftRows() is used</action> + <action type="fix" fixes-bug="63580" context="SL_Common HSLF XSLF">Fix texture paint handling</action> + <action type="fix" fixes-bug="59004" context="HSLF">HSLF rendering - adjust values for presetShapeDefinition differs in HSLF/XSLF</action> + <action type="fix" context="HSLF">Don't fallback to master shape properties, if master shape is not assigned</action> + <action type="add" context="POI_Overall">Add a ThreadLocalUtil.clearAllThreadLocals which can be used to clear thread-locals</action> + <action type="fix" fixes-bug="63371" context="XSSF">XSSFSheet.addMergedRegion should adjust count of merged cells</action> + <action type="fix" fixes-bug="63073" context="XSSF">Return value of XSSFSheet.addMergedRegion is off by one</action> + <action type="fix" fixes-bug="54803" context="OPC">Error opening XLSX after saving with a Drawing using POI</action> + <action type="add" fixes-bug="github-135" context="XDDF">Support to create new chart without reading template</action> + <action type="add" fixes-bug="github-143" context="HPSF">MAPIType.isFixedLength: not true in case of length > 8</action> + <action type="add" fixes-bug="github-144" context="XDDF">Support for seven new chart types</action> + <action type="add" fixes-bug="github-149" context="HSMF">improve MAPIMessage.getHtmlBody</action> + <action type="add" fixes-bug="github-150" context="XWPF">Add XWPFPicture getWidth and getDepth methods</action> + <action type="add" fixes-bug="github-151" context="XWPF">Add XWPFRun getStyle method</action> + <action type="add" fixes-bug="github-152" context="XWPF">Add XWPFParagraph setKeepNext method</action> + <action type="add" fixes-bug="github-153" context="XWPF">Add XWPFParagraph createHyperlinkRun method</action> + <action type="add" fixes-bug="github-154" context="SXSSF">Improved support for writing large files</action> + <action type="add" fixes-bug="github-157" context="OOXML">Add setters to POIXMLProperties</action> + <action type="fix" fixes-bug="63153" context="XDDF">Enable safe removal of data series from charts</action> + <action type="fix" fixes-bug="59623" context="XDDF">Provide example of threshold line in bar chart</action> + </actions> + </release> + + <release version="4.1.0" date="2019-04-09"> + <summary> + <summary-item>Improved support/fixes for Java 9+ and IBM JVM</summary-item> + <summary-item>New EMF renderer and support of SVG images in XSLF</summary-item> + <summary-item>Security, stability and memory/resource handling improvements</summary-item> + <summary-item>Various bug fixes across function and conditional format rule evaluation</summary-item> + <summary-item>Upgrade to XMLBeans 3.1.0</summary-item> + <summary-item>Upgrade to Bouncycastle 1.61</summary-item> + <summary-item>Upgrade to Curvesapi 1.06</summary-item> + <summary-item>Upgrade to Commons-Codec 1.12</summary-item> + <summary-item>Upgrade to Commons-Collections4 4.3</summary-item> + <summary-item>Upgrade to XMLSec 2.1.2</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="63200" context="XSLF">Avoid a possible NullPointerException in XSLFShape.selectPaint()</action> + <action type="add" fixes-bug="60724" context="SS_Common">Implement 'ignore hidden rows' variations for existing implemented variants</action> + <action type="fix" fixes-bug="63264" context="SS_Common">Conditional Format rule evaluation calculates relative references incorrectly</action> + <action type="fix" fixes-bug="61652" context="SS_Common">Fix NPE in EDATE function when date evaluates to an invalid value</action> + <action type="fix" fixes-bug="62151" context="POIFS">Work around illegal reflective access in Java 9+ when freeing buffers</action> + <action type="add" fixes-bug="63029" context="OPC">OPCPackage Potentially clobbers files on close()</action> + <action type="add" fixes-bug="62980" context="SS_Common XSSF HSSF">Make D* functions ignore case in headings</action> + <action type="fix" fixes-bug="60977" context="XSSF">Adding custom properties creates invalid .xlsx file on second write</action> + <action type="fix" fixes-bug="60460" context="SL_Common">Null pointer exception in ExternSheetNameResolver.prependSheetName method</action> + <action type="fix" fixes-bug="60845" context="XSSF">Fix copying styles/conditional formatting</action> + <action type="add" fixes-bug="63054" context="SS_Common XSSF HSSF">Improved evaluation of array formulas with errors in arguments</action> + <action type="fix" fixes-bug="63047" context="POI_Overall">Make POILogger subclassable</action> + <action type="add" fixes-bug="62904" context="SS_Common XSSF HSSF">Support array arguments in IF and logical IS*** functions</action> + <action type="add" fixes-bug="63028" context="SL_Common XSLF HSLF">Provide font embedding for slideshows</action> + <action type="fix" fixes-bug="61532" context="SXSSF">Fix setting values/types during formula evaluation for SXSSF</action> + <action type="fix" fixes-bug="62629" context="OPC">Allow to handle files with invalid content types for pictures</action> + <action type="fix" fixes-bug="62839" context="SL_Common">Fix MathX.floor for negative n</action> + <action type="fix" fixes-bug="62884" context="SL_Common">Sheetnum is not checked in InternalWorkbook.setSheetHidden()</action> + <action type="fix" fixes-bug="62886" context="OPC">Regression extracting text from corrupted docx files</action> + <action type="add" fixes-bug="63017" context="SL_Common XSLF">Remove rows from a XSLFTable</action> + <action type="add" fixes-bug="60656" context="SL_Common XSLF HSLF">EMF image support in slideshows</action> + <action type="add" fixes-bug="62365" context="XSLF">SVG image support in XSLF</action> + <action type="add" fixes-bug="github-136" context="XSSF">Support GEOMEAN function</action> + <action type="fix" fixes-bug="63011" context="OPC">Multiple digital signature in excel file broke first signature</action> + <action type="fix" fixes-bug="62999" context="SL_Common">IBM JDK JIT causes AIOOBE in TexturePaintContext</action> + <action type="fix" fixes-bug="62994" context="POI_Overall">IBM JCE workarounds</action> + <action type="fix" fixes-bug="62966" context="SL_Common">init presetShapeDefinitions.xml fail under IBM jdk</action> + <action type="fix" fixes-bug="62953" context="SL_Common XSLF HSLF">Rendering of FreeformShapes with formula fails</action> + <action type="fix" fixes-bug="63005" context="POI_Overall">Remove support for reading files that have XML entity definitions</action> + <action type="fix" fixes-bug="63013" context="XWPF">add XWPFRun setLang method</action> + <action type="fix" fixes-bug="63240" context="XSSF">Remove unnecessary synchronization on DocumentHelper.newDocumentBuilder and SAXHelper.newXMLReader</action> + <action type="fix" fixes-bug="61652" context="SS_Common">Fix NPE in EDATE function when date evaluates to an invalid value</action> + <action type="fix" fixes-bug="63264" context="SS_Common">Conditional Format rule evaluation calculates relative references incorrectly</action> + <action type="add" fixes-bug="60724" context="SS_Common">Implement 'ignore hidden rows' variations for existing SUBTOTAL function variants</action> + <action type="fix" fixes-bug="63268" context="SS_Common">Fix issue with CellUtil.setFont adding unnecessary styles</action> + <action type="fix" fixes-bug="61700" context="SS_Common">getForceFormulaRecalculation() returns wrong value</action> + <action type="fix" fixes-bug="63292" context="SS_Common">DataFormatter.formatCellValue() ignores use1904Windowing w/4-part date formats</action> + </actions> + </release> + + <release version="4.0.1" date="2018-12-03"> + <summary> + <summary-item>Fixes pom.xml entries for commons-maths3 (missing), curvesapi and commons-codec</summary-item> + <summary-item>Improvements for XDDF charts and text manipulation</summary-item> + <summary-item>Upgrade to XMLBeans 3.0.2</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="59773" context="POI_Overall">Move loop invariants outside of loop for faster execution</action> + <action type="fix" fixes-bug="59834" context="POI_Overall">poi-ooxml pom.xml should include dependency on poi-scratchpad</action> + <action type="fix" fixes-bug="62690" context="POI_Overall">Missing Maven dependency to commons-math3</action> + <action type="fix" fixes-bug="62692" context="OPC">WildFly XML parser not properly supported - Property 'http://www.oracle.com/xml/jaxp/properties/entityExpansionLimit' is not recognized</action> + <action type="fix" fixes-bug="62699" context="POI_Overall">Download page must link to https://downloads.apache.org/poi/KEYS</action> + <action type="fix" fixes-bug="62733" context="XSLF">XSLFBackground setFill() can corrupt the document</action> + <action type="fix" fixes-bug="62735" context="XSSF">poi-ooxml 4.0.0 should have dependency on curvesapi 1.05</action> + <action type="fix" fixes-bug="62740" context="XSSF">XSSFTable constructor automatically assigns invalid (non-unique) column IDs</action> + <action type="fix" fixes-bug="62768" context="OPC">OPCPackage#close() method is incorrectly synchronized</action> + <action type="fix" fixes-bug="62796" context="POI_Overall">Remove XML Event parser code from PackagePropertiesMarshaller</action> + <action type="fix" fixes-bug="62800" context="XSLF">Fix null pointer exception if a picture shape has no blip id</action> + <action type="fix" fixes-bug="62805" context="POI_Overall">Fix Old-Xerces build issues</action> + <action type="fix" fixes-bug="62805" context="XSLF">XSLFTableCell#removeBorder(BorderEdge.right) removes the bottom edge not the right edge.</action> + <action type="fix" fixes-bug="62811" context="POI_Overall">POI Encryption didn't work with 4.0.0 but did work with 3.17</action> + <action type="fix" fixes-bug="62951" context="POI_Overall">FileMagic not correctly identified</action> + <action type="fix" fixes-bug="62949" context="SL_Common">SlideShow rendering - keyframe fractions must be increasing</action> + <action type="fix" fixes-bug="62921" context="POI_Overall">Provide OOXMLLite alternative for Java 12+</action> + <action type="fix" fixes-bug="62625" context="POI_Overall">Handle off-spec, variant REFERENCE_NAME record structure in VBAMacroReader</action> + <action type="fix" fixes-bug="62624" context="POI_Overall">Handle module name mapping in VBAMacroReader</action> + <action type="fix" fixes-bug="62836" context="SS_Common">Support TREND function</action> + <action type="fix" fixes-bug="62859" context="XWPF">Rare NPE while creating XWPFSDTContent</action> + <action type="add" fixes-bug="62373" context="SS_Common">Support for FREQUENCY function</action> + <action type="fix" fixes-bug="62831" context="POI_Overall">WorkbookFactory.create support for subclass of File, eg from JFileChooser</action> + <action type="fix" fixes-bug="62815" context="XSSF">XLSB number extraction improvements</action> + <action type="fix" fixes-bug="62373" context="SS_Common">Support FREQUENCY function</action> + <action type="fix" fixes-bug="62742" context="POI_Overall">Add common-compress jar to bin zip/tgz</action> + <action type="fix" fixes-bug="62747" context="POI_Overall">Upgrade bouncycastle dependency to 1.60</action> + <action type="fix" fixes-bug="62736" context="XWPF">Relations on XSLFPictureShape were removed unconditionally</action> + <action type="add" fixes-bug="github-109" context="XDDF">Define XDDF user model for text body, its paragraphs and text runs</action> + <action type="add" fixes-bug="github-123" context="XSSF">Import chart on drawing</action> + <action type="fix" fixes-bug="62746" context="XDDF">Support axIds in XDDF</action> + <action type="fix" fixes-bug="60509" context="XSSF">XSSFWorkbook.setSheetName() does not update references in charts</action> + <action type="fix" fixes-bug="59625" context="XWPF">Localisation (Internationalisation in other languages) when applied in charts corrupt the MS Word file</action> + </actions> + </release> + + <release version="4.0.0" date="2018-09-07"> + <summary> + <summary-item>Removed support for Java 6 and 7 making Java 8 the minimum version supported</summary-item> + <summary-item>New OOXML schema (1.4) necessary, because of incompatible XMLBeans loading not anymore through POIXMLTypeLoader</summary-item> + </summary> + <actions> + <action type="remove" fixes-bug="62649" breaks-compatibility="true" context="POIFS">Remove OPOIFS*</action> + <action type="fix" fixes-bug="61589" context="XSLF">Importing content does not copy hyperlink address</action> + <action type="fix" fixes-bug="62587" context="XSLF">repeated call to XSLFSheet.removeShape leads to java.lang.IllegalArgumentException: partName</action> + <action type="fix" fixes-bug="62513" context="OOXML">Don't try to parse embedded package relationships</action> + <action type="add" fixes-bug="59268" context="OOXML">Work on providing an updated version of XMLBeans</action> + <action type="fix" fixes-bug="62451" context="HPSF">Document last printed in the year 27321</action> + <action type="fix" fixes-bug="60713" breaks-compatibility="true" context="SXSSF XSSF OPC">(S)XSSFWorkbook/POIXMLDocument.write(OutputStream) closes the OutputStream</action> + <action type="add" fixes-bug="62452" context="OPC">Extract configuration while verifying XML signatures</action> + <action type="fix" fixes-bug="62187" breaks-compatibility="true" context="OPC">Compiling with Java 10 fails with ClassCastException / use commons-compress</action> + <action type="fix" fixes-bug="62355" breaks-compatibility="true" context="POI_Overall">Unsplit packages for Jigsaw / Java 9 compatibility</action> + <action type="fix" fixes-bug="62041" context="SL_Common">TestFonts fails on Mac</action> + <action type="fix" fixes-bug="62051" context="XSLF">Two shapes have the same shapeId within the same slide</action> + <action type="fix" fixes-bug="61633" context="XSLF">Zero width shapes aren't rendered</action> + <action type="add" fixes-bug="62037" context="SL_Common">SlideNames should not be null but have a default as if accessed by VBA</action> + <action type="fix" fixes-bug="62381" context="SL_Common">Fix rendering of AutoShapes</action> + <action type="fix" fixes-bug="59893" context="POI_Overall">Forbid calls to InputStream.available</action> + <action type="fix" fixes-bug="61905" context="HSSF">HSSFWorkbook.setActiveCell() does not actually make the cell selected in Excel</action> + <action type="fix" fixes-bug="61459" context="HSLF">HSLFShape.getShapeName() returns name of shapeType and not the shape name</action> + <action type="add" fixes-bug="62319" breaks-compatibility="true" context="SL_Common">Decommission XSLF-/PowerPointExtractor</action> + <action type="add" fixes-bug="62092" context="SL_Common">Text not extracted from grouped text shapes in HSLF</action> + <action type="add" fixes-bug="62159" context="OPC">Support XML signature over windows certificate store</action> + <action type="add" fixes-bug="57369" context="XDDF">Add support for major and minor units on chart axes</action> + <action type="add" fixes-bug="55954" context="XWPF">Added methods to position table</action> + <action type="add" fixes-bug="61947" context="POI_Overall">Remove deprecated classes (POI 4.0.0)</action> + <action type="add" fixes-bug="55954" context="XWPF">Add functions to get, set, remove outer borders for tables</action> + <action type="add" fixes-bug="github-72" context="XDDF">Define XDDF user model for shape properties to be shared between XSLF, XSSF and XWPF</action> + <action type="add" fixes-bug="61543" breaks-compatibility="true" context="XSSF">Do not fail with "part already exists" when tables are created/removed</action> + <action type="add" fixes-bug="61550" breaks-compatibility="true" context="POI_Overall">Add more information to exception text and verify that it is thrown</action> + <action type="add" fixes-bug="61609" breaks-compatibility="true" context="POI_Overall">Add .gitattribute file and set lf for one sample-file</action> + <action type="add" fixes-bug="61797" breaks-compatibility="true" context="SL_Common">Embed Excel / Ole objects into powerpoint</action> + <action type="fix" fixes-bug="61943" context="SL_Common">narrow generics definition because of tighter java9 checks</action> + <action type="add" fixes-bug="61942" context="OPC">Refactor PackagePartName handling and add getUnusedPartIndex method</action> + <action type="fix" fixes-bug="61941" context="POIFS">Move Ole marker generation to Ole10Native</action> + <action type="fix" fixes-bug="61940" context="POI_Overall">Replace ClassID statics with enum</action> + <action type="add" fixes-bug="61939" context="OPC">Provide schema for AlternateContent - provide new ooxml-schemas-1.4.jar</action> + <action type="fix" fixes-bug="61787" context="HSSF">Change how deleted content is detected to not incorrectly see too much text as deleted, this was introduced with bug 58067</action> + <action type="fix" fixes-bug="61798" context="HSSF">Fix usage of getLastCellNum() when calculating worksheet dimension during saving</action> + <action type="fix" fixes-bug="61911" context="HWPF">Avoid IndexOutOfBounds access when reading pictures</action> + <action type="fix" fixes-bug="61765" context="HSSF">Support third party tool generated files using WorkBook as their POIFS directory name</action> + <action type="fix" fixes-bug="61881" context="HSLF">Regression in ppt parsing: typeface can't be null or empty</action> + <action type="add" fixes-bug="github-68" context="XDDF XSLF XSSF XWPF">Share chart data implementation between XSLFChart, XSSFChart and XWPFChart through XDDF</action> + <action type="fix" fixes-bug="61809" context="HPSF">Infinite loop in SectionIDMap.get() and .put()</action> + <action type="add" fixes-bug="60887" context="XSSF">Surface XSSF Header/Footer Attributes</action> + <action type="add" fixes-bug="61730" context="SS_Common">CellRangeAddresses support iterating over their CellAddresses</action> + <action type="fix" fixes-bug="61727" context="SS_Common">CellRangeUtil merge cell ranges broken for certain orders of arguments</action> + <action type="fix" fixes-bug="57517" context="HSSF">Fix various situations that were handled incorrectly in HSSFOptimiser</action> + <action type="add" fixes-bug="61671" context="XSLF">XSLFSlide does not contain isHidden and setHidden like HSLFSlide does</action> + <action type="update" fixes-bug="61630" context="XSSF">Performance improvement to XSSFExportToXML</action> + <action type="add" fixes-bug="58068" context="XSSF">Add a method to pass the actual Color to StylesTable.findFont()</action> + <action type="fix" fixes-bug="61096" context="POIFS">Add support for modules in VBAMacroReader</action> + <action type="fix" fixes-bug="61033" context="XSSF">Add XSSFWorkbook.setCellFormulaValidation() to control if formulas are validated during Cell.setCellFormula()</action> + <action type="fix" fixes-bug="61148" context="SXSSF">Fix calculating/setting formula value</action> + <action type="fix" fixes-bug="61064" context="SS_Common">Support behavior of function CEILING in newer versions of Microsoft Excel</action> + <action type="fix" fixes-bug="61516" context="SS_Common">Correctly handle references that end up outside the workbook when cells with formulas are copied</action> + <action type="add" fixes-bug="60737" context="XSSF">Add endSheet() to XSSFEventBasedExcelExtractor</action> + <action type="fix" fixes-bug="59747" context="OPC">Exchange order of writing parts into Zip to allow some tools to handle files better</action> + <action type="add" fixes-bug="github-69" context="SS_Common">Support matrix functions</action> + <action type="fix" fixes-bug="60499" context="OPC">Deleting a picture that is used twice on a slide corrupt the slide</action> + <action type="fix" fixes-bug="60279" context="POI_Overall">Back-off to brute-force search for macro content if macro offset is incorrect</action> + <action type="add" fixes-bug="61528" context="XSSF">Pivot table enhancements</action> + <action type="fix" fixes-bug="61906" context="XSSF">add API for working with RichStringText</action> + <action type="fix" fixes-bug="61792" context="SS_Common">Avoid iterating over chars (use codepoints instead)</action> + <action type="fix" fixes-bug="62254" context="SS_Common">Update OFFSET function to support optional values</action> + <action type="update" fixes-bug="62435" context="XSSF">Rename getAllEmbedds method to getAllEmbeddedParts (getAllEmbedds is retained but deprecated)</action> + <action type="update" fixes-bug="62438" breaks-compatibility="true" context="POI_Overall">Replace org.apache.poi.openxml4j.util.Nullable with java.lang.Optional</action> + <action type="fix" fixes-bug="github-90" context="XSSF">Change default DSIG signing algorithm to SHA256</action> + <action type="fix" fixes-bug="github-107" context="SS_Common">Support AREAS function</action> + <action type="fix" fixes-bug="github-110" breaks-compatibility="true" context="XWPF">Renames org.apache.poi.xwpf.usermodel.TextSegement to org.apache.poi.xwpf.usermodel.TextSegment</action> + <action type="fix" fixes-bug="github-114" context="XWPF">Better support for Footnotes and Endnotes</action> + </actions> + </release> + +</changes> diff --git a/src/documentation/content/xdocs/components/configuration.xml b/src/documentation/content/xdocs/components/configuration.xml new file mode 100644 index 0000000000..71a1557164 --- /dev/null +++ b/src/documentation/content/xdocs/components/configuration.xml @@ -0,0 +1,232 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - Configuration</title> + <authors> + <person id="POI" name="POI Developers" email="dev@poi.apache.org"/> + </authors> + </header> + + <body> + <section><title>Overview</title> + <p>The best way to learn about using Apache POI is to read through the <a href="index.html">feature documentation</a> + and other online examples online. + </p> + <p>To keep the features documentation focused on the APIs, there is little mention of some of the configuration + settings that can be enabled that may prove useful to users who have to handle very large documents or very + large throughput. + </p> + </section> + <section><title>Configuration via Java-code when calling Apache POI</title> + <p>These API methods allow to configure behavior of Apache POI for special needs, e.g. when processing excessively + large files. + </p> + <table> + <tr> + <th>Configuration Setting</th> + <th>Description</th> + </tr> + + <tr> + <td>org.apache.poi.ooxml.POIXMLTypeLoader.DEFAULT_XML_OPTIONS</td> + <td>POI support for XSSF APIs relies heavily on <a href="https://xmlbeans.apache.org">XMLBeans</a>. + This instance can be <a href="https://xmlbeans.apache.org/docs/5.0.0/org/apache/xmlbeans/XmlOptions.html">configured</a>. + It is recommended to take care if you do change any of the config items. + In POI 5.1.0, we will disallow Doc Type parsing in the XML files embedded in xlsx/docx/pptx/etc files, by default. + DEFAULT_XML_OPTIONS.setDisallowDocTypeDeclaration(false) will undo this change. + </td> + </tr> + + <tr> + <td><a href="https://poi.apache.org/apidocs/5.0/org/apache/poi/util/IOUtils.html#setByteArrayMaxOverride-int-"> + org.apache.poi.util.IOUtils.setByteArrayMaxOverride(int maxOverride)</a> + </td> + <td>If this value is set to > 0, IOUtils.safelyAllocate(long, int) will ignore the maximum record length parameter. + This is designed to allow users to bypass the hard-coded maximum record lengths if they are willing to accept the risk of allocating memory up to the size specified. + It also allows to impose a lower limit than used for very memory constrained systems. + <p> + <strong>Note</strong>: This is a per-allocation limit and does not allow you to limit overall sum of allocations! Use -1 for using the limits specified per record-type. + </p> + </td> + </tr> + + <tr> + <td><a href="https://poi.apache.org/apidocs/5.0/org/apache/poi/openxml4j/util/ZipSecureFile.html#setMinInflateRatio-double-"> + org.apache.poi.openxml4j.util.ZipSecureFile.setMinInflateRatio(double ratio)</a> + </td> + <td>Sets the ratio between de- and inflated bytes to detect zipbomb. + It defaults to 1% (= 0.01d), i.e. when the compression is better than 1% for any given read package part, the parsing will fail indicating a Zip-Bomb. + </td> + </tr> + + <tr> + <td><a href="https://poi.apache.org/apidocs/5.0/org/apache/poi/openxml4j/util/ZipSecureFile.html#setMaxEntrySize-long-"> + org.apache.poi.openxml4j.util.ZipSecureFile.setMaxEntrySize(long maxEntrySize)</a> + </td> + <td>Sets the maximum file size of a single zip entry. It defaults to 4GB, i.e. the 32-bit zip format maximum. + This can be used to limit memory consumption and protect against security vulnerabilities when documents are provided by users. + POI 5.1.0 removes the previous limit of 4GB on this setting. + </td> + </tr> + + <tr> + <td><a href="https://poi.apache.org/apidocs/5.0/org/apache/poi/openxml4j/util/ZipSecureFile.html#setMaxTextSize-long-"> + org.apache.poi.openxml4j.util.ZipSecureFile.setMaxTextSize(long maxTextSize)</a> + </td> + <td>Sets the maximum number of characters of text that are extracted before an exception is thrown during extracting text from documents. + This can be used to limit memory consumption and protect against security vulnerabilities when documents are provided by users. + The default is approx 10 million chars. Prior to POI 5.1.0, the max allowed was approx 4 billion chars. + </td> + </tr> + + <tr> + <td>org.apache.poi.openxml4j.util.ZipInputStreamZipEntrySource.setThresholdBytesForTempFiles(int thresholdBytes) + </td> + <td><strong>Added in POI 5.1.0.</strong> + Number of bytes at which a zip entry is regarded as too large for holding in memory + and the data is put in a temp file instead - defaults to -1 meaning temp files are not used + and that zip entries with more than 2GB of data after decompressing will fail, 0 means all + zip entries are stored in temp files. A threshold like 50000000 (approx 50Mb is recommended) + </td> + </tr> + + <tr> + <td>org.apache.poi.openxml4j.util.ZipInputStreamZipEntrySource.setEncryptTempFiles(boolean encrypt) + </td> + <td><strong>Added in POI 5.1.0.</strong> + Whether temp files should be encrypted (default false). Only affects temp files related to zip entries. + </td> + </tr> + + <tr> + <td>org.apache.poi.openxml4j.opc.ZipPackage.setUseTempFilePackageParts(boolean tempFilePackageParts) + </td> + <td><strong>Added in POI 5.1.0.</strong> + Whether to save package part data in temp files to save memory (default=false). + </td> + </tr> + + <tr> + <td>org.apache.poi.openxml4j.opc.ZipPackage.setEncryptTempFilePackageParts(boolean encryptTempFiles) + </td> + <td><strong>Added in POI 5.1.0.</strong> + Whether to encrypt package part temp files (default=false). + </td> + </tr> + + <tr> + <td>org.apache.poi.extractor.ExtractorFactory.setThreadPrefersEventExtractors(boolean preferEventExtractors) and + org.apache.poi.extractor.ExtractorFactory.setAllThreadsPreferEventExtractors(Boolean preferEventExtractors) + </td> + <td> + When creating text-extractors for documents, allows to choose a different type of extractor which parses documents + via an event-based parser. + </td> + </tr> + + <tr> + <td>Various classes: setMaxRecordLength(int length) + </td> + <td> + Allows to override the default max record length for various classes which + parse input data. E.g. XMLSlideShow, XSSFBParser, HSLFSlideShow, HWPFDocument, + HSSFWorkbook, EmbeddedExtractor, StringUtil, ... + <br/> + This may be useful if you try to process very large files which otherwise trigger + the excessive-memory-allocation prevention in Apache POI. + </td> + </tr> + + <tr> + <td>org.apache.poi.xslf.usermodel.XSLFPictureData.setMaxImageSize(int length) + </td> + <td> + Allows to override the default max image size allowed for XSLF pictures. + </td> + </tr> + + <tr> + <td>org.apache.poi.xssf.usermodel.XSSFPictureData#setMaxImageSize(int length) + </td> + <td> + Allows to override the default max image size allowed for XSSF pictures. + </td> + </tr> + + <tr> + <td>org.apache.poi.xwpf.usermodel.XWPFPictureData#setMaxImageSize(int length) + </td> + <td> + Allows to override the default max image size allowed for XWPF pictures. + </td> + </tr> + + </table> + </section> + <section><title>Observed Java System Properties</title> + <p>Apache POI supports some Java System Properties. + </p> + <table> + <tr> + <th>System property</th> + <th>Description</th> + </tr> + + <tr> + <td>java.io.tmpdir</td> + <td> + Apache POI uses the default mechanism of the JDK for specifying the location of + temporary files. + </td> + </tr> + + <tr> + <td>org.apache.poi.hwpf.preserveBinTables and org.apache.poi.hwpf.preserveTextTable</td> + <td> + Allows to adjust how parsing Word documents via HWPF is handling tables. + </td> + </tr> + + <tr> + <td>org.apache.poi.ss.ignoreMissingFontSystem</td> + <td><strong>Added in POI 5.2.3.</strong> + Instructs Apache POI to ignore some errors due to missing fonts and thus allows + to perform more functionality even when no fonts are installed. + <br/> + Note: Some functionality will still not be possible as it cannot use default-values, e.g. rendering + slides, drawing, ... + </td> + </tr> + </table> + </section> + </body> + + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/components/diagram/index.xml b/src/documentation/content/xdocs/components/diagram/index.xml new file mode 100644 index 0000000000..5f060e8318 --- /dev/null +++ b/src/documentation/content/xdocs/components/diagram/index.xml @@ -0,0 +1,107 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - HDGF and XDGF - Java API To Access Microsoft Visio Format Files</title> + <subtitle>Overview</subtitle> + <authors> + <person id="pd" name="POI Developers" email="dev@poi.apache.org"/> + </authors> + </header> + + <body> + <section> + <title>Overview</title> + + <p>HDGF is the POI Project's pure Java implementation of the + Visio binary (VSD) file format. XDGF is the POI Project's + pure Java implementation of the Visio XML (VSDX) file format.</p> + <!-- TODO More about XDGF here! --> + <p>Currently, HDGF provides a low-level, read-only api for + accessing Visio documents. It also provides a + <a href="https://github.com/apache/poi/tree/trunk/poi-scratchpad/src/main/java/org/apache/poi/hdgf/extractor/">way</a> + to extract the textual content from a file. + </p> + <p>At this time, there is no <em>usermodel</em> api or similar, + only low level access to the streams, chunks and chunk commands. + Users are advised to check the unit tests to see how everything + works. They are also well advised to read the documentation + supplied with + <a href="https://web.archive.org/web/20071212220759/https://www.gnome.ru/projects/vsdump_en.html">vsdump</a> + to get a feel for how Visio files are structured.</p> + <p>To get a feel for the contents of a file, and to track down + where data of interest is stored, HDGF comes with + <a href="https://github.com/apache/poi/tree/trunk/poi-scratchpad/src/main/java/org/apache/poi/hdgf/dev/">VSDDumper</a> + to print out the contents of the file. Users should also make + use of + <a href="https://web.archive.org/web/20071212220759/https://www.gnome.ru/projects/vsdump_en.html">vsdump</a> + to probe the structure of files.</p> + + <note> + This code currently lives the + <a href="https://github.com/apache/poi/tree/trunk/poi-scratchpad/">scratchpad area</a> + of the POI Git repository. To use this component, ensure + you have the Scratchpad Jar on your classpath, or a dependency + defined on the <em>poi-scratchpad</em> artifact - the main POI + jar is not enough! See the + <a href="site:components">POI Components Map</a> + for more details. + </note> + + <section> + <title>Steps required for write support</title> + <p>Currently, HDGF is only able to read visio files, it is + not able to write them back out again. We believe the + following are the steps that would need to be taken to + implement it.</p> + <ol> + <li>Re-write the decompression support in LZW4HDGF as + HDGFLZW, which will be much better documented, and also + under the ASL. <strong>Completed October 2007</strong></li> + <li>Add compression support to HDGFLZW. + <strong>In progress - works for small streams but encoding + goes wrong on larger ones</strong></li> + <li>Have HDGF just write back the raw bytes it read in, and + have a test to ensure the file is un-changed.</li> + <li>Have HDGF generate the bytes to write out from the + Stream stores, using the compressed data as appropriate, + without re-compressing. Plus test to ensure file is + un-changed.</li> + <li>Have HDGF generate the bytes to write out from the + Stream stores, re-compressing any streams that were + decompressed. Plus test to ensure file is un-changed.</li> + <li>Have HDGF re-generate the offsets in pointers for the + locations of the streams. Plus test to ensure file is + un-changed.</li> + <li>Have HDGF re-generate the bytes for all the chunks, from + the chunk commands. Tests to ensure the chunks are + serialized properly, and then that the file is un-changed</li> + <li>Alter the data of one command, but keep it the same + length, and check visio can open the file when written + out.</li> + <li>Alter the data of one command, to a new length, and + check that visio can open the file when written out.</li> + </ol> + </section> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/document/docoverview.xml b/src/documentation/content/xdocs/components/document/docoverview.xml new file mode 100644 index 0000000000..621e8e9309 --- /dev/null +++ b/src/documentation/content/xdocs/components/document/docoverview.xml @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - HWPF - Java API to Handle Microsoft Word Files</title> + <subtitle>Word File Format</subtitle> + <authors> + <person name="S. Ryan Ackley" email="sackley@cfl.rr.com"/> + </authors> + </header> + + <body> + <section><title>The Word 97 File Format in semi-plain English</title> + + <p>The purpose of this document is to give a brief high level overview of the + HWPF document format. This document does not go into in-depth technical + detail and is only meant as a supplement to the Microsoft Word 97-2007 + Binary File Format freely available from + <a href="https://msdn.microsoft.com/en-us/library/cc313153%28v=office.12%29.aspx">Microsoft</a>.</p> + <p>The OLE file format is not discussed in this document. It is assumed that + the reader has a working knowledge of the POIFS API. </p> + + <section><title>Word file structure</title> + <p>A Word file is made up of the document text and data structures + containing formatting information about the text. Of course, this is a + very simplified illustration. There are fields and macros and other + things that have not been considered. At this stage, HWPF is mainly + concerned with formatted text.</p> + </section> + <section><title>Reading Word files</title> + <p>The entry point for HWPF's reading of a Word file is the File Information + Block (FIB). This structure is the entry point for the locations and size + of a document's text and data structures. The FIB is located at the + beginning of the main stream.</p> + <section><title>Text</title> + <p>The document's text is also located in the main stream. Its starting + location is given as FIB.fcMin and its length is given in bytes by + FIB.ccpText. These two values are not very useful in getting the text + because of unicode. There may be unicode text intermingled with ASCII + text. That brings us to the piece table.</p> + <p>The piece table is used to divide the text into non-unicode and unicode + pieces. The size and offset are given in FIB.fcClx and FIB.lcbClx + respectively. The piece table may contain Property Modifiers (prm). + These are for complex(fast-saved) files and are skipped. Each text piece + contains offsets in the main stream that contain text for that piece. + If the piece uses unicode, the file offset is masked with a certain bit. + Then you have to unmask the bit and divide by 2 to get the real file + offset. </p> + </section> + <section><title>Text Formatting</title> + <section><title>Stylesheet</title> + <p>All text formatting is based on styles contained in the StyleSheet. + The StyleSheet is a data structure containing among other things, style + descriptions. Each style description can contain a paragraph style and + a character style or simply a character style. Each style description + is stored in a compressed version on file. Basically these are deltas + from another style.</p> + <p>Eventually, you have to chain back to the nil style which is an + imaginary style with certain implied values.</p> + </section> + <section><title>Paragraph and Character styles</title> + <p>Paragraph and Character formatting properties for a document's text are + stored on file as deltas from some base style in the Stylesheet. The + deltas are used to create a complete uncompressed style in memory.</p> + <p>Uncompressed paragraph styles are represented by the Pargraph + Properties(PAP) data structure. Uncompressed character styles are + represented by the Character Properties(CHP) data structure. The styles + for the document text are stored in compressed format in the + corresponding Formatted Disk Pages (FKP). A compressed PAP is referred + to as a PAPX and a compressed CHP is a CHPX. The FKP locations are + stored in the bin table. There are separate bin tables for CHPXs and + PAPXs. The bin tables' locations and sizes are stored in the FIB.</p> + <p>A FKP is a 512 byte OLE page. It contains the offsets of the beginning + and end of each paragraph/character run in the main stream and the + compressed properties for that interval. The compressed PAPX is based on + its base style in the StyleSheet. The compressed CHPX is based on the + enclosing paragraph's base style in the Stylesheet.</p> + </section> + <section><title>Uncompressing styles and other data structures</title> + <p>All compressed properties(CHPX, PAPX, SEPX) contain a grpprl. A grpprl + is an array of sprms. A sprm defines a delta from some base property. + There is a table of possible sprms in the Word 97 spec. Each sprm is a + two byte operand followed by a parameter. The parameter size depends on + the sprm. Each sprm describes an operation that should be performed on + the base style. After every sprm in the grpprl is performed on the base + style you will have the style for the paragraph, character run, + section, etc.</p> + </section> + </section> + </section> + </section> + </body> +</document> + diff --git a/src/documentation/content/xdocs/components/document/index.xml b/src/documentation/content/xdocs/components/document/index.xml new file mode 100644 index 0000000000..f5dd91c61c --- /dev/null +++ b/src/documentation/content/xdocs/components/document/index.xml @@ -0,0 +1,235 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - HWPF and XWPF - Java API to Handle Microsoft Word Files</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/> + <person name="Andrew C. Oliver" email="acoliver@apache.org"/> + <person name="Ryan Ackley" email="sackley@apache.org"/> + <person name="Rainer Klute" email="klute@apache.org"/> + </authors> + </header> + + <body> + <section><title>Overview</title> + + <p>HWPF is the name of our port of the Microsoft Word 97(-2007) file format + to pure Java. It also provides limited read only support for the older + Word 6 and Word 95 file formats.</p> + + <p>The partner to HWPF for the new Word 2007 .docx format is <em>XWPF</em>. + Whilst HWPF and XWPF provide similar features, there is not a common + interface across the two of them at this time.</p> + + <p>Both HWPF and XWPF could be described as "moderately functional". For some + use cases, especially around text extraction, support is very strong. For + others, support may be limited or incomplete, and it may be necessary to + dig down into low-level code. Error checking may be missing in places, + so it may be possible to accidentally generate invalid files. Enhancements + to fix such things are generally very well received!</p> + + <p>As detailed in the <a href="site:components">Components + Page</a>, HWPF is contained within the poi-scratchpad-XXX.jar, while XWPF + is in the poi-ooxml-XXX.jar. You will need to ensure you include the appropriate + jars (and their dependencies!) in your classpath to use HWPF or XWPF.</p> + + <p>Please note that in version 3.12, due to a bug, you might need to include + poi-scratchpad-XXX.jar when using XWPF. This has been fixed again for the next + release as there should not be such a dependency.</p> + + </section> + <section> + <title>An overview of the code</title> + <p> + Source in the <em>org.apache.poi.hwpf.model</em> tree is the Java representation of + internal Word format structure. This code is "internal", it shall not + be used by your code. Code from <em>org.apache.poi.hwpf.usermodel</em> + package is actual public and user-friendly (as much as possible) API to access document + parts. Source code in the + <em>org.apache.poi.hwpf.extractor</em> + tree is a wrapper of this to facilitate easy extraction of interesting things (eg the Text), + and + <em>org.apache.poi.hwpf.converter</em> + package contains Word-to-HTML and Word-to-FO converters (latest can be used to generate PDF + from Word files when using with + <a href="https://xmlgraphics.apache.org/fop/">Apache FOP</a> + ). Also there is a small file-structure-dumping utility in + <em>org.apache.poi.hwpf.dev</em> + package, primally for developing purposes. + </p> + + <p> + The main entry point to HWPF is HWPFDocument. Currently it has a lot of references both to + internal interfaces ( + <em>org.apache.poi.hwpf.model</em> + package) and public API ( + <em>org.apache.poi.hwpf.usermodel</em> + ) package. It is possible that it will be split into two different interfaces (like WordFile + and WordDocument) in later versions. + </p> + + <p> + The main entry point to XWPF is XWPFDocument. From there, you can get the + paragraphs, pictures, tables, sections, headers etc. + </p> + <p> + Currently, there are only a handful of example programs using HWPF and XWPF + available. They can be found in svn in the examples section, under + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hwpf">HWPF</a> + and + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xwpf">XWPF</a>. + Both HWPF and XWPF have fairly high levels of unit test coverage, which + provides examples of using the various areas of functionality of both + modules. These can be found in svn, under + <a href="https://github.com/apache/poi/tree/trunk/poi-scratchpad/src/test/java/org/apache/poi/hwpf">HWPF</a> + and + <a href="https://github.com/apache/poi/tree/trunk/poi-ooxml/src/test/java/org/apache/poi/xwpf">XWPF</a>. + Contributions of more examples, whether inspired by the unit tests or + not, would be most welcomed! + </p> + + </section> + <section> + <title>HWPF Notes</title> + + <p>A .doc Word document, as handled by HWPF, can be considered as very long single + text buffer. The HWPF API provides "pointers" + to document parts, like sections, paragraphs and character runs. Usually user will iterates + over main document part sections, paragraphs from sections and character runs from + paragraph. Each such interface is a pointer to document text subrange along with additional + properties (and they all extends same Range parent class). There is additional Range + implementations like Table, TableRow, TableCell, etc. Some structures like Bookmark or Field + can also provide subranges pointers. + </p> + + <p>Changing file content usually requires a lot of synchronized changes in those structures like + updating property boundaries, position handlers, etc. Because of that HWPF API shall be + considered as not thread safe. In addition, there is a "one pointer" rule for changing + content. It means you should not use two different Range instances at one time. More + precisely, if you are changing file content using some range pointer, all other range + pointers except parents' ones become invalid. For example if you obtain overall range (1), + paragraph range (2) from overall range and character run range (3) from paragraph range and + change text of paragraph, character run range is now invalid and should not be used, but + overall range pointer still valid. Each time you obtaining range (pointer) new instance is + created. It means if you obtained two range pointers and changed document text using first + range pointer, second one became invalid. + </p> + + </section> + <section> + <title>XWPF Patches Required!</title> + + <p>At the moment, XWPF covers many common use cases for reading and writing + .docx files. Whilst this is a great thing, it does mean that XWPF does + everything that the current POI committers need it to do, and so none of + the committers are actively adding new features.</p> + + <p>If you come across a feature in XWPF that you need, and isn't currently + there, please do send in a patch to add the extra functionality! More details + on contributing patches are available on the <a + href="site:guidelines">"Contribution to POI" page</a>.</p> + </section> + + <section> + <title>HWPF Patches Required!</title> + + <p>At the moment we unfortunately do not have someone taking care for HWPF + and fostering its development. What we need is someone to stand up, take + this thing under his hood as his baby and push it forward. Ryan Ackley, + who put a lot of effort into HWPF, is no longer on board, so HWPF is an + orphan child waiting to be adopted.</p> + + <p>If <strong>you</strong> are interested in becoming the new HWPF + pointman, you should look into the Microsoft Word internals. A good + starting point seems to be Ryan Ackley's <a + href="site:docformat">overview</a>. An introduction to the binary + file formats is <a + href="https://msdn.microsoft.com/en-us/library/cc998577%28v=office.12%29.aspx">available + from Microsoft</a>, which has some good references and links. After that, + the full details on the word format are available from + <a href="https://msdn.microsoft.com/en-us/library/cc313153%28v=office.12%29.aspx">Microsoft</a>, + but the documentation can be a little hard to get into at first... Try reading the + <a href="site:docformat">overview</a> first, and looking at the existing + code, then finally look up the documentation for specific missing features.</p> + + <p>As a first step you should familiarize yourself with the source code, + examples, test cases, and the HWPF patches available at <a + href="https://issues.apache.org/">Bugzilla</a> (if any). Then you + should compile an overview of</p> + + <ul> + <li>the current HWPF status,</li> + <li>the patches in <a + href="https://issues.apache.org/bugzilla/">Bugzilla</a> to be checked + in (and those that should better be ditched),</li> + <li>the available test cases and the test cases still to be written,</li> + <li>the available documentation and the docs to be written,</li> + <li>anything else that seems reasonable</li> + </ul> + + <p>When you start coding, you will not yet have write access to the + SVN repository. Please submit your patches to <a + href="https://issues.apache.org/">Bugzilla</a> and nag <a + href="mailto:dev@poi.apache.org">the dev list</a> until someone commits + them. Besides the actual checking in of HWPF patches, current POI + committers will also do some minor reviews now and then of your source code + patches, test cases and documentation to help ensure software quality. But + most of the time you will be on your own. However, anyone offering useful + contributions over a period of time will be offered committership!</p> + + <p>Please do not forget to write <a + href="https://www.junit.org/">JUnit</a> test cases and documentation! + We won't accept code that doesn't come with test cases. And please + consider that other contributors should be able to understand your source + code easily. If you need any help getting started with JUnit test cases + for HWPF, please ask on the developers' mailing list! If you show that you + are prepared to stick at it you will most likely be given SVN commit + access. See <a href="site:guidelines">"Contribution to POI" page</a> + for more details and help getting started.</p> + + <p>Of course we will help you as best as we can. However, presently there + is no committer who is really familiar with the Word format, so you'll be + mostly on your own. We are looking forward for you and your contributions! + Honor and glory of becoming a POI committer are waiting!</p> + </section> + </body> +</document> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/src/documentation/content/xdocs/components/document/projectplan.xml b/src/documentation/content/xdocs/components/document/projectplan.xml new file mode 100644 index 0000000000..f43c2a1b60 --- /dev/null +++ b/src/documentation/content/xdocs/components/document/projectplan.xml @@ -0,0 +1,392 @@ +<?xml version="1.0"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!-- edited with XMLSPY v5 rel. 4 U (http://www.xmlspy.com) by Ryan Ackley (Myself) --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> +<document> + <header> + <title>Apache POI™ - HWPF - Java API to Handle Microsoft Word Files</title> + <subtitle>Project Plan</subtitle> + <authors> + <person name="Ryan Ackley" email="sackley@apache.org"/> + </authors> + </header> + <body> + <p>HWPF Milestones</p> + <table> + <tr> + <th> + Milestones + </th> + <th> + Target Date + </th> + <th> + Owner + </th> + </tr> + <tr> + <td> + Read in a Word document +with minimum formatting +(no lists, tables, footnotes, +endnotes, headers, footers) +and write it back out with the +result viewable in Word +97/2000 + </td> + <td> + 07/11/2003 + </td> + <td> + Ryan + </td> + </tr> + <tr> + <td> + Add support for Lists and +Tables + </td> + <td> + 8/15/2003 + </td> + <td> +   + </td> + </tr> + <tr> + <td> + HWPF 1.0-alpha release with +documentation and examples + </td> + <td> + 8/18/2003 + </td> + <td> + Praveen/Ryan + </td> + </tr> + <tr> + <td> + Add support for Headers, +Footers, endnotes, and +footnotes + </td> + <td> + 8/31/2003 + </td> + <td> + ? + </td> + </tr> + <tr> + <td> + Add support for forms and +mail merge + </td> + <td> + September/October 2003 + </td> + <td> + ? + </td> + </tr> + </table> + <p>HWPF Task Lists</p> + <p>Read in a Word document with minimum formatting (no lists, tables, footnotes, +endnotes, headers, footers) and write it back out with the result viewable in Word 97/2000</p> + <table> + <tr> + <th> + Task + </th> + <th> + Target Date + </th> + <th> + Owner + </th> + </tr> + <tr> + <td> + Create classes to read and +write low level data +structures with test cases + </td> + <td> + 7/10/2003 + </td> + <td> + Ryan + </td> + </tr> + <tr> + <td> + Create classes to read and +write FontTable and Font +names with test case + </td> + <td> + 7/10/2003 + </td> + <td> + Praveen + </td> + </tr> + <tr> + <td> + Final test + </td> + <td> + 7/11/2003 + </td> + <td> + Ryan + </td> + </tr> + </table> + <p>Develop user friendly API so it is fun and easy to read and write word documents +with java.</p> + <table> + <tr> + <th> + Task + </th> + <th> + Target Date + </th> + <th> + Owner + </th> + </tr> + <tr> + <td> + Develop a way for SPRMS to +be compressed and +uncompressed + </td> + <td> + + </td> + <td> + + </td> + </tr> + <tr> + <td> + Override CHPAbstractType +with a concrete class that +exposes attributes with +human readable names + </td> + <td> + + </td> + <td> + + </td> + </tr> + <tr> + <td> + Override PAPAbstractType +with a concrete class that +exposes attributes with +human readable names + </td> + <td> + + </td> + <td> + + </td> + </tr> + <tr> + <td> + Override SEPAbstractType +with a concrete class that +exposes attributes with +human readable names + </td> + <td> + + </td> + <td> + + </td> + </tr> + <tr> + <td> + Override DOPAbstractType +with a concrete class that +exposes attributes with +human readable names + </td> + <td> + + </td> + <td> + + </td> + </tr> + <tr> + <td> + Override TAPAbstractType +with a concrete class that +exposes attributes with +human readable names + </td> + <td> + + </td> + <td> + + </td> + </tr> + <tr> + <td> + Override TCAbstractType +with a concrete class that +exposes attributes with +human readable names + </td> + <td> + + </td> + <td> + + </td> + </tr> + <tr> + <td> + Develop a VerifyIntegrity +class for testing so it is easy +to determine if a Word +Document is well-formed. + </td> + <td> + + </td> + <td> + + </td> + </tr> + <tr> + <td> + Develop general intuitive +API to tie everything together + </td> + <td> + + </td> + <td> + + </td> + </tr> + </table> + <p>Add support for lists and tables</p> + <table> + <tr> + <th> + Task + </th> + <th> + Target Date + </th> + <th> + Owner + </th> + </tr> + <tr> + <td> + Add data structures for +reading and writing list data +with test cases. + </td> + <td> + + </td> + <td> + + </td> + </tr> + <tr> + <td> + Add data structures for +reading and writing tables +with test cases. + </td> + <td> + + </td> + <td> + + </td> + </tr> + </table> + <p>HWPF 1.0-alpha release with documentation and examples</p> + <table> + <tr> + <th> + Task + </th> + <th> + Target Date + </th> + <th> + Owner + </th> + </tr> + <tr> + <td> + Document the user model +API + </td> + <td> + + </td> + <td> + + </td> + </tr> + <tr> + <td> + Document the low level +classes + </td> + <td> + + </td> + <td> + + </td> + </tr> + <tr> + <td> + Come up with detailed How-To’s + </td> + <td> + + </td> + <td> + + </td> + </tr> + </table> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/document/quick-guide-xwpf.xml b/src/documentation/content/xdocs/components/document/quick-guide-xwpf.xml new file mode 100644 index 0000000000..a321821957 --- /dev/null +++ b/src/documentation/content/xdocs/components/document/quick-guide-xwpf.xml @@ -0,0 +1,89 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>POI-XWPF - A Quick Guide</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Nick Burch" email="nick at torchbox dot com"/> + </authors> + </header> + + <body> + <p>XWPF has a fairly stable core API, providing read and write access + to the main parts of a Word .docx file, but it isn't complete. For + some things, it may be necessary to dive down into the low level XMLBeans + objects to manipulate the ooxml structure. If you find yourself having + to do this, please consider sending in a patch to enhance that, see the + <a href="site:guidelines">"Contribution to POI" page</a>.</p> + + <section><title>Basic Text Extraction</title> + <p>For basic text extraction, make use of +<code>org.apache.poi.xwpf.extractor.XWPFWordExtractor</code>. It accepts an input +stream or a <code>XWPFDocument</code>. The <code>getText()</code> +method can be used to +get the text from all the paragraphs, along with tables, headers etc. + </p> + </section> + + <section><title>Specific Text Extraction</title> + <p>To get specific bits of text, first create a +<code>org.apache.poi.xwpf.XWPFDocument</code>. Select the <code>IBodyElement</code> +of interest (Table, Paragraph etc), and from there get a <code>XWPFRun</code>. +Finally fetch the text and properties from that. + </p> + </section> + + <section><title>Headers and Footers</title> + <p>To get at the headers and footers of a word document, first create a +<code>org.apache.poi.xwpf.XWPFDocument</code>. Next, you need to create a +<code>org.apache.poi.xwpf.usermodel.XWPFHeaderFooter</code>, passing it your +XWPFDocument. Finally, the XWPFHeaderFooter gives you access to the headers and +footers, including first / even / odd page ones if defined in your +document.</p> + </section> + + <section><title>Changing Text</title> + <p>From a <code>XWPFParagraph</code>, it is possible to fetch the existing + <code>XWPFRun</code> elements that make up the text. To add new text, + the <code>createRun()</code> method will add a new <code>XWPFRun</code> + to the end of the list. <code>insertNewRun(int)</code> can instead be + used to add a new <code>XWPFRun</code> at a specific point in the + paragraph. + </p> + <p>Once you have a <code>XWPFRun</code>, you can use the + <code>setText(String)</code> method to make changes to the text. To add + whitespace elements such as tabs and line breaks, it is necessary to use + methods like <code>addTab()</code> and <code>addCarriageReturn()</code>. + </p> + </section> + + <section><title>Further Examples</title> + <p>For now, there are a limited number of XWPF examples in the + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xwpf">Examples Package</a>. + Beyond those, the best source of additional examples is in the unit + tests. <a href="https://github.com/apache/poi/tree/trunk/poi-ooxml/src/test/java/org/apache/poi/xwpf/"> + Browse the XWPF unit tests.</a> + </p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/document/quick-guide.xml b/src/documentation/content/xdocs/components/document/quick-guide.xml new file mode 100644 index 0000000000..a15f2009a5 --- /dev/null +++ b/src/documentation/content/xdocs/components/document/quick-guide.xml @@ -0,0 +1,88 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>POI-HWPF - A Quick Guide</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Nick Burch" email="nick at torchbox dot com"/> + </authors> + </header> + + <body> + <p>HWPF is still in early development. It is in the <a + href="https://github.com/apache/poi/tree/trunk/poi-scratchpad/"> + scratchpad section of the SVN.</a> You will need to ensure you + either have a recent SVN checkout, or a recent SVN nightly build + (including the scratchpad jar!)</p> + + <section><title>Basic Text Extraction</title> + <p>For basic text extraction, make use of +<code>org.apache.poi.hwpf.extractor.WordExtractor</code>. It accepts an input +stream or a <code>HWPFDocument</code>. The <code>getText()</code> +method can be used to +get the text from all the paragraphs, or <code>getParagraphText()</code> +can be used to fetch the text from each paragraph in turn. The other +option is <code>getTextFromPieces()</code>, which is very fast, but +tends to return things that aren't text from the page. YMMV. + </p> + </section> + + <section><title>Specific Text Extraction</title> + <p>To get specific bits of text, first create a +<code>org.apache.poi.hwpf.HWPFDocument</code>. Fetch the range +with <code>getRange()</code>, then get paragraphs from that. You +can then get text and other properties. + </p> + </section> + + <section><title>Headers and Footers</title> + <p>To get at the headers and footers of a word document, first create a +<code>org.apache.poi.hwpf.HWPFDocument</code>. Next, you need to create a +<code>org.apache.poi.hwpf.usermodel.HeaderStores</code>, passing it your +HWPFDocument. Finally, the HeaderStores gives you access to the headers and +footers, including first / even / odd page ones if defined in your +document. Additionally, HeaderStores provides a method for removing +any macros in the text, which is helpful as many headers and footers +do end up with macros in them.</p> + </section> + + <section><title>Changing Text</title> + <p>It is possible to change the text via + <code>insertBefore()</code> and <code>insertAfter()</code> + on a <code>Range</code> object (either a <code>Range</code>, + <code>Paragraph</code> or <code>CharacterRun</code>). + It is also possible to delete a <code>Range</code>. + This code will work in many, but not all cases, and patches to + improve it are gratefully received! + </p> + </section> + + <section><title>Further Examples</title> + <p>For now, the best source of additional examples is in the unit + tests. <a + href="https://github.com/apache/poi/tree/trunk/poi-scratchpad/src/test/java/org/apache/poi/hwpf/"> + Browse the HWPF unit tests.</a> + </p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/hmef/index.xml b/src/documentation/content/xdocs/components/hmef/index.xml new file mode 100644 index 0000000000..168ba65408 --- /dev/null +++ b/src/documentation/content/xdocs/components/hmef/index.xml @@ -0,0 +1,216 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>POI-HMEF - Java API To Access Microsoft Transport Neutral Encoding Files (TNEF)</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Nick Burch" email="nick at apache dot org"/> + </authors> + </header> + + <body> + <section> + <title>Overview</title> + + <p>HMEF is the POI Project's pure Java implementation of Microsoft's + TNEF (Transport Neutral Encoding Format), aka winmail.dat, + which is used by Outlook and Exchange in some situations.</p> + <p>Currently, HMEF provides a read-only api for accessing common + message and attachment attributes, including the message body + and attachment files. In addition, it's possible to have + read-only access to all of the underlying TNEF and MAPI + attributes of the message and attachments.</p> + <p>HMEF also provides a command line tool for extracting out + the message body and attachment files from a TNEF (winmail.dat) + file.</p> + <p>Write support, both for saving changes and for creating new + files, is currently unavailable. Anyone interested in working + on these areas is advised to read the + <a href="site:guidelines">Contribution Guidelines</a> then + <a href="site:mailinglists">join the dev list</a>!</p> + + <note> + This code currently lives the + <a href="https://github.com/apache/poi/tree/trunk/poi-scratchpad/">scratchpad area</a> + of the POI Git repository. To use this component, ensure + you have the Scratchpad Jar on your classpath, or a dependency + defined on the <em>poi-scratchpad</em> artifact - the main POI + jar is not enough! See the + <a href="site:components">POI Components Map</a> + for more details. + </note> + </section> + + <section> + <title>Using HMEF to access TNEF (winmail.dat) files</title> + + <section> + <title>Easy extraction of message body and attachment files</title> + + <p>The class <em>org.apache.poi.hmef.extractor.HMEFContentsExtractor</em> + provides both command line and Java extraction. It allows the + saving of the message body (an RTF file), and all of the + attachment files, to a single directory as specified.</p> + + <p>From the command line, simply call the class specifying the + TNEF file to extract, and the directory to place the extracted + files into, eg:</p> + <source> + java -classpath poi-5.4.1.jar:poi-scratchpad-5.4.1.jar org.apache.poi.hmef.extractor.HMEFContentsExtractor winmail.dat /tmp/extracted/ + </source> + + <p>From Java, there are two method calls on the class, one to + extract the message body RTF to a file, and the other to extract + all the attachments to a directory. A typical use would be:</p> + <source> +public void extract(String winmailFilename, String directoryName) throws Exception { + HMEFContentsExtractor ext = new HMEFContentsExtractor(new File(winmailFilename)); + + File dir = new File(directoryName); + File rtf = new File(dir, "message.rtf"); + if(! dir.exists()) { + throw new FileNotFoundException("Output directory " + dir.getName() + " not found"); + } + + System.out.println("Extracting..."); + ext.extractMessageBody(rtf); + ext.extractAttachments(dir); + System.out.println("Extraction completed"); +} + </source> + </section> + + <section> + <title>Attachment attributes and contents</title> + + <p>To get at your attachments, simply call the + <em>getAttachments()</em> method on a <em>HMEFMessage</em> + instance, and you'll receive a list of all the attachments.</p> + <p>When you have a <em>org.apache.poi.hmef.Attachment</em> object, + there are several helper methods available. These will all + return the value of the appropriate underlying attachment + attributes, or null if for some reason the attribute isn't + present in your file.</p> + <ul> + <li><em>getFilename()</em> - returns the name of the attachment + file, possibly in 8.3 format</li> + <li><em>getLongFilename()</em> - returns the full name of the + attachment file</li> + <li><em>getExtension()</em> - returns the extension of the + attachment file, including the "."</li> + <li><em>getModifiedDate()</em> - returns the date that the + attachment file was last edited on</li> + <li><em>getContents()</em> - returns a byte array of the contents + of the attached file</li> + <li><em>getRenderedMetaFile()</em> - returns a byte array of + a windows meta file representation of the attached file</li> + </ul> + </section> + + <section> + <title>Message attributes and message body</title> + + <p>A <em>org.apache.poi.hmef.HMEFMessage</em> instance is created + from an <em>InputStream</em> of the underlying TNEF (winmail.dat) + file.</p> + <p>From a <em>HMEFMessage</em>, there are three main methods of + interest to call:</p> + <ul> + <li><em>getBody()</em> - returns a String containing the RTF + contents of the message body. </li> + <li><em>getSubject()</em> - returns the message subject</li> + <li><em>getAttachments()</em> - returns the list of + <em>Attachment</em> objects for the message</li> + </ul> + </section> + + <section> + <title>Low level attribute access</title> + + <p>Both Messages and Attachments contain two kinds of attributes. + These are <em>TNEFAttribute</em> and <em>MAPIAttribute</em>.</p> + <p>TNEFAttribute is specific to TNEF files in terms of the + available types and properties. In general, Attachments have a + few more useful ones of these then Messages.</p> + <p>MAPIAttributes hold standard MAPI properties and values, and + work in a similar way to <a href="../hsmf/">HSMF + (Outlook)</a> does. There are typically many of these on both + Messages and Attachments. <em>Note - see limitations</em></p> + <p>Both <em>HMEFMessage</em> and <em>Attachment</em> supports + support two different ways of getting to attributes of interest. + Firstly, they support list getters, to return all attributes + (either TNEF or MAPI). Secondly, they support specific getters by + TNEF or MAPI property.</p> + <source> +HMEFMessage msg = new HMEFMessage(new FileInputStream(file)); +for(TNEFAttribute attr : msg.getMessageAttributes()) { + System.out.println("TNEF : " + attr); +} +for(MAPIAttribute attr : msg.getMessageMAPIAttributes()) { + System.out.println("MAPI : " + attr); +} +System.out.println("Subject is " + msg.getMessageMAPIAttribute(MAPIProperty.CONVERSATION_TOPIC)); + +for(Attachment attach : msg.getAttachments()) { + for(TNEFAttribute attr : attach.getAttributes()) { + System.out.println("A.TNEF : " + attr); + } + for(MAPIAttribute attr : attach.getMAPIAttributes()) { + System.out.println("A.MAPI : " + attr); + } + System.out.println("Filename is " + attach.getAttribute(TNEFProperty.ID_ATTACHTITLE)); + System.out.println("Extension is " + attach.getMAPIAttribute(MAPIProperty.ATTACH_EXTENSION)); +} + </source> + </section> + </section> + + <section> + <title>Investigating a TNEF file</title> + + <p>To get a feel for the contents of a file, and to track down + where data of interest is stored, HMEF comes with + <a href="https://github.com/apache/poi/tree/trunk/poi-scratchpad/src/main/java/org/apache/poi/hmef/dev/">HMEFDumper</a> + to print out the contents of the file.</p> + </section> + + <section> + <title>Limitations</title> + + <p>HMEF is currently a work-in-progress, and not everything + works yet. The current limitations are:</p> + <ul> + <li>Non-standard MAPI properties from the range 0x8000 to 0x8fff + may not be being quite correctly turned into attributes. + The values show up, but the name and type may not always + be correct.</li> + <li>All testing so far has been performed on a small number of + English documents. We think we're correctly turning bytes into + Java unicode strings, but we need a few non-English sample + files in the test suite to verify this!</li> + <li>There is no support for saving changes, nor for creating new + files</li> + </ul> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/hpbf/file-format.xml b/src/documentation/content/xdocs/components/hpbf/file-format.xml new file mode 100644 index 0000000000..e23df62cc2 --- /dev/null +++ b/src/documentation/content/xdocs/components/hpbf/file-format.xml @@ -0,0 +1,197 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>POI-HPBF - A Guide to the Publisher File Format</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Nick Burch" email="nick at torchbox dot com"/> + </authors> + </header> + + <body> + <section><title>Document Streams</title> + <p> + The file is made up of a number of POIFS streams. A typical + file will be made up as follows: + </p> +<source> +Root Entry - + Objects - + (no children) + SummaryInformation <(0x05)SummaryInformation> + DocumentSummaryInformation <(0x05)DocumentSummaryInformation> + Escher - + EscherStm + EscherDelayStm + Quill - + QuillSub - + CONTENTS + CompObj <(0x01)CompObj> + Envelope + Contents + Internal <(0x03)Internal> + CompObj <(0x01)CompObj> + VBA - + (no children) +</source> + </section> + <section><title>Changing Text</title> + <p>If you make a change to the text of a file, but not change + how much text there is, then the <em>CONTENTS</em> stream + will undergo a small change, and the <em>Contents</em> stream + will undergo a large change.</p> + <p>If you make a change to the text of a file, and change the + amount of text there is, then both the <em>Contents</em> and + the <em>CONTENTS</em> streams change.</p> + </section> + <section><title>Changing Shapes</title> + <p>If you alter the size of a textbox, but make no text changes, + then both <em>Contents</em> and <em>CONTENTS</em> streams + change. There are no changes to the Escher streams.</p> + <p>If you set the background colour of a textbox, but make + no changes to the text, (to finish off)</p> + </section> + <section><title>Structure of CONTENTS</title> + <p>First we have "CHNKINK ", followed by 24 bytes.</p> + <p>Next we have 20 sequences of 24 bytes each. If the first two bytes + at 0x1800, then that sequence entry exists, but if it's 0x0000 then + the entry doesn't exist. If it does exist, we then have 4 bytes of + upper case ASCII text, followed by three little endian shorts. + The first of these seems to be the count of that type, the second is + usually 1, the third is usually zero. The we have another 4 bytes of + upper case ASCII text, normally but not always the same as the first + text. Finally, we have an unsigned little endian 32 bit offset to + the start of the data for this, then an unsigned little endian + 32 bit offset of the length of this section.</p> + <p>Normally, the first sequence entry is for TEXT, and the text data + will start at 0x200. After that is normally two or three STSH entries + (so the first short has values 0, then 1, then 2). After that it + seems to vary.</p> + <p>At 0x200 we have the text, stored as little endian 16 bit unicode.</p> + <p>After the text comes all sorts of other stuff, presumably as + described by the sequences.</p> + <p>For a contents stream of length 7168 / 0x1c00 bytes, the start + looks something like:</p> +<source> +CHNKINK // "CHNKINK " +04 00 07 00 // Normally 04 00 07 00 +13 00 00 03 // Normally ## 00 00 03 +00 02 00 00 // Normally 00 ## 00 00 +00 1c 00 00 // Normally length of the stream +f8 01 13 00 // Normally f8 01 11/13 00 +ff ff ff ff // Normally seems to be ffffffff + +18 00 +TEXT 00 00 01 00 00 00 // TEXT 0 1 0 +TEXT 00 02 00 00 d0 03 00 00 // TEXT from: 200 (512), len: 3d0 (976) +18 00 +STSH 00 00 01 00 00 00 // STSH 0 1 0 +STSH d0 05 00 00 1e 00 00 00 // STSH from: 5d0 (1488), len: 1e (30) +18 00 +STSH 01 00 01 00 00 00 // STSH 1 1 0 +STSH ee 05 00 00 b8 01 00 00 // STSH from: 5ee (1518), len: 1b8 (440) +18 00 +STSH 02 00 01 00 00 00 // STSH 2 1 0 +STSH a6 07 00 00 3c 00 00 00 // STSH from: 7a6 (1958), len: 3c (60) +18 00 +FDPP 00 00 01 00 00 00 // FDPP 0 1 0 +FDPP 00 08 00 00 00 02 00 00 // FDPP from: 800 (2048), len: 200 (512) +18 00 +FDPC 00 00 01 00 00 00 // FDPC 0 1 0 +FDPC 00 0a 00 00 00 02 00 00 // FDPC from: a00 (2560), len: 200 (512) +18 00 +FDPC 01 00 01 00 00 00 // FDPC 1 1 0 +FDPC 00 0c 00 00 00 02 00 00 // FDPC from: c00 (3072), len: 200 (512) +18 00 +SYID 00 00 01 00 00 00 // SYID 0 1 0 +SYID 00 0e 00 00 20 00 00 00 // SYID from: e00 (3584), len: 20 (32) +18 00 +SGP 00 00 01 00 00 00 // SGP 0 1 0 +SGP 20 0e 00 00 0a 00 00 00 // SGP from: e20 (3616), len: a (10) +18 00 +INK 00 00 01 00 00 00 // INK 0 1 0 +INK 2a 0e 00 00 04 00 00 00 // INK from: e2a (3626), len: 4 (4) +18 00 +BTEP 00 00 01 00 00 00 // BTEP 0 1 0 +PLC 2e 0e 00 00 18 00 00 00 // PLC from: e2e (3630), len: 18 (24) +18 00 +BTEC 00 00 01 00 00 00 // BTEC 0 1 0 +PLC 46 0e 00 00 20 00 00 00 // PLC from: e46 (3654), len: 20 (32) +18 00 +FONT 00 00 01 00 00 00 // FONT 0 1 0 +FONT 66 0e 00 00 48 03 00 00 // FONT from: e66 (3686), len: 348 (840) +18 00 +TCD 03 00 01 00 00 00 // TCD 3 1 0 +PLC ae 11 00 00 24 00 00 00 // PLC from: 11ae (4526), len: 24 (36) +18 00 +TOKN 04 00 01 00 00 00 // TOKN 4 1 0 +PLC d2 11 00 00 0a 01 00 00 // PLC from: 11d2 (4562), len: 10a (266) +18 00 +TOKN 05 00 01 00 00 00 // TOKN 5 1 0 +PLC dc 12 00 00 2a 01 00 00 // PLC from: 12dc (4828), len: 12a (298) +18 00 +STRS 00 00 01 00 00 00 // STRS 0 1 0 +PLC 06 14 00 00 46 00 00 00 // PLC from: 1406 (5126), len: 46 (70) +18 00 +MCLD 00 00 01 00 00 00 // MCLD 0 1 0 +MCLD 4c 14 00 00 16 06 00 00 // MCLD from: 144c (5196), len: 616 (1558) +18 00 +PL 00 00 01 00 00 00 // PL 0 1 0 +PL 62 1a 00 00 48 00 00 00 // PL from: 1a62 (6754), len: 48 (72) +00 00 // Blank entry follows +00 00 00 00 00 00 +00 00 00 00 00 00 00 00 +00 00 00 00 00 00 00 00 + +(the text will then start) +</source> + <p>We think that the first 4 bytes of text describes the + the function of the data at the offset. The first short is + then the count of that type, eg the 2nd will have 1. We + think that the second 4 bytes of text describes the format + of data block at the offset. The format of the text block + is easy, but we're still trying to figure out the others.</p> + + <section><title>Structure of TEXT bit</title> + <p>This is very simple. All the text for the document is + stored in a single bit of the Quill CONTENTS. The text + is stored as little endian 16 bit unicode strings.</p> + </section> + <section><title>Structure of PLC bit</title> + <p>The first four bytes seem to hold the count of the + entries in the bit, and the second four bytes seem to hold + the type. There is then some pre-data, and then data for + each of the entries, the exact format dependant on the type.</p> + <p>Type 0 has 4 2 byte unsigned ints, then a pair of 2 byte + unsigned ints for each entry.</p> + <p>Type 4 has 4 2 byte unsigned ints, then a pair of 4 byte + unsigned ints for each entry.</p> + <p>Type 8 has 7 2 byte unsigned ints, then a pair of 4 byte + unsigned ints for each entry.</p> + <p>Type 12 holds hyperlinks, and is very much more complex. + See <a href="https://github.com/apache/poi/tree/trunk/poi-scratchpad/src/main/java/org/apache/poi/hpbf/model/qcbits/QCPLCBit.java?view=markup"><code>org.apache.poi.hpbf.model.qcbits.QCPLCBit</code></a> + for our best guess as to how the contents match up.</p> + </section> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/hpbf/index.xml b/src/documentation/content/xdocs/components/hpbf/index.xml new file mode 100644 index 0000000000..92e4693d3e --- /dev/null +++ b/src/documentation/content/xdocs/components/hpbf/index.xml @@ -0,0 +1,77 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>POI-HPBF - Java API To Access Microsoft Publisher Format Files</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Nick Burch" email="nick at apache dot org"/> + </authors> + </header> + + <body> + <section> + <title>Overview</title> + + <p>HPBF is the POI Project's pure Java implementation of the + Publisher file format.</p> + <p>Currently, HPBF is in an early stage, whilst we try to + figure out the file format. So far, we have basic text + extraction support, and are able to read some parts within + the file. Writing is not yet supported, as we are unable + to make sense of the Contents stream, which we think has + lots of offsets to other parts of the file.</p> + <p>Our initial aim is to produce a text extractor for the format + (now done), and be able to extract hyperlinks from within + the document (partly supported). Additional low level + code to process the file format may follow, if there + is demand and developer interest warrants it.</p> + <p>Text Extraction is available via the + <em>org.apache.poi.hpbf.extractor.PublisherTextExtractor</em> + class.</p> + <p>At this time, there is no <em>usermodel</em> api or similar. + There is only low level support for certain parts of + the file, but by no means all of it.</p> + <p>Our current understanding of the file format is documented + <a href="site:hpbformat">here</a>.</p> + <p>As of 2017, we are unaware of a public format specification for + Microsoft Publisher .pub files. This format was not included in + the Microsoft Open Specifications Promise with the rest of the + Microsoft Office file formats. + As of <a href="https://social.msdn.microsoft.com/Forums/en-US/63dc6c4e-d6b2-4873-97dd-139ddb304e24/what-about-publisher-file-format?forum=os_binaryfile">2009</a> and <a href="https://social.msdn.microsoft.com/Forums/en-US/a5f55c72-5378-4dc9-944a-9973a12bfaa7/reading-viso-vsdfiles-and-publisher-pubfiles-without-office?forum=os_binaryfile">2016</a>, Microsoft had no plans to document the .pub file format. + If this changes in the future, perhaps we will see a spec published + on the <a href="https://msdn.microsoft.com/en-us/library/cc313105(v=office.12).aspx">Microsoft Office File Format Open Specification Technical Documentation</a>. + </p> + + <note> + This code currently lives the + <a href="https://github.com/apache/poi/tree/trunk/poi-scratchpad/">scratchpad area</a> + of the POI Git repository. To use this component, ensure + you have the Scratchpad Jar on your classpath, or a dependency + defined on the <em>poi-scratchpad</em> artifact - the main POI + jar is not enough! See the + <a href="site:components">POI Components Map</a> + for more details. + </note> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/hpsf/how-to.xml b/src/documentation/content/xdocs/components/hpsf/how-to.xml new file mode 100644 index 0000000000..a2c7c61acf --- /dev/null +++ b/src/documentation/content/xdocs/components/hpsf/how-to.xml @@ -0,0 +1,1477 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>HPSF HOW-TO</title> + <authors> + <person name="Rainer Klute" email="klute@apache.org"/> + </authors> + </header> + <body> + <section><title>How To Use the HPSF API</title> + + <p>This HOW-TO is organized in four sections. You should read them + sequentially because the later sections build upon the earlier ones.</p> + + <ol> + <li> + The <a href="#sec1">first section</a> explains how to <strong>read + the most important standard properties</strong> of a Microsoft Office + document. Standard properties are things like title, author, creation + date etc. It is quite likely that you will find here what you need and + don't have to read the other sections. + </li> + + <li> + The <a href="#sec2">second section</a> goes a small step + further and focuses on <strong>reading additional standard + properties</strong>. It also talks about <strong>exceptions</strong> that + may be thrown when dealing with HPSF and shows how you can <strong>read + properties of embedded objects</strong>. + </li> + + <li> + The <a href="#sec3">third section</a> explains how to <strong>write + standard properties</strong>. HPSF provides some high-level classes and + methods which make writing of standard properties easy. They are based on + the low-level writing functions explained in the <a href="#sec3">fifth + section</a>. + </li> + + <li> + The <a href="#sec4">fourth section</a> tells how to <strong>read + non-standard properties</strong>. Non-standard properties are + application-specific triples consisting of an ID, a type, and a value. + </li> + + <li> + The <a href="#sec5">fifth section</a> tells you how to <strong>write + property set streams</strong> using HPSF's low-level methods. You have to + understand the <a href="#sec3">fourth section</a> before you should + think about low-level writing properties. Check the Javadoc API + documentation to find out about the details! + </li> + </ol> + + <note><strong>Please note:</strong> HPSF's writing functionality is + <strong>not</strong> present in POI releases up to and including 2.5. In + order to write properties you have to download a 3.0.x POI release, + or retrieve the POI development version from the <a + href="site:git">Git repository</a>.</note> + + + + <anchor id="sec1"/> + <section><title>Reading Standard Properties</title> + + <note>This section explains how to read the most important standard + properties of a Microsoft Office document. Standard properties are things + like title, author, creation date etc. This section introduces the + <strong>summary information stream</strong> which is used to keep these + properties. Chances are that you will find here what you need and don't + have to read the other sections.</note> + + <p>If all you are interested in is getting the textual content of + all the document properties, such as for full text indexing, then + take a look at + <code>org.apache.poi.hpsf.extractor.HPSFPropertiesExtractor</code>. However, + if you want full access to the properties, please read on!</p> + + <p>The first thing you should understand is that a Microsoft Office file is + not one large bunch of bytes but has an internal filesystem structure with + files and directories. You can access these files and directories using + the <a href="../poifs/index.html">POI filesystem (POIFS)</a> + provides. A file or document in a POI filesystem is also called a + <strong>stream</strong> - The properties of, say, an Excel document are + stored apart of the actual spreadsheet data in separate streams. The good + new is that this separation makes the properties independent of the + concrete Microsoft Office file. In the following text we will always say + "POI filesystem" instead of "Microsoft Office file" because a POI + filesystem is not necessarily created by or for a Microsoft Office + application, because it is shorter, and because we want to avoid the name + of That Redmond Company.</p> + + <p>The following example shows how to read the "title" property. Reading + other properties is similar. Consider the API documentation of the class + <code>org.apache.poi.hpsf.SummaryInformation</code> to learn which methods + are available.</p> + + <p>The standard properties this section focuses on can be found in a + document called <em>\005SummaryInformation</em> located in the root of the + POI filesystem. The notation <em>\005</em> in the document's name means + the character with a decimal value of 5. In order to read the "title" + property, an application has to perform the following steps:</p> + + <ol> + <li> + Open the document <em>\005SummaryInformation</em> located in the root + of the POI filesystem. + </li> + <li> + Create an instance of the class <code>SummaryInformation</code> from + that document. + </li> + <li> + Call the <code>SummaryInformation</code> instance's + <code>getTitle()</code> method. + </li> + </ol> + + <p>Sounds easy, doesn't it? Here are the steps in detail.</p> + + + <section><title>Open the document \005SummaryInformation in the root of the + POI filesystem</title> + + <p>An application that wants to open a document in a POI filesystem + (POIFS) proceeds as shown by the following code fragment. The full + source code of the sample application is available in the + <em>examples</em> section of the POI source tree as + <em>ReadTitle.java</em>.</p> + + <source> +import java.io.*; +import org.apache.poi.hpsf.*; +import org.apache.poi.poifs.eventfilesystem.*; + +// ... + +public static void main(String[] args) + throws IOException +{ + final String filename = args[0]; + POIFSReader r = new POIFSReader(); + r.registerListener(new MyPOIFSReaderListener(), + "\005SummaryInformation"); + r.read(new FileInputStream(filename)); +}</source> + + <p>The first interesting statement is</p> + + <source>POIFSReader r = new POIFSReader();</source> + + <p>It creates a + <code>org.apache.poi.poifs.eventfilesystem.POIFSReader</code> instance + which we shall need to read the POI filesystem. Before the application + actually opens the POI filesystem we have to tell the + <code>POIFSReader</code> which documents we are interested in. In this + case the application should do something with the document + <em>\005SummaryInformation</em>.</p> + + <source> +r.registerListener(new MyPOIFSReaderListener(), + "\005SummaryInformation");</source> + + <p>This method call registers a + <code>org.apache.poi.poifs.eventfilesystem.POIFSReaderListener</code> + with the <code>POIFSReader</code>. The <code>POIFSReaderListener</code> + interface specifies the method <code>processPOIFSReaderEvent()</code> + which processes a document. The class + <code>MyPOIFSReaderListener</code> implements the + <code>POIFSReaderListener</code> and thus the + <code>processPOIFSReaderEvent()</code> method. The eventing POI + filesystem calls this method when it finds the + <em>\005SummaryInformation</em> document. In the sample application + <code>MyPOIFSReaderListener</code> is a static class in the + <em>ReadTitle.java</em> source file.</p> + + <p>Now everything is prepared and reading the POI filesystem can + start:</p> + + <source>r.read(new FileInputStream(filename));</source> + + <p>The following source code fragment shows the + <code>MyPOIFSReaderListener</code> class and how it retrieves the + title.</p> + + <source> +static class MyPOIFSReaderListener implements POIFSReaderListener +{ + public void processPOIFSReaderEvent(POIFSReaderEvent event) + { + SummaryInformation si = null; + try + { + si = (SummaryInformation) + PropertySetFactory.create(event.getStream()); + } + catch (Exception ex) + { + throw new RuntimeException + ("Property set stream \"" + + event.getPath() + event.getName() + "\": " + ex); + } + final String title = si.getTitle(); + if (title != null) + System.out.println("Title: \"" + title + "\""); + else + System.out.println("Document has no title."); + } +} +</source> + + <p>The line</p> + + <source>SummaryInformation si = null;</source> + + <p>declares a <code>SummaryInformation</code> variable and initializes it + with <code>null</code>. We need an instance of this class to access the + title. The instance is created in a <code>try</code> block:</p> + + <source>si = (SummaryInformation) + PropertySetFactory.create(event.getStream());</source> + + <p>The expression <code>event.getStream()</code> returns the input stream + containing the bytes of the property set stream named + <em>\005SummaryInformation</em>. This stream is passed into the + <code>create</code> method of the factory class + <code>org.apache.poi.hpsf.PropertySetFactory</code> which returns + a <code>org.apache.poi.hpsf.PropertySet</code> instance. It is more or + less safe to cast this result to <code>SummaryInformation</code>, a + convenience class with methods like <code>getTitle()</code>, + <code>getAuthor()</code> etc.</p> + + <p>The <code>PropertySetFactory.create()</code> method may throw all sorts + of exceptions. We'll deal with them in the next sections. For now we just + catch all exceptions and throw a <code>RuntimeException</code> + containing the message text of the origin exception.</p> + + <p>If all goes well, the sample application retrieves the title and prints + it to the standard output. As you can see you must be prepared for the + case that the POI filesystem does not have a title.</p> + + <source>final String title = si.getTitle(); +if (title != null) + System.out.println("Title: \"" + title + "\""); +else + System.out.println("Document has no title.");</source> + + <p>Please note that a POI filesystem does not necessarily contain the + <em>\005SummaryInformation</em> stream. The documents created by the + Microsoft Office suite have one, as far as I know. However, an Excel + spreadsheet exported from StarOffice 5.2 won't have a + <em>\005SummaryInformation</em> stream. In this case the applications + won't throw an exception but simply does not call the + <code>processPOIFSReaderEvent</code> method. You have been warned!</p> + </section> + </section> + + <anchor id="sec2"/> + <section><title>Additional Standard Properties, Exceptions And Embedded + Objects</title> + + <note>This section focusses on reading additional standard properties which + are kept in the <strong>document summary information</strong> stream. It + also talks about exceptions that may be thrown when dealing with HPSF and + shows how you can read properties of embedded objects.</note> + + <p>A couple of <strong>additional standard properties</strong> are not + contained in the <em>\005SummaryInformation</em> stream explained + above. Examples for such properties are a document's category or the + number of multimedia clips in a PowerPoint presentation. Microsoft has + invented an additional stream named + <em>\005DocumentSummaryInformation</em> to hold these properties. With two + minor exceptions you can proceed exactly as described above to read the + properties stored in <em>\005DocumentSummaryInformation</em>:</p> + + <ul> + <li>Instead of <em>\005SummaryInformation</em> use + <em>\005DocumentSummaryInformation</em> as the stream's name.</li> + <li>Replace all occurrences of the class + <code>SummaryInformation</code> by + <code>DocumentSummaryInformation</code>.</li> + </ul> + + <p>And of course you cannot call <code>getTitle()</code> because + <code>DocumentSummaryInformation</code> has different query methods, + e.g. <code>getCategory</code>. See the Javadoc API documentation for the + details.</p> + + <p>In the previous section the application simply caught all + <strong>exceptions</strong> and was in no way interested in any + details. However, a real application will likely want to know what went + wrong and act appropriately. Besides any I/O exceptions there are three + HPSF resp. POI specific exceptions you should know about:</p> + + <dl> + <dt><code>NoPropertySetStreamException</code>:</dt> + <dd> + This exception is thrown if the application tries to create a + <code>PropertySet</code> instance from a stream that is not a + property set stream. (<code>SummaryInformation</code> and + <code>DocumentSummaryInformation</code> are subclasses of + <code>PropertySet</code>.) A faulty property set stream counts as not + being a property set stream at all. An application should be prepared to + deal with this case even if it opens streams named + <em>\005SummaryInformation</em> or + <em>\005DocumentSummaryInformation</em>. These are just names. A + stream's name by itself does not ensure that the stream contains the + expected contents and that this contents is correct. + </dd> + + <dt><code>UnexpectedPropertySetTypeException</code></dt> + <dd>This exception is thrown if a certain type of property set is + expected somewhere (e.g. a <code>SummaryInformation</code> or + <code>DocumentSummaryInformation</code>) but the provided property + set is not of that type.</dd> + + <dt><code>MarkUnsupportedException</code></dt> + <dd>This exception is thrown if an input stream that is to be parsed + into a property set does not support the + <code>InputStream.mark(int)</code> operation. The POI filesystem uses + the <code>DocumentInputStream</code> class which does support this + operation, so you are safe here. However, if you read a property set + stream from another kind of input stream things may be + different.</dd> + </dl> + + <p>Many Microsoft Office documents contain <strong>embedded + objects</strong>, for example an Excel sheet within a Word + document. Embedded objects may have property sets of their own. An + application can open these property set streams as described above. The + only difference is that they are not located in the POI filesystem's root + but in a <strong>nested directory</strong> instead. Just register a + <code>POIFSReaderListener</code> for the property set streams you are + interested in.</p> + </section> + + + + <anchor id="sec3"/> + <section><title>Writing Standard Properties</title> + + <note>This section explains how to <strong>write standard + properties</strong>. HPSF provides some high-level classes and methods + which make writing of standard properties easy. They are based on the + low-level writing functions explained in <a href="#sec4">another + section</a>.</note> + + <p>As explained above, standard properties are located in the summary + information and document summary information streams of typical POI + filesystems. You have already learned about the classes + <code>SummaryInformation</code> and + <code>DocumentSummaryInformation</code> and their <code>get...()</code> + methods for reading standard properties. These classes also provide + <code>set...()</code> methods for writing properties.</p> + + <p>After setting properties in <code>SummaryInformation</code> or + <code>DocumentSummaryInformation</code> you have to write them to a disk + file. The following sample program shows how you can</p> + + <ol> + <li>read a disk file into a POI filesystem,</li> + <li>read the document summary information from the POI filesystem,</li> + <li>set a property to a new value,</li> + <li>write the modified document summary information back to the POI + filesystem, and</li> + <li>write the POI filesystem to a disk file.</li> + </ol> + + <p>The complete source code of this program is available as + <em>ModifyDocumentSummaryInformation.java</em> in the <em>examples</em> + section of the POI source tree.</p> + + <note>Dealing with the summary information stream is analogous to handling + the document summary information and therefore does not need to be + explained here in detailed. See the HPSF API documentation to learn about + the <code>set...()</code> methods of the class + <code>SummaryInformation</code>.</note> + + <p>The first step is to read the POI filesystem into memory:</p> + + <source>InputStream is = new FileInputStream(poiFilesystem); +POIFSFileSystem poifs = new POIFSFileSystem(is); +is.close();</source> + + <p>The code snippet above assumes that the variable + <code>poiFilesystem</code> holds the name of a disk file. It reads the + file from an input stream and creates a <code>POIFSFileSystem</code> + object in memory. After having read the file, the input stream should be + closed as shown.</p> + + <p>In order to read the document summary information stream the application + must open the element <em>\005DocumentSummaryInformation</em> in the POI + filesystem's root directory. However, the POI filesystem does not + necessarily contain a document summary information stream, and the + application should be able to deal with that situation. The following + code does so by creating a new <code>DocumentSummaryInformation</code> if + there is none in the POI filesystem:</p> + + <source>DirectoryEntry dir = poifs.getRoot(); +DocumentSummaryInformation dsi; +try +{ + DocumentEntry dsiEntry = (DocumentEntry) + dir.getEntry(DocumentSummaryInformation.DEFAULT_STREAM_NAME); + DocumentInputStream dis = new DocumentInputStream(dsiEntry); + PropertySet ps = new PropertySet(dis); + dis.close(); + dsi = new DocumentSummaryInformation(ps); +} +catch (FileNotFoundException ex) +{ + /* There is no document summary information. We have to create a + * new one. */ + dsi = PropertySetFactory.newDocumentSummaryInformation(); +} + </source> + + <p>In the source code above the statement</p> + + <source>DirectoryEntry dir = poifs.getRoot();</source> + + <p>gets hold of the POI filesystem's root directory as a + <code>DirectoryEntry</code>. The <code>getEntry()</code> method of this + class is used to access a file or directory entry in a directory. However, + if the file to be opened does not exist, a + <code>FileNotFoundException</code> will be thrown. Therefore opening the + document summary information entry should be done in a <code>try</code> + block:</p> + + <source> DocumentEntry dsiEntry = (DocumentEntry) + dir.getEntry(DocumentSummaryInformation.DEFAULT_STREAM_NAME);</source> + + <p><code>DocumentSummaryInformation.DEFAULT_STREAM_NAME</code> represents + the string "\005DocumentSummaryInformation", i.e. the standard name of a + document summary information stream. If this stream exists, the + <code>getEntry()</code> method returns a <code>DocumentEntry</code>. To + read the <code>DocumentEntry</code>'s contents, create a + <code>DocumentInputStream</code>:</p> + + <source> DocumentInputStream dis = new DocumentInputStream(dsiEntry);</source> + + <p>Up to this point we have used POI's <a + href="../poifs/index.html">POIFS component</a>. Now HPSF enters the + stage. A property set is created from the input stream's data:</p> + + <source> PropertySet ps = new PropertySet(dis); + dis.close(); + dsi = new DocumentSummaryInformation(ps); </source> + + <p>If the data really constitutes a property set, a + <code>PropertySet</code> object is created. Otherwise a + <code>NoPropertySetStreamException</code> is thrown. After having read the + data from the input stream the latter should be closed.</p> + + <p>Since we know - or at least hope - that the stream named + "\005DocumentSummaryInformation" is not just any property set but really + contains the document summary information, we try to create a new + <code>DocumentSummaryInformation</code> from the property set. If the + stream is not document summary information stream the sample application + fails with a <code>UnexpectedPropertySetTypeException</code>.</p> + + <p>If the POI document does not contain a document summary information + stream, we can create a new one in the <code>catch</code> clause. The + <code>PropertySetFactory</code>'s method + <code>newDocumentSummaryInformation()</code> establishes a new and empty + <code>DocumentSummaryInformation</code> instance:</p> + + <source> dsi = PropertySetFactory.newDocumentSummaryInformation();</source> + + <p>Whether we read the document summary information from the POI filesystem + or created it from scratch, in either case we now have a + <code>DocumentSummaryInformation</code> instance we can write to. Writing + is quite simple, as the following line of code shows:</p> + + <source>dsi.setCategory("POI example");</source> + + <p>This statement sets the "category" property to "POI example". Any + former "category" value will be lost. If there hasn't been a "category" + property yet, a new one will be created.</p> + + <p><code>DocumentSummaryInformation</code> of course has methods to set the + other standard properties, too - look into the API documentation to see + all of them.</p> + + <p>Once all properties are set as needed, they should be stored into the + file on disk. The first step is to write the + <code>DocumentSummaryInformation</code> into the POI filesystem:</p> + + <source>dsi.write(dir, DocumentSummaryInformation.DEFAULT_STREAM_NAME);</source> + + <p>The <code>DocumentSummaryInformation</code>'s <code>write()</code> + method takes two parameters: The first is the <code>DirectoryEntry</code> + in the POI filesystem, the second is the name of the stream to create in + the directory. If this stream already exists, it will be overwritten.</p> + + <note>If you not only modified the document summary information but also + the summary information you have to write both of them to the POI + filesystem.</note> + + <p>Still the POI filesystem is a data structure in memory only and must be + written to a disk file to make it permanent. The following lines write + back the POI filesystem to the file it was read from before. Please note + that in production-quality code you should never write directly to the + origin file, because in case of an error everything would be lost. Here it + is done this way to keep the example short.</p> + + <source>OutputStream out = new FileOutputStream(poiFilesystem); +poifs.writeFilesystem(out); +out.close();</source> + + <section><title>User-Defined Properties</title> + + <p>If you compare the source code excerpts above with the file containing + the full source code, you will notice that I left out some following + lines of code. The are dealing with the special topic of custom + properties.</p> + + <source>DocumentSummaryInformation dsi = ... +... +CustomProperties customProperties = dsi.getCustomProperties(); +if (customProperties == null) + customProperties = new CustomProperties(); + +/* Insert some custom properties into the container. */ +customProperties.put("Key 1", "Value 1"); +customProperties.put("Schlssel 2", "Wert 2"); +customProperties.put("Sample Number", new Integer(12345)); +customProperties.put("Sample Boolean", new Boolean(true)); +customProperties.put("Sample Date", new Date()); + +/* Read a custom property. */ +Object value = customProperties.get("Sample Number"); + +/* Write the custom properties back to the document summary + * information. */ +dsi.setCustomProperties(customProperties);</source> + + <p>Custom properties are properties the user can define himself. Using for + example Microsoft Word he can define these extra properties and give + each of them a <strong>name</strong>, a <strong>type</strong> and a + <strong>value</strong>. The custom properties are stored in the document + information summary along with the standard properties.</p> + + <p>The source code example shows how to retrieve the custom properties + as a whole from a <code>DocumentSummaryInformation</code> instance using + the <code>getCustomProperties()</code> method. The result is a + <code>CustomProperties</code> instance or <code>null</code> if no + user-defined properties exist.</p> + + <p>Since <code>CustomProperties</code> implements the <code>Map</code> + interface you can read and write properties with the usual + <code>Map</code> methods. However, <code>CustomProperties</code> poses + some restrictions on the types of keys and values.</p> + + <ul> + <li>The <strong>key</strong> is a string.</li> + <li>The <strong>value</strong> is one of <code>String</code>, + <code>Boolean</code>, <code>Long</code>, <code>Integer</code>, + <code>Short</code>, or <code>java.util.Date</code>.</li> + </ul> + + <p>The <code>CustomProperties</code> class has been designed for easy + access using just keys and values. The underlying Microsoft-specific + custom properties data structure is more complicated. However, it does + not provide noteworthy additional benefits. It is possible to have + multiple properties with the same name or properties without a + name at all. When reading custom properties from a document summary + information stream, the <code>CustomProperties</code> class ignores + properties without a name and keeps only the "last" (whatever that means) + of those properties having the same name. You can find out whether a + <code>CustomProperties</code> instance dropped any properties with the + <code>isPure()</code> method.</p> + + <p>You can read and write the full spectrum of custom properties with + HPSF's low-level methods. They are explained in the <a + href="#sec4">next section</a>.</p> + </section> + </section> + + + + <anchor id="sec4"/> + <section><title>Reading Non-Standard Properties</title> + + <note>This section tells how to read non-standard properties. Non-standard + properties are application-specific ID/type/value triples.</note> + + <section><title>Overview</title> + <p>Now comes the real hardcode stuff. As mentioned above, + <code>SummaryInformation</code> and + <code>DocumentSummaryInformation</code> are just special cases of the + general concept of a property set. This concept says that a + <strong>property set</strong> consists of properties and that each + <strong>property</strong> is an entity with an <strong>ID</strong>, a + <strong>type</strong>, and a <strong>value</strong>.</p> + + <p>Okay, that was still rather easy. However, to make things more + complicated, Microsoft in its infinite wisdom decided that a property set + shalt be broken into one or more <strong>sections</strong>. Each section + holds a bunch of properties. But since that's still not complicated + enough, a section may have an optional <strong>dictionary</strong> that + maps property IDs to <strong>property names</strong> - we'll explain + later what that means.</p> + + <p>The procedure to get to the properties is the following:</p> + + <ol> + <li>Use the <strong><code>PropertySetFactory</code></strong> class to + create a <code>PropertySet</code> object from a property set stream. If + you don't know whether an input stream is a property set stream, just + try to call <code>PropertySetFactory.create(java.io.InputStream)</code>: + You'll either get a <code>PropertySet</code> instance returned or an + exception is thrown.</li> + + <li>Call the <code>PropertySet</code>'s method <code>getSections()</code> + to get the sections contained in the property set. Each section is + an instance of the <code>Section</code> class.</li> + + <li>Each section has a format ID. The format ID of the first section in a + property set determines the property set's type. For example, the first + (and only) section of the summary information property set has a format + ID of <code>F29F85E0-4FF9-1068-AB-91-08-00-2B-27-B3-D9</code>. You can + get the format ID with <code>Section.getFormatID()</code>.</li> + + <li>The properties contained in a <code>Section</code> can be retrieved + with <code>Section.getProperties()</code>. The result is an array of + <code>Property</code> instances.</li> + + <li>A property has a name, a type, and a value. The <code>Property</code> + class has methods to retrieve them.</li> + </ol> + </section> + + <section><title>A Sample Application</title> + <p>Let's have a look at a sample Java application that dumps all property + set streams contained in a POI file system. The full source code of this + program can be found as <em>ReadCustomPropertySets.java</em> in the + <em>examples</em> area of the POI source code tree. Here are the key + sections:</p> + + <source>import java.io.*; +import java.util.*; +import org.apache.poi.hpsf.*; +import org.apache.poi.poifs.eventfilesystem.*; +import org.apache.poi.util.HexDump;</source> + + <p>The most important package the application needs is + <code>org.apache.poi.hpsf.*</code>. This package contains the HPSF + classes. Most classes named below are from the HPSF package. Of course we + also need the POIFS event file system's classes and <code>java.io.*</code> + since we are dealing with POI I/O. From the <code>java.util</code> package + we use the <code>List</code> and <code>Iterator</code> class. The class + <code>org.apache.poi.util.HexDump</code> provides a methods to dump byte + arrays as nicely formatted strings.</p> + + <source>public static void main(String[] args) + throws IOException +{ + final String filename = args[0]; + POIFSReader r = new POIFSReader(); + + /* Register a listener for *all* documents. */ + r.registerListener(new MyPOIFSReaderListener()); + r.read(new FileInputStream(filename)); +}</source> + + <p>The <code>POIFSReader</code> is set up in a way that the listener + <code>MyPOIFSReaderListener</code> is called on every file in the POI file + system.</p> + </section> + + <section><title>The Property Set</title> + <p>The listener class tries to create a <code>PropertySet</code> from each + stream using the <code>PropertySetFactory.create()</code> method:</p> + + <source>static class MyPOIFSReaderListener implements POIFSReaderListener +{ + public void processPOIFSReaderEvent(POIFSReaderEvent event) + { + PropertySet ps = null; + try + { + ps = PropertySetFactory.create(event.getStream()); + } + catch (NoPropertySetStreamException ex) + { + out("No property set stream: \"" + event.getPath() + + event.getName() + "\""); + return; + } + catch (Exception ex) + { + throw new RuntimeException + ("Property set stream \"" + + event.getPath() + event.getName() + "\": " + ex); + } + + /* Print the name of the property set stream: */ + out("Property set stream \"" + event.getPath() + + event.getName() + "\":");</source> + + <p>Creating the <code>PropertySet</code> is done in a <code>try</code> + block, because not each stream in the POI file system contains a property + set. If it is some other file, the + <code>PropertySetFactory.create()</code> throws a + <code>NoPropertySetStreamException</code>, which is caught and + logged. Then the program continues with the next stream. However, all + other types of exceptions cause the program to terminate by throwing a + runtime exception. If all went well, we can print the name of the property + set stream.</p> + </section> + + <section><title>The Sections</title> + <p>The next step is to print the number of sections followed by the + sections themselves:</p> + + <source>/* Print the number of sections: */ +final long sectionCount = ps.getSectionCount(); +out(" No. of sections: " + sectionCount); + +/* Print the list of sections: */ +List sections = ps.getSections(); +int nr = 0; +for (Iterator i = sections.iterator(); i.hasNext();) +{ + /* Print a single section: */ + Section sec = (Section) i.next(); + + // See below for the complete loop body. +}</source> + + <p>The <code>PropertySet</code>'s method <code>getSectionCount()</code> + returns the number of sections.</p> + + <p>To retrieve the sections, use the <code>getSections()</code> + method. This method returns a <code>java.util.List</code> containing + instances of the <code>Section</code> class in their proper order.</p> + + <p>The sample code shows a loop that retrieves the <code>Section</code> + objects one by one and prints some information about each one. Here is + the complete body of the loop:</p> + + <source>/* Print a single section: */ +Section sec = (Section) i.next(); +out(" Section " + nr++ + ":"); +String s = hex(sec.getFormatID().getBytes()); +s = s.substring(0, s.length() - 1); +out(" Format ID: " + s); + +/* Print the number of properties in this section. */ +int propertyCount = sec.getPropertyCount(); +out(" No. of properties: " + propertyCount); + +/* Print the properties: */ +Property[] properties = sec.getProperties(); +for (int i2 = 0; i2 < properties.length; i2++) +{ + /* Print a single property: */ + Property p = properties[i2]; + int id = p.getID(); + long type = p.getType(); + Object value = p.getValue(); + out(" Property ID: " + id + ", type: " + type + + ", value: " + value); +}</source> + </section> + + <section><title>The Section's Format ID</title> + <p>The first method called on the <code>Section</code> instance is + <code>getFormatID()</code>. As explained above, the format ID of the + first section in a property set determines the type of the property + set. Its type is <code>ClassID</code> which is essentially a sequence of + 16 bytes. A real application using its own type of a custom property set + should have defined a unique format ID and, when reading a property set + stream, should check the format ID is equal to that unique format ID. The + sample program just prints the format ID it finds in a section:</p> + + <source>String s = hex(sec.getFormatID().getBytes()); +s = s.substring(0, s.length() - 1); +out(" Format ID: " + s);</source> + + <p>As you can see, the <code>getFormatID()</code> method returns a + <code>ClassID</code> object. An array containing the bytes can be + retrieved with <code>ClassID.getBytes()</code>. In order to get a nicely + formatted printout, the sample program uses the <code>hex()</code> helper + method which in turn uses the POI utility class <code>HexDump</code> in + the <code>org.apache.poi.util</code> package. Another helper method is + <code>out()</code> which just saves typing + <code>System.out.println()</code>.</p> + </section> + + <section><title>The Properties</title> + <p>Before getting the properties, it is possible to find out how many + properties are available in the section via the + <code>Section.getPropertyCount()</code>. The sample application uses this + method to print the number of properties to the standard output:</p> + + <source>int propertyCount = sec.getPropertyCount(); +out(" No. of properties: " + propertyCount);</source> + + <p>Now its time to get to the properties themselves. You can retrieve a + section's properties with the method + <code>Section.getProperties()</code>:</p> + + <source>Property[] properties = sec.getProperties();</source> + + <p>As you can see the result is an array of <code>Property</code> + objects. This class has three methods to retrieve a property's ID, its + type, and its value. The following code snippet shows how to call + them:</p> + + <source>for (int i2 = 0; i2 < properties.length; i2++) +{ + /* Print a single property: */ + Property p = properties[i2]; + int id = p.getID(); + long type = p.getType(); + Object value = p.getValue(); + out(" Property ID: " + id + ", type: " + type + + ", value: " + value); +}</source> + </section> + + <section><title>Sample Output</title> + <p>The output of the sample program might look like the following. It + shows the summary information and the document summary information + property sets of a Microsoft Word document. However, unlike the first and + second section of this HOW-TO the application does not have any code + which is specific to the <code>SummaryInformation</code> and + <code>DocumentSummaryInformation</code> classes.</p> + + <source>Property set stream "/SummaryInformation": + No. of sections: 1 + Section 0: + Format ID: 00000000 F2 9F 85 E0 4F F9 10 68 AB 91 08 00 2B 27 B3 D9 ....O..h....+'.. + No. of properties: 17 + Property ID: 1, type: 2, value: 1252 + Property ID: 2, type: 30, value: Titel + Property ID: 3, type: 30, value: Thema + Property ID: 4, type: 30, value: Rainer Klute (Autor) + Property ID: 5, type: 30, value: Test (Stichwrter) + Property ID: 6, type: 30, value: This is a document for testing HPSF + Property ID: 7, type: 30, value: Normal.dot + Property ID: 8, type: 30, value: Unknown User + Property ID: 9, type: 30, value: 3 + Property ID: 18, type: 30, value: Microsoft Word 9.0 + Property ID: 12, type: 64, value: Mon Jan 01 00:59:25 CET 1601 + Property ID: 13, type: 64, value: Thu Jul 18 16:22:00 CEST 2002 + Property ID: 14, type: 3, value: 1 + Property ID: 15, type: 3, value: 20 + Property ID: 16, type: 3, value: 93 + Property ID: 19, type: 3, value: 0 + Property ID: 17, type: 71, value: [B@13582d +Property set stream "/DocumentSummaryInformation": + No. of sections: 2 + Section 0: + Format ID: 00000000 D5 CD D5 02 2E 9C 10 1B 93 97 08 00 2B 2C F9 AE ............+,.. + No. of properties: 14 + Property ID: 1, type: 2, value: 1252 + Property ID: 2, type: 30, value: Test + Property ID: 14, type: 30, value: Rainer Klute (Manager) + Property ID: 15, type: 30, value: Rainer Klute IT-Consulting GmbH + Property ID: 5, type: 3, value: 3 + Property ID: 6, type: 3, value: 2 + Property ID: 17, type: 3, value: 111 + Property ID: 23, type: 3, value: 592636 + Property ID: 11, type: 11, value: false + Property ID: 16, type: 11, value: false + Property ID: 19, type: 11, value: false + Property ID: 22, type: 11, value: false + Property ID: 13, type: 4126, value: [B@56a499 + Property ID: 12, type: 4108, value: [B@506411 + Section 1: + Format ID: 00000000 D5 CD D5 05 2E 9C 10 1B 93 97 08 00 2B 2C F9 AE ............+,.. + No. of properties: 7 + Property ID: 0, type: 0, value: {6=Test-JaNein, 5=Test-Zahl, 4=Test-Datum, 3=Test-Text, 2=_PID_LINKBASE} + Property ID: 1, type: 2, value: 1252 + Property ID: 2, type: 65, value: [B@c9ba38 + Property ID: 3, type: 30, value: This is some text. + Property ID: 4, type: 64, value: Wed Jul 17 00:00:00 CEST 2002 + Property ID: 5, type: 3, value: 27 + Property ID: 6, type: 11, value: true +No property set stream: "/WordDocument" +No property set stream: "/CompObj" +No property set stream: "/1Table"</source> + + <p>There are some interesting items to note:</p> + + <ul> + <li>The first property set (summary information) consists of a single + section, the second property set (document summary information) consists + of two sections.</li> + + <li>Each section type (identified by its format ID) has its own domain of + property ID. For example, in the second property set the properties with + ID 2 have different meanings in the two section. By the way, the format + IDs of these sections are <strong>not</strong> equal, but you have to + look hard to find the difference.</li> + + <li>The properties are not in any particular order in the section, + although they slightly tend to be sorted by their IDs.</li> + </ul> + </section> + + <section><title>Property IDs</title> + <p>Properties in the same section are distinguished by their IDs. This is + similar to variables in a programming language like Java, which are + distinguished by their names. But unlike variable names, property IDs are + simple integral numbers. There is another similarity, however. Just like + a Java variable has a certain scope (e.g. a member variables in a class), + a property ID also has its scope of validity: the section.</p> + + <p>Two property IDs in sections with different section format IDs + don't have the same meaning even though their IDs might be equal. For + example, ID 4 in the first (and only) section of a summary + information property set denotes the document's author, while ID 4 in the + first section of the document summary information property set means the + document's byte count. The sample output above does not show a property + with an ID of 4 in the first section of the document summary information + property set. That means that the document does not have a byte + count. However, there is a property with an ID of 4 in the + <em>second</em> section: This is a user-defined property ID - we'll get + to that topic in a minute.</p> + + <p>So, how can you find out what the meaning of a certain property ID in + the summary information and the document summary information property set + is? The standard property sets as such don't have any hints about the + <strong>meanings of their property IDs</strong>. For example, the summary + information property set does not tell you that the property ID 4 stands + for the document's author. This is external knowledge. Microsoft defined + standard meanings for some of the property IDs in the summary information + and the document summary information property sets. As a help to the Java + and POI programmer, the class <code>PropertyIDMap</code> in the + <code>org.apache.poi.hpsf.wellknown</code> package defines constants + for the "well-known" property IDs. For example, there is the + definition</p> + + <source>public final static int PID_AUTHOR = 4;</source> + + <p>These definitions allow you to use symbolic names instead of + numbers.</p> + + <p>In order to provide support for the other way, too, - i.e. to map + property IDs to property names - the class <code>PropertyIDMap</code> + defines two static methods: + <code>getSummaryInformationProperties()</code> and + <code>getDocumentSummaryInformationProperties()</code>. Both return + <code>java.util.Map</code> objects which map property IDs to + strings. Such a string gives a hint about the property's meaning. For + example, + <code>PropertyIDMap.getSummaryInformationProperties().get(4)</code> + returns the string "PID_AUTHOR". An application could use this string as + a key to a localized string which is displayed to the user, e.g. "Author" + in English or "Verfasser" in German. HPSF might provide such + language-dependent ("localized") mappings in a later release.</p> + + <p>Usually you won't have to deal with those two maps. Instead you should + call the <code>Section.getPIDString(int)</code> method. It returns the + string associated with the specified property ID in the context of the + <code>Section</code> object.</p> + + <p>Above you learned that property IDs have a meaning in the scope of a + section only. However, there are two exceptions to the rule: The property + IDs 0 and 1 have a fixed meaning in <strong>all</strong> sections:</p> + + <table> + <tr> + <th>Property ID</th> + <th>Meaning</th> + </tr> + + <tr> + <td>0</td> + <td>The property's value is a <strong>dictionary</strong>, i.e. a + mapping from property IDs to strings.</td> + </tr> + + <tr> + <td>1</td> + <td>The property's value is the number of a <strong>codepage</strong>, + i.e. a mapping from character codes to characters. All strings in the + section containing this property must be interpreted using this + codepage. Typical property values are 1252 (8-bit "western" characters, + ISO-8859-1), 1200 (16-bit Unicode characters, UFT-16), or 65001 (8-bit + Unicode characters, UFT-8).</td> + </tr> + </table> + </section> + + <section><title>Property types</title> + <p>A property is nothing without its value. It is stored in a property set + stream as a sequence of bytes. You must know the property's + <strong>type</strong> in order to properly interpret those bytes and + reasonably handle the value. A property's type is one of the so-called + Microsoft-defined <strong>"variant types"</strong>. When you call + <code>Property.getType()</code> you'll get a <code>long</code> value + which denoting the property's variant type. The class + <code>Variant</code> in the <code>org.apache.poi.hpsf</code> package + holds most of those <code>long</code> values as named constants. For + example, the constant <code>VT_I4 = 3</code> means a signed integer value + of four bytes. Examples of other types are <code>VT_LPSTR = 30</code> + meaning a null-terminated string of 8-bit characters, <code>VT_LPWSTR = + 31</code> which means a null-terminated Unicode string, or <code>VT_BOOL + = 11</code> denoting a boolean value.</p> + + <p>In most cases you won't need a property's type because HPSF does all + the work for you.</p> + </section> + + <section><title>Property values</title> + <p>When an application wants to retrieve a property's value and calls + <code>Property.getValue()</code>, HPSF has to interpret the bytes making + out the value according to the property's type. The type determines how + many bytes the value consists of and what + to do with them. For example, if the type is <code>VT_I4</code>, HPSF + knows that the value is four bytes long and that these bytes + comprise a signed integer value in the little-endian format. This is + quite different from e.g. a type of <code>VT_LPWSTR</code>. In this case + HPSF has to scan the value bytes for a Unicode null character and collect + everything from the beginning to that null character as a Unicode + string.</p> + + <p>The good new is that HPSF does another job for you, too: It maps the + variant type to an adequate Java type.</p> + + <table> + <tr> + <th>Variant type:</th> + <th>Java type:</th> + </tr> + + <tr> + <td>VT_I2</td> + <td>java.lang.Integer</td> + </tr> + + <tr> + <td>VT_I4</td> + <td>java.lang.Long</td> + </tr> + + <tr> + <td>VT_FILETIME</td> + <td>java.util.Date</td> + </tr> + + <tr> + <td>VT_LPSTR</td> + <td>java.lang.String</td> + </tr> + + <tr> + <td>VT_LPWSTR</td> + <td>java.lang.String</td> + </tr> + + <tr> + <td>VT_CF</td> + <td>byte[]</td> + </tr> + + <tr> + <td>VT_BOOL</td> + <td>java.lang.Boolean</td> + </tr> + + </table> + + <p>The bad news is that there are still a couple of variant types HPSF + does not yet support. If it encounters one of these types it + returns the property's value as a byte array and leaves it to be + interpreted by the application.</p> + + <p>An application retrieves a property's value by calling the + <code>Property.getValue()</code> method. This method's return type is the + abstract <code>Object</code> class. The <code>getValue()</code> method + looks up the property's variant type, reads the property's value bytes, + creates an instance of an adequate Java type, assigns it the property's + value and returns it. Primitive types like <code>int</code> or + <code>long</code> will be returned as the corresponding class, + e.g. <code>Integer</code> or <code>Long</code>.</p> + </section> + + + <section><title>Dictionaries</title> + <p>The property with ID 0 has a very special meaning: It is a + <strong>dictionary</strong> mapping property IDs to property names. We + have seen already that the meanings of standard properties in the + summary information and the document summary information property sets + have been defined by Microsoft. The advantage is that the labels of + properties like "Author" or "Title" don't have to be stored in the + property set. However, a user can define custom fields in, say, Microsoft + Word. For each field the user has to specify a name, a type, and a + value.</p> + + <p>The names of the custom-defined fields (i.e. the property names) are + stored in the document summary information second section's + <strong>dictionary</strong>. The dictionary is a map which associates + property IDs with property names.</p> + + <p>The method <code>Section.getPIDString(int)</code> not only returns with + the well-known property names of the summary information and document + summary information property sets, but with self-defined properties, + too. It should also work with self-defined properties in self-defined + sections.</p> + </section> + + <section><title>Codepage support</title> + + <p>The property with ID 1 holds the number of the codepage which was used + to encode the strings in this section. If this property is not available + in a section, the platform's default character encoding will be + used. This works fine as long as the document being read has been written + on a platform with the same default character encoding. However, if you + receive a document from another region of the world and the codepage is + undefined, you are in trouble.</p> + + <p>HPSF's codepage support is only as good as the character encoding + support of the Java Virtual Machine (JVM) the application runs on. If + HPSF encounters a codepage number it assumes that the JVM has a character + encoding with a corresponding name. For example, if the codepage is 1252, + HPSF uses the character encoding "cp1252" to read or write strings. If + the JVM does not have that character encoding installed or if the + codepage number is illegal, an UnsupportedEncodingException will be + thrown. This works quite well with Java 2 Standard Edition (J2SE) + versions since 1.4. However, under J2SE 1.3 or lower you are out of + luck. You should install a newer J2SE version to process codepages with + HPSF.</p> + + <p>There are some exceptions to the rule saying that a character + encoding's name is derived from the codepage number by prepending the + string "cp" to it. In these cases the codepage number is mapped to a + well-known character encoding name. Here are a few examples:</p> + + <dl> + <dt>Codepage 932</dt> + <dd>is mapped to the character encoding "SJIS".</dd> + <dt>Codepage 1200</dt> + <dd>is mapped to the character encoding "UTF-16".</dd> + <dt>Codepage 65001</dt> + <dd>is mapped to the character encoding "UTF-8".</dd> + </dl> + + <p>More of these mappings between codepage and character encoding name are + hard-coded in the classes <code>org.apache.poi.hpsf.Constants</code> and + <code>org.apache.poi.hpsf.VariantSupport</code>. Probably there will be a + need to add more mappings. The HPSF author will appreciate any hints.</p> + </section> + </section> + + <anchor id="sec5"/> + <section><title>Writing Properties</title> + + <note>This section describes how to write properties.</note> + + <section><title>Overview of Writing Properties</title> + <p>Writing properties is possible at a high level and at a low level:</p> + + <ul> + + <li>Most users will want to create or change entries in the summary + information or document summary information streams. </li> + + <li>On the low level, there are no convenience classes or methods. You + have to deal with things like property IDs and variant types to write + properties. Therefore you should have read <a href="#sec3">section + 3</a> to understand the description of the low-level writing + functions.</li> + </ul> + + <p>HPSF's writing capabilities come with the classes + <code>PropertySet</code>, <code>Section</code>, + <code>Property</code>, and some helper classes.</p> + </section> + + + <section><title>Low-Level Writing: An Overview</title> + <p>When you are going to write a property set stream your application has + to perform the following steps:</p> + + <ol> + <li>Create a <code>PropertySet</code> instance.</li> + + <li>Get hold of a <code>Section</code>. You can either retrieve + the one that is always present in a new <code>PropertySet</code>, + or you have to create a new <code>Section</code> and add it to + the <code>PropertySet</code>. + </li> + + <li>Set any <code>Section</code> fields as you like.</li> + + <li>Create as many <code>Property</code> objects as you need. Set + each property's ID, type, and value. Add the + <code>Property</code> objects to the <code>Section</code>. + </li> + + <li>Create further <code>Section</code>s if you need them.</li> + + <li>Eventually retrieve the property set as a byte stream using + <code>PropertySet.toInputStream()</code> and write it to a POIFS + document.</li> + </ol> + </section> + + <section><title>Low-level Writing Functions In Details</title> + <p>Writing properties is introduced by an artificial but simple example: a + program creating a new document (aka POI file system) which contains only + a single document: a summary information property set stream. The latter + will hold the document's title only. This is artificial in that it does + not contain any Word, Excel or other kind of useful application document + data. A document containing just a property set is without any practical + use. However, it is perfectly fine for an example because it make it very + simple and easy to understand, and you will get used to writing + properties in real applications quickly.</p> + + <p>The application expects the name of the POI file system to be written + on the command line. The title property it writes is "Sample title".</p> + + <p>Here's the application's source code. You can also find it in the + "examples" section of the POI source code distribution. Explanations are + following below.</p> + + <source>package org.apache.poi.hpsf.examples; + +import java.io.FileOutputStream; +import java.io.IOException; +import java.io.InputStream; + +import org.apache.poi.hpsf.Property; +import org.apache.poi.hpsf.PropertySet; +import org.apache.poi.hpsf.Section; +import org.apache.poi.hpsf.Section; +import org.apache.poi.hpsf.SummaryInformation; +import org.apache.poi.hpsf.Variant; +import org.apache.poi.hpsf.WritingNotSupportedException; +import org.apache.poi.hpsf.wellknown.PropertyIDMap; +import org.apache.poi.hpsf.wellknown.SectionIDMap; +import org.apache.poi.poifs.filesystem.POIFSFileSystem; + +/** + * <p>This class is a simple sample application showing how to create a property + * set and write it to disk.</p> + * + * @author Rainer Klute + * @since 2003-09-12 + */ +public class WriteTitle +{ + /** + * <p>Runs the example program.</p> + * + * @param args Command-line arguments. The first and only command-line + * argument is the name of the POI file system to create. + * @throws IOException if any I/O exception occurs. + * @throws WritingNotSupportedException if HPSF does not (yet) support + * writing a certain property type. + */ + public static void main(final String[] args) + throws WritingNotSupportedException, IOException + { + /* Check whether we have exactly one command-line argument. */ + if (args.length != 1) + { + System.err.println("Usage: " + WriteTitle.class.getName() + + "destinationPOIFS"); + System.exit(1); + } + + final String fileName = args[0]; + + /* Create a mutable property set. Initially it contains a single section + * with no properties. */ + final PropertySet mps = new PropertySet(); + + /* Retrieve the section the property set already contains. */ + final Section ms = mps.getSections().get(0); + + /* Turn the property set into a summary information property. This is + * done by setting the format ID of its first section to + * SectionIDMap.SUMMARY_INFORMATION_ID. */ + ms.setFormatID(SectionIDMap.SUMMARY_INFORMATION_ID); + + /* Create an empty property. */ + final Property p = new Property(); + + /* Fill the property with appropriate settings so that it specifies the + * document's title. */ + p.setID(PropertyIDMap.PID_TITLE); + p.setType(Variant.VT_LPWSTR); + p.setValue("Sample title"); + + /* Place the property into the section. */ + ms.setProperty(p); + + /* Create the POI file system the property set is to be written to. */ + final POIFSFileSystem poiFs = new POIFSFileSystem(); + + /* For writing the property set into a POI file system it has to be + * handed over to the POIFS.createDocument() method as an input stream + * which produces the bytes making out the property set stream. */ + final InputStream is = mps.toInputStream(); + + /* Create the summary information property set in the POI file + * system. It is given the default name most (if not all) summary + * information property sets have. */ + poiFs.createDocument(is, SummaryInformation.DEFAULT_STREAM_NAME); + + /* Write the whole POI file system to a disk file. */ + poiFs.writeFilesystem(new FileOutputStream(fileName)); + } + +}</source> + + <p>The application first checks that there is exactly one single argument + on the command line: the name of the file to write. If this single + argument is present, the application stores it in the + <code>fileName</code> variable. It will be used in the end when the POI + file system is written to a disk file.</p> + + <source>if (args.length != 1) +{ + System.err.println("Usage: " + WriteTitle.class.getName() + + "destinationPOIFS"); + System.exit(1); +} +final String fileName = args[0];</source> + + <p>Let's create a property set now. We cannot use the + <code>PropertySet</code> class, because it is read-only. It does not have + a constructor creating an empty property set, and it does not have any + methods to modify its contents, i.e. to write sections containing + properties into it.</p> + + <p>The class to use is <code>PropertySet</code>. The sample application calls its no-args + constructor in order to establish an empty property set:</p> + + <source>final PropertySet mps = new PropertySet();</source> + + <p>As said, we have an empty property set now. Later we will put some + contents into it.</p> + + <p>The <code>PropertySet</code> created by the no-args constructor + is not really empty: It contains a single section without properties. We + can either retrieve that section and fill it with properties or we can + replace it by another section. We can also add further sections to the + property set. The sample application decides to retrieve the section + being already there:</p> + + <source>final Section ms = mps.getSections().get(0);</source> + + <p>The <code>getSections()</code> method returns the property set's + sections as a list, i.e. an instance of + <code>java.util.List</code>. Calling <code>get(0)</code> returns the + list's first (or zeroth, if you prefer) element.</p> + + <p>The alternative to retrieving the <code>Section</code> being + already there would have been to create an new + <code>Section</code> like this:</p> + + <source>Section s = new Section();</source> + + <p>The <code>Section</code> the sample application retrieved from + the <code>PropertySet</code> is still empty. It contains no + properties and does not have a format ID. As you have read <a + href="#sec3">above</a> the format ID of the first section in a + property set determines the property set's type. Since our property set + should become a SummaryInformation property set we have to set the format + ID of its first (and only) section to + <code>F29F85E0-4FF9-1068-AB-91-08-00-2B-27-B3-D9</code>. However, you + won't have to remember that ID: HPSF has it defined as the well-known + constant <code>SectionIDMap.SUMMARY_INFORMATION_ID</code>. The sample + application writes it to the section using the + <code>setFormatID(byte[])</code> method:</p> + + <source>ms.setFormatID(SectionIDMap.SUMMARY_INFORMATION_ID);</source> + + <source>final Property p = new Property();</source> + + <p>A <code>Property</code> object must have an ID, a type, and a + value (see <a href="#sec3">above</a> for details). The class + provides methods to set these attributes:</p> + + <source>p.setID(PropertyIDMap.PID_TITLE); +p.setType(Variant.VT_LPWSTR); +p.setValue("Sample title");</source> + + <p>The <code>Property</code> class has a constructor which you can + use to pass in all three attributes in a single call. See the Javadoc API + documentation for details!</p> + + <p>The sample property set is complete now. We have a + <code>PropertySet</code> containing a <code>Section</code> + containing a <code>Property</code>. Of course we could have added + more sections to the property set and more properties to the sections but + we wanted to keep things simple.</p> + + <p>The property set has to be written to a POI file system. The following + statement creates it.</p> + + <source>final POIFSFileSystem poiFs = new POIFSFileSystem();</source> + + <p>Writing the property set includes the step of converting it into a + sequence of bytes. The <code>PropertySet</code> class has the + method <code>toInputStream()</code> for this purpose. It returns the + bytes making out the property set stream as an + <code>InputStream</code>:</p> + + <source>final InputStream is = mps.toInputStream();</source> + + <p>If you'd read from this input stream you'd receive all the property + set's bytes. However, it is very likely that you'll never do + that. Instead you'll pass the input stream to the + <code>POIFSFileSystem.createDocument()</code> method, like this:</p> + + <source>poiFs.createDocument(is, SummaryInformation.DEFAULT_STREAM_NAME);</source> + + <p>Besides the <code>InputStream</code> <code>createDocument()</code> + takes a second parameter: the name of the document to be created. For a + SummaryInformation property set stream the default name is available as + the constant <code>SummaryInformation.DEFAULT_STREAM_NAME</code>.</p> + + <p>The last step is to write the POI file system to a disk file:</p> + + <source>poiFs.writeFilesystem(new FileOutputStream(fileName));</source> + </section> + </section> + + + + <section><title>Further Reading</title> + <p>There are still some aspects of HSPF left which are not covered by this + HOW-TO. You should dig into the Javadoc API documentation to learn + further details. Since you've struggled through this document up to this + point, you are well prepared.</p> + </section> + + </section> + </body> +</document> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/src/documentation/content/xdocs/components/hpsf/index.xml b/src/documentation/content/xdocs/components/hpsf/index.xml new file mode 100644 index 0000000000..88c4f306c5 --- /dev/null +++ b/src/documentation/content/xdocs/components/hpsf/index.xml @@ -0,0 +1,73 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - HPSF - Java API for Microsoft Format Document + Properties</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Rainer Klute" email="klute@apache.org"/> + </authors> + </header> + <body> + <section><title>Overview</title> + + <p>Microsoft applications like "Word", "Excel" or "Powerpoint" let the user + describe a document by properties like "title", "category" and so on. The + application itself adds further information: last author, creation date + etc. These document properties are stored in <strong>property set + streams</strong>. A property set stream is a separate document within a + <a href="../poifs/index.html">POI filesystem</a>. HPSF is POI's pure-Java + implementation to read and write property sets.</p> + + <p>The <a href="how-to.html">HPSF HOWTO</a> describes what a Java + application should do to read a property set using HPSF, how to retrieve + the information it needs, and how to write properties into the + document.</p> + + <p>HPSF supports OLE2 property set streams in general, and is not limited to + the special case of document properties in the Microsoft Office files + mentioned above. The <a href="internals.html">HPSF description</a> + describes the internal structure of property set streams. A separate + document explains the internal of <a href="thumbnails.html">thumbnail + images</a>.</p> + </section> + </body> +</document> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/src/documentation/content/xdocs/components/hpsf/internals.xml b/src/documentation/content/xdocs/components/hpsf/internals.xml new file mode 100644 index 0000000000..4046f8859c --- /dev/null +++ b/src/documentation/content/xdocs/components/hpsf/internals.xml @@ -0,0 +1,1079 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - HPSF Internals</title> + <authors> + <person name="Rainer Klute" email="klute@rainer-klute.de"/> + </authors> + </header> + <body> + <section><title>HPSF Internals</title> + + <section><title>Introduction</title> + + <p>A Microsoft Office document is internally organized like a filesystem + with directory and files. Microsoft calls these files + <strong>streams</strong>. A document can have properties attached to it, + like author, title, number of words etc. These metadata are not stored in + the main stream of, say, a Word document, but instead in a dedicated + stream with a special format. Usually this stream's name is + <code>\005SummaryInformation</code>, where <code>\005</code> represents + the character with a decimal value of 5.</p> + + <p>A single piece of information in the stream is called a + <strong>property</strong>, for example the document title. Each property + has an integral <strong>ID</strong> (e.g. 2 for title), a + <strong>type</strong> (telling that the title is a string of bytes) and a + <strong>value</strong> (what this is should be obvious). A stream + containing properties is called a + <strong>property set stream</strong>.</p> + + <p>This document describes the internal structure of a property set stream, + i.e. the <strong>HPSF</strong>. It does + not describe how a Microsoft Office document is organized internally and + how to retrieve a stream from it. See the <a + href="../poifs/index.html">POIFS documentation</a> for that kind of + stuff.</p> + + <p>The HPSF is not only used in the Summary + Information stream in the top-level document of a Microsoft Office + document. Often there is also a property set stream named + <code>\005DocumentSummaryInformation</code> with additional properties. + Embedded documents may have their own property set streams. You cannot + tell by a stream's name whether it is a property set stream or not. + Instead you have to open the stream and look at its bytes.</p> + </section> + + + + <section><title>Data Types</title> + + <p>Before delving into the details of the property set stream format we + have to have a short look at data types. Integral values are stored in the + so-called <strong>little endian</strong> format. In this format the bytes + that make out an integral value are stored in the "wrong" order. For + example, the decimal value 4660 is 0x1234 in the hexadecimal notation. If + you think this should be represented by a byte 0x12 followed by another + byte 0x34, you are right. This is called the <strong>big endian</strong> + format. In the little endian format, however, this order is reversed and + the low-value byte comes first: 0x3412. + </p> + + <p>The following table gives an overview about some important data + types:</p> + + <table> + + <tr> + <th>Name</th> + <th>Length</th> + <th>Example (Big Endian)</th> + <th>Example (Little Endian)</th> + </tr> + + <tr> + <td><strong>Bytes</strong></td> + <td>1 byte</td> + <td><code>0x12</code></td> + <td><code>0x12</code></td> + </tr> + + <tr> + <td><strong>Word</strong></td> + <td>2 bytes</td> + <td><code>0x1234</code></td> + <td><code>0x3412</code></td> + </tr> + + <tr> + <td><strong>DWord</strong></td> + <td>4 bytes</td> + <td><code>0x12345678</code></td> + <td><code>0x78563412</code></td> + </tr> + + <tr> + <td><strong>ClassID</strong><br/> + A sequence of one DWord, two Words and eight Bytes</td> + + <td>16 bytes</td> + + <td><code>0xE0859FF2F94F6810AB9108002B27B3D9</code> resp. + <code>E0859FF2-F94F-6810-AB-91-08-00-2B-27-B3-D9</code></td> + + <td><code>0xF29F85E04FF91068AB9108002B27B3D9</code> resp. + <code>F29F85E0-4FF9-1068-AB-91-08-00-2B-27-B3-D9</code></td> + </tr> + + <tr> + <td></td> + <td></td> + <td>The ClassID examples are given here in two different notations. The + second notation without the "0x" at the beginning and with dashes + inside shows the internal grouping into one DWord, two Words and eight + Bytes.</td> + <td><em>Watch out:</em> Microsoft documentation and tools show class IDs + a little bit differently like + <code>F29F85E0-4FF9-1068-AB91-08002B27B3D9</code>. + However, that representation is (intentionally?) misleading with + respect to endianess.</td> + </tr> + </table> + </section> + + + + <section><title>HPSF Overview</title> + + <p>A property set stream consists of three main parts:</p> + + <ol> + <li>The <strong>header</strong> and</li> + <li>the <strong>section(s)</strong> containing the properties.</li> + </ol> + </section> + + + + <section><title>The Header</title> + + <p>The first bytes in a property set stream is the <strong>header</strong>. + It has a fixed length and looks like this:</p> + + <table> + <tr> + <th>Offset</th> + <th>Type</th> + <th>Contents</th> + <th>Remarks</th> + </tr> + + <tr> + <td>0</td> + <td>Word</td> + <td><code>0xFFFE</code></td> + <td>If the first four bytes of a stream do not contain these values, the + stream is not a property set stream.</td> + </tr> + + <tr> + <td>2</td> + <td>Word</td> + <td><code>0x0000</code></td> + <td></td> + </tr> + + <tr> + <td>4</td> + <td>DWord</td> + <td>Denotes the operating system and the OS version under which this + stream was created. The operating system ID is in the DWord's higher + word (after little endian decoding): <code>0x0000</code> for Win16, + <code>0x0001</code> for Macintosh and <code>0x0002</code> for Win32 - + that's all. The reader is most likely aware of the fact that there are + some more operating systems. However, Microsoft does not seem to + know.</td> + <td></td> + </tr> + + <tr> + <td>8</td> + <td>ClassID</td> + <td><code>0x00000000000000000000000000000000</code></td> + <td>Most property set streams have this value but this is not + required.</td> + </tr> + + <tr> + <td>24</td> + <td>DWord</td> + <td><code>0x01000000</code> or greater</td> + <td>Section count. This field's value should be equal to 1 or greater. + Microsoft claims that this is a "reserved" field, but it seems to tell + how many sections (see below) are following in the stream. This would + really make sense because otherwise you could not know where and how + far you should read section data.</td> + </tr> + </table> + </section> + + + + <section><title>Section List</title> + + <p>Following the header is the section list. This is an array of pairs each + consisting of a section format ID and an offset. This array has as many + pairs of ClassID and and DWord fields as the section count field in the + header says. The Summary Information stream contains a single section, the + Document Summary Information stream contains two.</p> + + <table> + <tr> + <th>Type</th> + <th>Contents</th> + <th>Remarks</th> + </tr> + + <tr> + <td>ClassID</td> + <td>Section format ID</td> + <td><code>0xF29F85E04FF91068AB9108002B27B3D9</code> for the single section + in the Summary Information stream.<br/><br/> + + <code>0xD5CDD5022E9C101B939708002B2CF9AE</code> for the first + section in the Document Summary Information stream.</td> + </tr> + + <tr> + <td>DWord</td> + <td>Offset</td> + <td>The number of bytes between the beginning of the stream and the + beginning of the section within the stream.</td> + </tr> + + <tr> + <td>ClassID</td> + <td>Section format ID</td> + <td>...</td> + </tr> + + <tr> + <td>DWord</td> + <td>Offset</td> + <td>...</td> + </tr> + + <tr> + <td>...</td> + <td>...</td> + <td>...</td> + </tr> + </table> + </section> + + + + <section><title>Section</title> + + <p>A section is divided into three parts: the section header (with the + section length and the number of properties in the section), the + properties list (with type and offset of each property), and the + properties themselves. Here are the details:</p> + + <table> + <tr> + <th> </th> + <th>Type</th> + <th>Contents</th> + <th>Remarks</th> + </tr> + + <tr> + <td>Section header</td> + + <td>DWord</td> + <td>Length</td> + <td>The length of the section in bytes.</td> + </tr> + + <tr> + <td></td> + <td>DWord</td> + <td>Property count</td> + <td>The number of properties in the section.</td> + </tr> + + <tr> + + <td>Properties list</td> + + <td>DWord</td> + <td>Property ID</td> + <td>The property ID tells what the property means. For example, an ID of + <code>0x0002</code> in the Summary Information stands for the document's + title. See the <a href="#property_ids">Property IDs</a> + chapter below for more details.</td> + </tr> + + <tr> + <td></td> + <td>DWord</td> + <td>Offset</td> + <td>The number of bytes between the beginning of the section and the + property.</td> + </tr> + + <tr> + <td></td> + <td>...</td> + <td>...</td> + <td>...</td> + </tr> + + <tr> + <td>Properties</td> + + <td>DWord</td> + <td>Property type ("variant")</td> + <td>This is the property's data type, e.g. an integer value, a byte + string or a Unicode string. See the + <a href="#property_types"><em>Property Types</em></a> chapter + for details!</td> + </tr> + + <tr> + <td></td> + <td><em>Field length depends on the property type + ("variant")</em></td> + <td>Property value</td> + <td>This field's length depends on the property's type. These are the + bytes that make out the DWord, the byte string or some other data of + fixed or variable length.<br/><br/> + + The property value's length is always stored in an area which is a + multiple of 4 in length. If the property is shorter, e.g. a byte + string of 13 bytes, the remaining bytes are padded with <code>0x00</code> + bytes.</td> + </tr> + + <tr> + <td></td> + <td>...</td> + <td>...</td> + <td>...</td> + </tr> + </table> + </section> + + + + <section><title>Property IDs</title> + <anchor id="property_ids"/> + + <p>As seen above, a section holds a property list: an array with property + IDs and offsets. The property ID gives each property a meaning. For + example, in the Summary Information stream the property ID 2 says that + this property is the document's title.</p> + + <p>If you want to know a property ID's meaning, it is not sufficient to + know the ID itself. You must also know the + <strong>section format ID</strong>. For example, in the Document Summary + Information stream the property ID 2 means not the document's title but + its category. Due to Microsoft's infinite wisdom the section format ID is + not part of the section. Thus if you have only a section without the + stream it is in, you cannot make any sense of the properties because you + do not know what they mean.</p> + + <p>So each section format ID has its own name space of property IDs. + Microsoft defined some "well-known" property IDs for the Summary + Information and the Document Summary Information streams. You can extend + them by your own additional IDs. This will be described below.</p> + + <section><title>Property IDs in The Summary Information Stream</title> + + <p>The Summary Information stream has a single section with a section + format ID of <code>0xF29F85E04FF91068AB9108002B27B3D9</code>. The following + table defines the meaning of its property IDs. Each row associates a + property ID with a <em>name</em> and an <em>ID string</em>. (The property + <em>type</em> is just for informational purposes given here. As we have + seen above, the type is always given along with the value.)</p> + + <p>The property <em>name</em> is a readable string which could be + displayed to the user. However, this string is useful only for users who + understand English. The property name does not help with other + languages.</p> + + <p>The property <em>ID string</em> is about the same but looks more + technically and is nothing a user should bother with. You could the ID + string and map it to an appropriate display string in a particular + language. Of course you could do that with the property ID as well and + with less overhead, but people (including software developers) tend to be + better in remembering symbolic constants than remembering numbers.</p> + + <table> + <tr> + <th>Property ID</th> + <th>Property Name</th> + <th>Property ID String</th> + <th>Property Type</th> + </tr> + <tr> + <td>2</td> + <td>Title</td> + <td>PID_TITLE</td> + <td>VT_LPSTR</td> + </tr> + <tr> + <td>3</td> + <td>Subject</td> + <td>PID_SUBJECT</td> + <td>VT_LPSTR</td> + </tr> + <tr> + <td>4</td> + <td>Author</td> + <td>PID_AUTHOR</td> + <td>VT_LPSTR</td> + </tr> + <tr> + <td>5</td> + <td>Keywords</td> + <td>PID_KEYWORDS</td> + <td>VT_LPSTR</td> + </tr> + <tr> + <td>6</td> + <td>Comments</td> + <td>PID_COMMENTS</td> + <td>VT_LPSTR</td> + </tr> + <tr> + <td>7</td> + <td>Template</td> + <td>PID_TEMPLATE</td> + <td>VT_LPSTR</td> + </tr> + <tr> + <td>8</td> + <td>Last Saved By</td> + <td>PID_LASTAUTHOR</td> + <td>VT_LPSTR</td> + </tr> + <tr> + <td>9</td> + <td>Revision Number</td> + <td>PID_REVNUMBER</td> + <td>VT_LPSTR</td> + </tr> + <tr> + <td>10</td> + <td>Total Editing Time</td> + <td>PID_EDITTIME</td> + <td>VT_FILETIME</td> + </tr> + <tr> + <td>11</td> + <td>Last Printed</td> + <td>PID_LASTPRINTED</td> + <td>VT_FILETIME</td> + </tr> + <tr> + <td>12</td> + <td>Create Time/Date</td> + <td>PID_CREATE_DTM</td> + <td>VT_FILETIME</td> + </tr> + <tr> + <td>13</td> + <td>Last Saved Time/Date</td> + <td>PID_LASTSAVE_DTM</td> + <td>VT_FILETIME</td> + </tr> + <tr> + <td>14</td> + <td>Number of Pages</td> + <td>PID_PAGECOUNT</td> + <td>VT_I4</td> + </tr> + <tr> + <td>15</td> + <td>Number of Words</td> + <td>PID_WORDCOUNT</td> + <td>VT_I4</td> + </tr> + <tr> + <td>16</td> + <td>Number of Characters</td> + <td>PID_CHARCOUNT</td> + <td>VT_I4</td> + </tr> + <tr> + <td>17</td> + <td>Thumbnail</td> + <td>PID_THUMBNAIL</td> + <td>VT_CF</td> + </tr> + <tr> + <td>18</td> + <td>Name of Creating Application</td> + <td>PID_APPNAME</td> + <td>VT_LPSTR</td> + </tr> + <tr> + <td>19</td> + <td>Security</td> + <td>PID_SECURITY</td> + <td>VT_I4</td> + </tr> + </table> + </section> + + + + <section><title>Property IDs in The Document Summary Information Stream</title> + + <p>The Document Summary Information stream has two sections with a section + format ID of <code>0xD5CDD5022E9C101B939708002B2CF9AE</code> for the first + one. The following table defines the meaning of the property IDs in the + first section. See the preceding section for interpreting the table.</p> + + <table> + <tr> + <th>Property ID</th> + <th>Property name</th> + <th>Property ID string</th> + <th>VT type</th> + </tr> + + <tr> + <td>0</td> + <td>Dictionary</td> + <td>PID_DICTIONARY</td> + <td>[Special format]</td> + </tr> + <tr> + <td>1</td> + <td>Code page</td> + <td>PID_CODEPAGE</td> + <td>VT_I2</td> + </tr> + <tr> + <td>2</td> + <td>Category</td> + <td>PID_CATEGORY</td> + <td>VT_LPSTR</td> + </tr> + <tr> + <td>3</td> + <td>PresentationTarget</td> + <td>PID_PRESFORMAT</td> + <td>VT_LPSTR</td> + </tr> + <tr> + <td>4</td> + <td>Bytes</td> + <td>PID_BYTECOUNT</td> + <td>VT_I4</td> + </tr> + <tr> + <td>5</td> + <td>Lines</td> + <td>PID_LINECOUNT</td> + <td>VT_I4</td> + </tr> + <tr> + <td>6</td> + <td>Paragraphs</td> + <td>PID_PARCOUNT</td> + <td>VT_I4</td> + </tr> + <tr> + <td>7</td> + <td>Slides</td> + <td>PID_SLIDECOUNT</td> + <td>VT_I4</td> + </tr> + <tr> + <td>8</td> + <td>Notes</td> + <td>PID_NOTECOUNT</td> + <td>VT_I4</td> + </tr> + <tr> + <td>9</td> + <td>HiddenSlides</td> + <td>PID_HIDDENCOUNT</td> + <td>VT_I4</td> + </tr> + <tr> + <td>10</td> + <td>MMClips</td> + <td>PID_MMCLIPCOUNT</td> + <td>VT_I4</td> + </tr> + <tr> + <td>11</td> + <td>ScaleCrop</td> + <td>PID_SCALE</td> + <td>VT_BOOL</td> + </tr> + <tr> + <td>12</td> + <td>HeadingPairs</td> + <td>PID_HEADINGPAIR</td> + <td>VT_VARIANT | VT_VECTOR</td> + </tr> + <tr> + <td>13</td> + <td>TitlesofParts</td> + <td>PID_DOCPARTS</td> + <td>VT_LPSTR | VT_VECTOR</td> + </tr> + <tr> + <td>14</td> + <td>Manager</td> + <td>PID_MANAGER</td> + <td>VT_LPSTR</td> + </tr> + <tr> + <td>15</td> + <td>Company</td> + <td>PID_COMPANY</td> + <td>VT_LPSTR</td> + </tr> + <tr> + <td>16</td> + <td>LinksUpTo Date</td> + <td>PID_LINKSDIRTY</td> + <td>VT_BOOL</td> + </tr> + </table> + </section> + </section> + + + + <section><title>Property Types</title> + <anchor id="property_types"/> + + <p>A property consists of a DWord <em>type field</em> followed by the + property value. The property type is an integer value and tells how the + data byte following it are to be interpreted. In the Microsoft world it is + also known as the <em>variant</em>.</p> + + <p>The <em>Usage</em> column says where a variant type may occur. Not all + of them are allowed in a property set but just those marked with a [P]. + <strong>[V]</strong> - may appear in a VARIANT, <strong>[T]</strong> - may + appear in a TYPEDESC, <strong>[P]</strong> - may appear in an OLE property + set, <strong>[S]</strong> - may appear in a Safe Array.</p> + + <table> + <tr> + <th>Variant ID</th> + <th>Variant Type</th> + <th>Usage</th> + <th>Description</th> + </tr> + <tr> + <td>0</td> + <td>VT_EMPTY</td> + <td>[V] [P]</td> + <td>nothing</td> + </tr> + <tr> + <td>1</td> + <td>VT_NULL</td> + <td>[V] [P]</td> + <td>SQL style Null</td> + </tr> + <tr> + <td>2</td> + <td>VT_I2</td> + <td>[V] [T] [P] [S]</td> + <td>2 byte signed int</td> + </tr> + <tr> + <td>3</td> + <td>VT_I4</td> + <td>[V] [T] [P] [S]</td> + <td>4 byte signed int</td> + </tr> + <tr> + <td>4</td> + <td>VT_R4</td> + <td>[V] [T] [P] [S]</td> + <td>4 byte real</td> + </tr> + <tr> + <td>5</td> + <td>VT_R8</td> + <td>[V] [T] [P] [S]</td> + <td>8 byte real</td> + </tr> + <tr> + <td>6</td> + <td>VT_CY</td> + <td>[V] [T] [P] [S]</td> + <td>currency</td> + </tr> + <tr> + <td>7</td> + <td>VT_DATE</td> + <td>[V] [T] [P] [S]</td> + <td>date</td> + </tr> + <tr> + <td>8</td> + <td>VT_BSTR</td> + <td>[V] [T] [P] [S]</td> + <td>OLE Automation string</td> + </tr> + <tr> + <td>9</td> + <td>VT_DISPATCH</td> + <td>[V] [T] [P] [S]</td> + <td>IDispatch *</td> + </tr> + <tr> + <td>10</td> + <td>VT_ERROR</td> + <td>[V] [T] [S]</td> + <td>SCODE</td> + </tr> + <tr> + <td>11</td> + <td>VT_BOOL</td> + <td>[V] [T] [P] [S]</td> + <td>True=-1, False=0</td> + </tr> + <tr> + <td>12</td> + <td>VT_VARIANT</td> + <td>[V] [T] [P] [S]</td> + <td>VARIANT *</td> + </tr> + <tr> + <td>13</td> + <td>VT_UNKNOWN</td> + <td>[V] [T] [S]</td> + <td>IUnknown *</td> + </tr> + <tr> + <td>14</td> + <td>VT_DECIMAL</td> + <td>[V] [T] [S]</td> + <td>16 byte fixed point</td> + </tr> + <tr> + <td>16</td> + <td>VT_I1</td> + <td>[T]</td> + <td>signed char</td> + </tr> + <tr> + <td>17</td> + <td>VT_UI1</td> + <td>[V] [T] [P] [S]</td> + <td>unsigned char</td> + </tr> + <tr> + <td>18</td> + <td>VT_UI2</td> + <td>[T] [P]</td> + <td>unsigned short</td> + </tr> + <tr> + <td>19</td> + <td>VT_UI4</td> + <td>[T] [P]</td> + <td>unsigned short</td> + </tr> + <tr> + <td>20</td> + <td>VT_I8</td> + <td>[T] [P]</td> + <td>signed 64-bit int</td> + </tr> + <tr> + <td>21</td> + <td>VT_UI8</td> + <td>[T] [P]</td> + <td>unsigned 64-bit int</td> + </tr> + <tr> + <td>22</td> + <td>VT_INT</td> + <td>[T]</td> + <td>signed machine int</td> + </tr> + <tr> + <td>23</td> + <td>VT_UINT</td> + <td>[T]</td> + <td>unsigned machine int</td> + </tr> + <tr> + <td>24</td> + <td>VT_VOID</td> + <td>[T]</td> + <td>C style void</td> + </tr> + <tr> + <td>25</td> + <td>VT_HRESULT</td> + <td>[T]</td> + <td>Standard return type</td> + </tr> + <tr> + <td>26</td> + <td>VT_PTR</td> + <td>[T]</td> + <td>pointer type</td> + </tr> + <tr> + <td>27</td> + <td>VT_SAFEARRAY</td> + <td>[T]</td> + <td>(use VT_ARRAY in VARIANT)</td> + </tr> + <tr> + <td>28</td> + <td>VT_CARRAY</td> + <td>[T]</td> + <td>C style array</td> + </tr> + <tr> + <td>29</td> + <td>VT_USERDEFINED</td> + <td>[T]</td> + <td>user defined type</td> + </tr> + <tr> + <td>30</td> + <td>VT_LPSTR</td> + <td>[T] [P]</td> + <td>null terminated string</td> + </tr> + <tr> + <td>31</td> + <td>VT_LPWSTR</td> + <td>[T] [P]</td> + <td>wide null terminated string</td> + </tr> + <tr> + <td>64</td> + <td>VT_FILETIME</td> + <td>[P]</td> + <td>FILETIME</td> + </tr> + <tr> + <td>65</td> + <td>VT_BLOB</td> + <td>[P]</td> + <td>Length prefixed bytes</td> + </tr> + <tr> + <td>66</td> + <td>VT_STREAM</td> + <td>[P]</td> + <td>Name of the stream follows</td> + </tr> + <tr> + <td>67</td> + <td>VT_STORAGE</td> + <td>[P]</td> + <td>Name of the storage follows</td> + </tr> + <tr> + <td>68</td> + <td>VT_STREAMED_OBJECT</td> + <td>[P]</td> + <td>Stream contains an object</td> + </tr> + <tr> + <td>69</td> + <td>VT_STORED_OBJECT</td> + <td>[P]</td> + <td>Storage contains an object</td> + </tr> + <tr> + <td>70</td> + <td>VT_BLOB_OBJECT</td> + <td>[P]</td> + <td>Blob contains an object</td> + </tr> + <tr> + <td>71</td> + <td>VT_CF</td> + <td>[P]</td> + <td>Clipboard format</td> + </tr> + <tr> + <td>72</td> + <td>VT_CLSID</td> + <td>[P]</td> + <td>A Class ID</td> + </tr> + <tr> + <td>0x1000</td> + <td>VT_VECTOR</td> + <td>[P]</td> + <td>simple counted array</td> + </tr> + <tr> + <td>0x2000</td> + <td>VT_ARRAY</td> + <td>[V]</td> + <td>SAFEARRAY*</td> + </tr> + <tr> + <td>0x4000</td> + <td>VT_BYREF</td> + <td>[V]</td> + <td>void* for local use</td> + </tr> + <tr> + <td>0x8000</td> + <td>VT_RESERVED</td> + <td><br/></td> + <td><br/></td> + </tr> + <tr> + <td>0xFFFF</td> + <td>VT_ILLEGAL</td> + <td><br/></td> + <td><br/></td> + </tr> + <tr> + <td>0xFFF</td> + <td>VT_ILLEGALMASKED</td> + <td><br/></td> + <td><br/></td> + </tr> + <tr> + <td>0xFFF</td> + <td>VT_TYPEMASK</td> + <td><br/></td> + <td><br/></td> + </tr> + </table> + </section> + + + + <section> + <title>The Dictionary</title> + + <p>What a dictionary is good for is explained in the <a + href="how-to.html">HPSF HOW-TO</a>. This chapter explains how it is + organized internally.</p> + + <p>The dictionary has a simple header consisting of a single UInt value. It + tells how many entries the dictionary comprises:</p> + + <table> + <tr> + <th>Name</th> + <th>Data type</th> + <th>Description</th> + </tr> + <tr> + <td>nrEntries</td> + <th>UInt</th> + <td>Number of dictionary entries</td> + </tr> + </table> + + <p>The dictionary entries follow the header. Each one looks like this:</p> + + <table> + <tr> + <th>Name</th> + <td>Data type</td> + <th>Description</th> + </tr> + <tr> + <td>key</td> + <td>UInt</td> + <td>The unique number of this property, i.e. the PID</td> + </tr> + <tr> + <td>length</td> + <td>UInt</td> + <td>The length of the property name associated with the key</td> + </tr> + <tr> + <td>value</td> + <td>String</td> + <td>The property's name, terminated with a 0x00 character</td> + </tr> + </table> + + <p>The entries are not aligned, i.e. each one follows its predecessor + without any gap or fill characters.</p> + </section> + + + + <section><title>References</title> + + <p>In order to assemble the HPSF description I used information publically + available on the Internet only. The references given below have been very + helpful. If you have any amendments or corrections, please let us know! + Thank you!</p> + + <ol> + + <li>In + <a href="https://www.kyler.com/pubs/ddj9894.html"><em>Understanding OLE + documents</em></a>, Ken Kyler gives an introduction to OLE2 + documents and especially to property sets. He names the property names, + types, and IDs of the Summary Information and Document Summary + Information stream.</li> + + <li>The <a href="https://www.dwam.net/docs/oleref/"><em>ActiveX + Programmer's Reference</em></a> at <a + href="https://www.dwam.net/docs/oleref/">https://www.dwam.net/docs/oleref/</a> + seems a little outdated, but that's what I have found.</li> + + <li>An overview of the <code>VT_</code> types is in + <a href="https://www.marin.clara.net/COM/variant_type_definitions.htm"><em>Variant + Type Definitions</em></a>.</li> + + <li>What is a <code>FILETIME</code>? The answer can be found + under <a + href="https://msdn.microsoft.com/library/default.asp?url=/library/en-us/sysinfo/base/filetime_str.asp"></a>, <a href="https://www.vbapi.com/ref/f/filetime.html">https://www.vbapi.com/ref/f/filetime.html</a> or + <a href="https://www.cs.rpi.edu/courses/fall01/os/FILETIME.html">https://www.cs.rpi.edu/courses/fall01/os/FILETIME.html</a>. + In short: <em>The FILETIME structure holds a date and time associated + with a file. The structure identifies a 64-bit integer specifying the + number of 100-nanosecond intervals which have passed since January 1, + 1601. This 64-bit value is split into the two dwords stored in the + structure.</em></li> + + <li>Microsoft provides some public information in the <a + href="https://msdn.microsoft.com/library/default.asp">MSDN + Library</a>. Use the search function to try to find what you are + looking for, e.g. "codepage" or "document summary information" etc.</li> + </ol> + </section> + </section> + </body> +</document> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/src/documentation/content/xdocs/components/hpsf/thumbnails.xml b/src/documentation/content/xdocs/components/hpsf/thumbnails.xml new file mode 100644 index 0000000000..3d109fc520 --- /dev/null +++ b/src/documentation/content/xdocs/components/hpsf/thumbnails.xml @@ -0,0 +1,198 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>HPSF THUMBNAIL HOW-TO</title> + <authors> + <person name="Drew Varner" email="Drew.Varner@-deleteThis-sc.edu" /> + </authors> + </header> + <body> + <section><title>The VT_CF Format</title> + + <p>Thumbnail information is stored as a VT_CF, or Thumbnail Variant. The + Thumbnail Variant is used to store various types of information in a + clipboard. The VT_CF can store information in formats for the Macintosh or + Windows clipboard.</p> + + <p>There are many types of data that can be copied to the clipboard, but the + only types of information needed for thumbnail manipulation are the image + formats.</p> + + <p>The <code>VT_CF</code> structure looks like this:</p> + + <table> + <tr> + <th>Element:</th> + <td>Clipboard Size</td> + <td>Clipboard Format Tag</td> + <td>Clipboard Data</td> + </tr> + <tr> + <th>Size:</th> + <td>32 bit unsigned integer (DWord)</td> + <td>32 bit signed integer (DWord)</td> + <td>variable length (byte array)</td> + </tr> + </table> + + <p>The Clipboard Size refers to the size (in bytes) of Clipboard Data + (variable size) plus the Clipboard Format (four bytes).</p> + + <p>Clipboard Format Tag has four possible values:</p> + + <table> + <tr> + <th>Value</th> + <th>Identifier</th> + <th>Description</th> + </tr> + <tr> + <td><code>-1L</code></td> + <td><code>CFTAG_WINDOWS</code></td> + <td>a built-in Windows© clipboard format value</td> + </tr> + <tr> + <td><code>-2L</code></td> + <td><code>CFTAG_MACINTOSH</code></td> + <td>a Macintosh clipboard format value</td> + </tr> + <tr> + <td><code>-3L</code></td> + <td><code>CFTAG_FMTID</code></td> + <td>a format identifier (FMTID) This is rarely used.</td> + </tr> + <tr> + <td><code>0L</code></td> + <td><code>CFTAG_NODATA</code></td> + <td>No data This is rarely used.</td> + </tr> + </table> + </section> + + + + <section><title>Windows Clipboard Data</title> + + <p>Windows clipboard data has four image formats for thumbnails:</p> + + <table> + <tr> + <th>Value</th> + <th>Identifier</th> + <th>Description</th> + </tr> + <tr> + <td>3</td> + <td><code>CF_METAFILEPICT</code></td> + <td>Windows metafile format - recommended</td> + </tr> + <tr> + <td>8</td> + <td><code>CF_DIB</code></td> + <td>Device Independent Bitmap</td> + </tr> + <tr> + <td>14</td> + <td><code>CF_ENHMETAFILE</code></td> + <td>Enhanced Windows metafile format</td> + </tr> + <tr> + <td>2</td> + <td><code>CF_BITMAP</code></td> + <td>Bitmap - Obsolete - Use <code>CF_DIB</code> instead</td> + </tr> + </table> + </section> + + <section><title>Windows Metafile Format</title> + + <p>The most common format for thumbnails on the Windows platform is the + Windows metafile format. The Clipboard places and extra header in front of + a the standard Windows Metafile Format data.</p> + + <p>The Clipboard Data byte array looks like this when an image is stored in + Windows' Clipboard WMF format.</p> + + <table> + <tr> + <th>Identifier</th> + <td>CF_METAFILEPICT</td> + <td>mm</td> + <td>width</td> + <td>height</td> + <td>handle</td> + <td>WMF data</td> + </tr> + <tr> + <th>Size</th> + <td>32 bit unsigned int</td> + <td>16 bit unsigned(?) int</td> + <td>16 bit unsigned(?) int</td> + <td>16 bit unsigned(?) int</td> + <td>16 bit unsigned(?) int</td> + <td>byte array - variable length</td> + </tr> + <tr> + <th>Description</th> + <td>Clipboard WMF</td> + <td>Mapping Mode</td> + <td>Image Width</td> + <td>Image Height</td> + <td>handle to the WMF data array in memory, or 0</td> + <td>standard WMF byte stream</td> + </tr> + </table> + </section> + + + <section><title>Device Independent Bitmap</title> + <p><strong>FIXME:</strong> Describe the Device Independent Bitmap + format!</p> + </section> + + + + <section><title>Macintosh Clipboard Data</title> + <p><strong>FIXME:</strong> Describe the Macintosh clipboard formats!</p> + </section> + + </body> +</document> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/src/documentation/content/xdocs/components/hpsf/todo.xml b/src/documentation/content/xdocs/components/hpsf/todo.xml new file mode 100644 index 0000000000..d18e9b1e9a --- /dev/null +++ b/src/documentation/content/xdocs/components/hpsf/todo.xml @@ -0,0 +1,77 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>To Do</title> + <authors> + <person name="Rainer Klute" email="klute@rainer-klute.de"/> + </authors> + </header> + <body> + <section><title>To Do</title> + + <p>The following functionalities should be added to HPFS:</p> + + <ol> + <li> + Improve writing support! We need convenience classes and methods for + easily writing summary information streams and document summary + information streams. + </li> + <li> + Add resource bundles to + <code>org.apache.poi.hpsf.wellknown</code> to ease + localizations. This would be useful for mapping standard property IDs to + localized strings. Example: The property ID 4 could be mapped to "Author" + in English or "Verfasser" in German. + </li> + <li> + Implement reading functionality for those property types that are not + yet supported. HPSF should return proper Java types instead of just byte + arrays. + </li> + <li> + Add WMF to <code>java.awt.Image</code> example code in the <a + href="thumbnails.html">Thumbnail HOW-TO</a>. + </li> + </ol> + </section> + </body> +</document> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/src/documentation/content/xdocs/components/hsmf/index.xml b/src/documentation/content/xdocs/components/hsmf/index.xml new file mode 100644 index 0000000000..a678b0bd06 --- /dev/null +++ b/src/documentation/content/xdocs/components/hsmf/index.xml @@ -0,0 +1,65 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>POI-HSMF - Java API To Access Microsoft Outlook MSG Files</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Nick Burch" email="nick at apache dot org"/> + <person name="Travis Ferguson" email="uniformstupidity at gmail dot com"/> + </authors> + </header> + + <body> + <section> + <title>Overview</title> + + <p>HSMF is the POI Project's pure Java implementation of the Outlook MSG format.</p> + <p>At this time, it provides low-level read access to all of the file, along + with a user-facing way to get at the common textual content of MSG files. + to all</p> + <p>There is an example MSG textual renderer, which shows how to access the + common parts such as sender, subject, message body and examples. This is + in the + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hsmf/">HSMF examples area</a> + of SVN. You may also wish to look at the unit tests for more use guides.</p> + + <note> + This code currently lives the + <a href="https://github.com/apache/poi/tree/trunk/poi-scratchpad/src/main/java">scratchpad area</a> + of the POI Git repository. To use this component, ensure + you have the Scratchpad Jar on your classpath, or a dependency + defined on the <em>poi-scratchpad</em> artifact - the main POI + jar is not enough! See the + <a href="site:components">POI Components Map</a> + for more details. + </note> + <note> + This code is subject to change between versions, and being + "scratchpad", doesn't maintain the usual Apache POI backwards + compatibility guarantees. In particular, the way that property + values are fetched is expected to change soon, as part of the + work to improve fixed-length property support. + </note> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/index.xml b/src/documentation/content/xdocs/components/index.xml new file mode 100644 index 0000000000..7264361237 --- /dev/null +++ b/src/documentation/content/xdocs/components/index.xml @@ -0,0 +1,423 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - Component Overview</title> + <authors> + <person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/> + <person id="RK" name="Rainer Klute" email="klute@apache.org"/> + <person id="DF" name="David Fisher" email="dfisher@jmlafferty.com"/> + </authors> + </header> + <body> + <section><title>Apache POI Project Components</title> + <p>The Apache POI project is the master project for developing pure + Java ports of file formats based on Microsoft's OLE 2 Compound + Document Format. OLE 2 Compound Document Format is used by + Microsoft Office Documents, as well as by programs using MFC + property sets to serialize their document objects. + </p> + <p>Apache POI is also the master project for developing pure + Java ports of file formats based on Office Open XML (ooxml). + OOXML is part of an ECMA / ISO standardisation effort. This + documentation is quite large, but you can normally find the bit you + need without too much effort! + <a href="https://ecma-international.org/publications-and-standards/standards/ecma-376/">ECMA-376 standard is here</a>, + and is also under the + <a href="https://msdn.microsoft.com/en-us/openspecifications/default">Microsoft OSP</a>. + </p> + + + <section><title>POIFS for OLE 2 Documents</title> + <p> + POIFS is the oldest and most stable part of POI. It is our port of the OLE 2 Compound Document Format to + pure Java. It supports both read and write functionality. All of our components for the binary (non-XML) + Microsoft Office formats ultimately rely on it by + definition. Please see <a href="./poifs/index.html">the POIFS project page</a> for more information. + </p> + </section> + <section><title>HSSF and XSSF for Excel Documents</title> + <p> + HSSF is our port of the Microsoft Excel 97 (-2003) file format (BIFF8) to pure + Java. XSSF is our port of the Microsoft Excel XML (2007+) file format (OOXML) to + pure Java. SS is a package that provides common support for both formats with a common API. + They both support read and write capability. Please see + <a href="site:spreadsheet">the HSSF+XSSF project page</a> for more + information. + </p> + </section> + <section><title>HWPF and XWPF for Word Documents</title> + <p> + HWPF is our port of the Microsoft Word 97 (-2003) file format to pure + Java. It supports read, and limited write capabilities. It also provides + simple text extraction support for the older Word 6 and Word 95 formats. + Please see <a href="site:document">the HWPF project page for more + information</a>. This component remains in early stages of + development. It can already read and write simple files. + </p> + <p> + We are also working on the XWPF for the WordprocessingML (2007+) format from the + OOXML specification. This provides read and write support for simpler + files, along with text extraction capabilities. + </p> + </section> + <section><title>HSLF and XSLF for PowerPoint Documents</title> + <p> + HSLF is our port of the Microsoft PowerPoint 97(-2003) file format to pure + Java. It supports read and write capabilities. Please see <a + href="site:slideshow">the HSLF project page for more + information</a>. + </p> + <p> + We are also working on the XSLF for the PresentationML (2007+) format from the + OOXML specification. + </p> + </section> + <section><title>HPSF for OLE 2 Document Properties</title> + <p> + HPSF is our port of the OLE 2 property set format to pure + Java. Property sets are mostly use to store a document's properties + (title, author, date of last modification etc.), but they can be used + for application-specific purposes as well. + </p> + <p> + HPSF supports both reading and writing of properties. + </p> + <p> + Please see <a href="./hpsf/index.html">the HPSF project + page</a> for more information. + </p> + </section> + <section><title>HDGF and XDGF for Visio Documents</title> + <p> + HDGF is our port of the Microsoft Visio 97(-2003) file format to pure + Java. It currently only supports reading at a very low level, and + simple text extraction. Please see <a + href="./diagram/index.html">the HDGF / Diagram project page for more + information</a>. + </p> + <p> + XDGF is our port of the Microsoft Visio XML (.vsdx) file format to pure + Java. It has slightly more support than HDGF. Please see <a + href="./diagram/index.html">the XDGF / Diagram project page for more + information</a>. + </p> + </section> + <section><title>HPBF for Publisher Documents</title> + <p> + HPBF is our port of the Microsoft Publisher 98(-2007) file format to pure + Java. It currently only supports reading at a low level for around + half of the file parts, and simple text extraction. Please see <a + href="./hpbf/index.html">the HPBF project page for more + information</a>. + </p> + </section> + <section><title>HMEF for TNEF (winmail.dat) Outlook Attachments</title> + <p> + HMEF is our port of the Microsoft TNEF (Transport Neutral Encoding + Format) file format to pure Java. TNEF is sometimes used by Outlook + for encoding the message, and will typically come through as + winmail.dat. HMEF currently only supports reading at a low level, but + we hope to add text and attachment extraction. Please see <a + href="./hmef/index.html">the HMEF project page for more + information</a>. + </p> + </section> + <section><title>HSMF for Outlook Messages</title> + <p> + HSMF is our port of the Microsoft Outlook message file format to pure + Java. It currently only some of the textual content of MSG files, and + some attachments. Further support and documentation is coming in slowly. + For now, users are advised to consult the unit tests for example use. + Please see <a href="./hsmf/index.html">the HSMF project page for more + information</a>. + </p> + <p> + Microsoft has recently added the Outlook file format to its OSP. More information + is now available making implementing this API an easier task. + </p> + </section> + </section> + <section id="components"><title>Component Map</title> + <p> + The Apache POI distribution consists of support for many document file formats. This support is provided + in several Jar files. Not all of the Jars are needed for every format. The following tables + show the relationships between POI components, Maven repository tags, and the project's Jar files. + </p> + <table> + <tr> + <th>Component</th> + <th>Application type</th> + <th>Maven artifactId</th> + <th>Notes</th> + </tr> + <tr> + <td><a href="./poifs/index.html">POIFS</a></td> + <td>OLE2 Filesystem</td> + <td><em>poi</em></td> + <td>Required to work with OLE2 / POIFS based files</td> + </tr> + <tr> + <td><a href="./hpsf/index.html">HPSF</a></td> + <td>OLE2 Property Sets</td> + <td><em>poi</em></td> + <td> </td> + </tr> + <tr> + <td><a href="site:spreadsheet">HSSF</a></td> + <td>Excel XLS</td> + <td><em>poi</em></td> + <td>For HSSF only, if common SS is needed see below</td> + </tr> + <tr> + <td><a href="site:slideshow">HSLF</a></td> + <td>PowerPoint PPT</td> + <td><em>poi-scratchpad</em></td> + <td> </td> + </tr> + <tr> + <td><a href="site:document">HWPF</a></td> + <td>Word DOC</td> + <td><em>poi-scratchpad</em></td> + <td> </td> + </tr> + <tr> + <td><a href="./diagram/index.html">HDGF</a></td> + <td>Visio VSD</td> + <td><em>poi-scratchpad</em></td> + <td> </td> + </tr> + <tr> + <td><a href="./hpbf/index.html">HPBF</a></td> + <td>Publisher PUB</td> + <td><em>poi-scratchpad</em></td> + <td> </td> + </tr> + <tr> + <td><a href="./hsmf/index.html">HSMF</a></td> + <td>Outlook MSG</td> + <td><em>poi-scratchpad</em></td> + <td> </td> + </tr> + <tr> + <td>DDF</td> + <td>Escher common drawings</td> + <td><em>poi</em></td> + <td> </td> + </tr> + <tr> + <td>HWMF</td> + <td>WMF drawings</td> + <td><em>poi-scratchpad</em></td> + <td> </td> + </tr> + <tr> + <td><a href="./oxml4j/index.html">OpenXML4J</a></td> + <td>OOXML</td> + <td><em>poi-ooxml</em> plus either <em>poi-ooxml-lite</em> or<br/> + <em>poi-ooxml-full</em></td> + <td>See notes below for differences between these options</td> + </tr> + <tr> + <td><a href="site:spreadsheet">XSSF</a></td> + <td>Excel XLSX</td> + <td><em>poi-ooxml</em></td> + <td> </td> + </tr> + <tr> + <td><a href="site:slideshow">XSLF</a></td> + <td>PowerPoint PPTX</td> + <td><em>poi-ooxml</em></td> + <td> </td> + </tr> + <tr> + <td><a href="site:document">XWPF</a></td> + <td>Word DOCX</td> + <td><em>poi-ooxml</em></td> + <td> </td> + </tr> + <tr> + <td><a href="./diagram/index.html">XDGF</a></td> + <td>Visio VSDX</td> + <td><em>poi-ooxml</em></td> + <td> </td> + </tr> + <tr> + <td><a href="./slideshow/index.html">Common SL</a></td> + <td>PowerPoint PPT and PPTX</td> + <td><em>poi-scratchpad</em> and <em>poi-ooxml</em></td> + <td>SL code is in the core POI jar, but implementations are in poi-scratchpad + and poi-ooxml.</td> + </tr> + <tr> + <td><a href="site:spreadsheet">Common SS</a></td> + <td>Excel XLS and XLSX</td> + <td><em>poi-ooxml</em></td> + <td>WorkbookFactory and friends all require poi-ooxml, not just core poi</td> + </tr> + </table> + + <p><br /></p> + + <p> + This table maps artifacts into the jar file name. "version-yyyymmdd" is + the POI version stamp. You can see what the latest stamp is on the + <a href="site:download">downloads page</a>. + </p> + <table> + <tr> + <th>Maven artifactId</th> + <th>Prerequisites</th> + <th>JAR</th> + </tr> + <tr> + <td>poi</td> + <td><a href="https://search.maven.org/#artifactdetails|org.apache.logging.log4j|log4j-api|2.24.3|jar">log4j 2.x</a>, + <a href="https://search.maven.org/#artifactdetails|commons-codec|commons-codec|1.17.1|jar">commons-codec</a>, + <a href="https://search.maven.org/#artifactdetails|org.apache.commons|commons-collections4|4.4|jar">commons-collections</a>, + <a href="https://search.maven.org/#artifactdetails|org.apache.commons|commons-math3|3.6.1|jar">commons-math3</a> + <a href="https://search.maven.org/#artifactdetails|commons-io|commons-io|2.20.0|jar">commons-io</a> + </td> + <td>poi-version-yyyymmdd.jar</td> + </tr> + <tr> + <td>poi-scratchpad</td> + <td><a href="https://search.maven.org/#search|gav|1|g:org.apache.poi AND a:poi">poi</a></td> + <td>poi-scratchpad-version-yyyymmdd.jar</td> + </tr> + <tr> + <td>poi-ooxml</td> + <td><a href="https://search.maven.org/#search|gav|1|g:org.apache.poi AND a:poi">poi</a>, + <a href="https://search.maven.org/#search|gav|1|g:org.apache.poi AND a:poi-ooxml-lite">poi-ooxml-lite</a>, + <a href="https://search.maven.org/#artifactdetails|org.apache.commons|commons-compress|1.23.0|jar">commons-compress</a>, + <a href="https://search.maven.org/#artifactdetails|com.zaxxer|SparseBitSet|1.2|jar">SparseBitSet</a><br/> + For SVG support: + <a href="https://search.maven.org/#search|gav|1|g:org.apache.xmlgraphics AND a:batik-all">batik-all</a>, + <a href="https://search.maven.org/#search|gav|1|g:xml-apis AND a:xml-apis-ext">xml-apis-ext</a>, + <a href="https://search.maven.org/#search|gav|1|g:org.apache.xmlgraphics AND a:xmlgraphics-commons">xmlgraphics-commons</a><br/> + For PDF support: + <a href="https://search.maven.org/#search|gav|1|g:org.apache.pdfbox AND a:pdfbox">pdfbox</a>, + <a href="https://search.maven.org/#search|gav|1|g:org.apache.pdfbox AND a:fontbox">fontbox</a>, + <a href="https://search.maven.org/#search|gav|1|g:de.rototor.pdfbox AND a:graphics2d">rototor graphics2d</a> + </td> + <td>poi-ooxml-version-yyyymmdd.jar</td> + </tr> + <tr> + <td>poi-ooxml-lite</td> + <td><a href="https://search.maven.org/#artifactdetails|org.apache.xmlbeans|xmlbeans|5.3.0|jar">xmlbeans</a></td> + <td>poi-ooxml-lite-version-yyyymmdd.jar</td> + </tr> + <tr> + <td>poi-examples</td> + <td><a href="https://search.maven.org/#search|gav|1|g:org.apache.poi AND a:poi">poi</a>, + <a href="https://search.maven.org/#search|gav|1|g:org.apache.poi AND a:poi-scratchpad">poi-scratchpad</a>, + <a href="https://search.maven.org/#search|gav|1|g:org.apache.poi AND a:poi-ooxml">poi-ooxml</a> + </td> + <td>poi-examples-version-yyyymmdd.jar</td> + </tr> + <tr> + <td>poi-ooxml-full (known as ooxml-schemas)</td> + <td><a href="https://search.maven.org/#artifactdetails|org.apache.xmlbeans|xmlbeans|5.3.0|jar">xmlbeans</a><br/> + For signing: + <a href="https://search.maven.org/#artifactdetails|org.bouncycastle|bcpkix-jdk18on|1.81|jar">bcpkix-jdk18on</a>, + <a href="https://search.maven.org/#artifactdetails|org.bouncycastle|bcutil-jdk18on|1.81|jar">bcprov-jdk18on</a>, + <a href="https://search.maven.org/#artifactdetails|org.apache.santuario|xmlsec|3.0.6|bundle">xmlsec</a>, + <a href="https://search.maven.org/#artifactdetails|org.slf4j|slf4j-api|2.0.17|jar">slf4j-api</a> + </td> + <td>poi-ooxml-full-version-yyyymmdd.jar</td> + </tr> + </table> + + <p> </p> + <note> + Apache commons-math3 and commons-compress were added as a dependency in POI 4.0.0.<br/> + Zaxxer SparseBitSet was added as a dependency in POI 4.1.2<br/> + Apache commons-io was added as a dependency in POI 5.1.0 + </note> + <p> + poi-ooxml requires poi-ooxml-lite. This is a substantially smaller + version of the poi-ooxml-full jar (ooxml-schemas-1.4.jar for POI 4.0.0, + ooxml-schemas-1.3.jar for POI 3.14 or to POI 3.17, + ooxml-schemas-1.1.jar for POI 3.7 up to POI 3.13, ooxml-schemas-1.0.jar + for POI 3.5 and 3.6). + The larger poi-ooxml-full (formerly, ooxml-schemas) jar is <a href="../help/index.html#faq-N10025">normally</a> + only required for features that are not fully implemented in poi-ooxml. + There used to also be an ooxml-security jar, which contained + all of the classes relating to encryption and signing. POI 5 no longer needs this jar. + The equivalent classes are now in poi-ooxml-full and poi-ooxml-lite. + This JAR was ooxml-security-1.1.jar for POI 3.14 and POI 4. ooxml-security-1.0.jar + was used prior to that. + </p> + <p> + The OOXML jars require a stax implementation, but now that Apache + POI requires Java 8, that dependency is provided by the JRE and no additional + stax jars are required. The OOXML jars used to require DOM4J, but + the code has now been changed to use JAXP and no additional dom4j + jars are required. By the way, look at this <a href="../help/index.html#faq-N1017E">FAQ</a> + if you have problems when using a non-Oracle JDK. + </p> + <p> + The ooxml schemas jars are compiled with <a href="https://xmlbeans.apache.org/">Apache XMLBeans</a>. + It is recommended that you use the XMLBeans version that was used to build the POI OOXML schemas. + It may be possible to use newer XMLBeans jars but there are no guarantees, especially if the XMLBeans version + numbers differ a lot. + </p> + </section> + <section><title>Examples</title> + <p> + Small sample programs using the POI API are available in the + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples">src/examples</a> + (<a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples">viewvc</a>) directory of the source distribution. + </p> + <p> + All of the examples are included in POI distributions as a poi-examples artifact. + </p> + </section> + <section><title>Running POI on other JVM languages</title> + <p> + POI can be run on most languages that run on the JVM. For code examples, + see <a href="poi-jvm-languages.html">Running POI on other JVM languages</a> + </p> + </section> + <section><title>Contributed Software</title> + <p> + Besides the "official" components outlined above there is some further + software distributed with POI. This is called "contributed" software. It + is not explicitly recommended or even maintained by the POI team, but + it might still be useful to you. + </p> + <p> + See <a href="poi-ruby.html">POI Ruby Bindings</a> and other code in the + <a + href="https://github.com/apache/poi/tree/trunk/src/contrib/">poi-contrib module</a> + </p> + </section> + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/components/logging.xml b/src/documentation/content/xdocs/components/logging.xml new file mode 100644 index 0000000000..10518acca8 --- /dev/null +++ b/src/documentation/content/xdocs/components/logging.xml @@ -0,0 +1,290 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - Logging Framework</title> + <authors> + <person id="DS" name="Dominik Stadler" email="centic@apache.org"/> + <person id="MV" name="Marius Volkhart" email="mariusvolkhart@apache.org"/> + </authors> + </header> + + <body> + <section> + <title>Introduction</title> + <p> + Logging in POI is used primarily as a debugging mechanism, not a normal runtime + logging system. Logging at levels noisier than WARN is ONLY for autopsy type debugging, and should + NEVER be enabled on a production system. + </p> + </section> + <section> + <title>POI 5.1.0 and above</title> + <p> + Since version 5.1.0 Apache POI uses <a href="https://logging.apache.org/log4j/2.x/">Apache Log4j v2</a> directly. + </p> + <p> + Apache POI only depends on log4j-api and allows choosing which logging framework to use. log4j-core is + just one of many options. + If you want to continue to use another SLF4J compatible logging framework, you can deploy the + <a href="https://logging.apache.org/log4j/log4j-2.2/log4j-to-slf4j/index.html">log4j-to-slf4j</a> jar to + facilitate this. + </p> + <p> + POI tries to name loggers after the canonical name of the containing class. For example, + <code>org.apache.poi.poifs.filesystem.POIFSFileSystem</code>. Use your logging framework's typical + mechanisms for activating and deactivating logging for specific loggers. + </p> + <p> + All loggers are named <code>com.apache.poi.*</code>, so rules applied to <code>com.apache.poi</code> + will affect all POI loggers. + </p> + </section> + <section> + <title>Logging with Log4j 2 Core</title> + <p> + Capturing POI logs using Log4j 2 Core is as simple as including the + <a href="https://logging.apache.org/log4j/2.x/maven-artifacts.html"><code>log4j-core</code></a> JAR in + your project. POI also has dependencies on libraries that make use of the SLF4J and Apache Commons + Logging APIs. Gather logs from these dependencies by adding the + <a href="https://logging.apache.org/log4j/2.x/log4j-jcl/index.html">Commons Logging Bridge</a> and the + the <a href="https://logging.apache.org/log4j/2.x/log4j-slf4j-impl/index.html">SLF4J Binding</a> to your + project. + </p> + <p> + The simplest configuration is to capture all POI logs at the same level as your application. You might + want to collect all messages <code>INFO</code> and higher, and are OK with capturing POI messages as well. + </p> + <source> + <Configuration ...> + <Loggers> + <Root level="INFO"> + ... + </Root> + </Loggers> + </Configuration> + </source> + + <p> + A more recommended configuration is to capture only messages from loggers you opt in to. For example, + you might want to capture all messages from <code>com.example.myapplication</code> at <code>INFO</code> + but only POI messages at <code>WARN</code> or more severe. + </p> + <source> + <Configuration ...> + <Loggers> + <Logger name="com.example.myapplication" level="INFO" /> + <Logger name="org.apache.poi" level="WARN" /> + + <Root level="OFF"> + ... + </Root> + </Loggers> + </Configuration> + </source> + + <p>Another strategy you may decide to use is to capture all messages except those coming from POI.</p> + <source> + <Configuration ...> + <Loggers> + <Logger name="org.apache.poi" level="OFF" /> + + <Root level="INFO"> + ... + </Root> + </Loggers> + </Configuration> + </source> + </section> + <section> + <title>Log4J SimpleLogger</title> + <p> + If your main aim is just to get rid of the scary logging log message from Log4J that says + 'ERROR StatusLogger Log4j2 could not find a logging implementation.', then one option is to + enable the SimpleLogger using a system property. + </p> + <p> + -Dlog4j2.loggerContextFactory=org.apache.logging.log4j.simple.SimpleLoggerContextFactory + </p> + </section> + <section> + <title>Logging with SLF4J</title> + <p> + If you want to continue to use another SLF4J compatible logging framework, you can deploy the + <a href="https://logging.apache.org/log4j/log4j-2.2/log4j-to-slf4j/index.html">log4j-to-slf4j</a> jar + and the intended slf4j-bridges to facilitate this. + </p> + <p> + See <a href="https://www.slf4j.org/">https://www.slf4j.org/</a> for more details about using SLF4J. + </p> + </section> + <section> + <title>Logging with Logback</title> + <p> + Capturing POI logs using Logback requires adding the + <a href="https://logging.apache.org/log4j/2.x/log4j-to-slf4j/index.html">Log4j to SLF4J Adapter</a> to + your project, along with the standard Logback dependencies. POI also has dependencies on libraries that + make use of the SLF4J and Apache Commons Logging APIs. Gather logs from these dependencies by adding the + <a href="https://www.slf4j.org/legacy.html#jcl-over-slf4j">Commons Logging Bridge</a> to your project. + </p> + + <p> + The simplest configuration is to capture all POI logs at the same level as your application. You might + want to collect all messages <code>INFO</code> and higher, and are OK with capturing POI messages as well. + </p> + <source> + <configuration ...> + <root level="INFO"> + ... + </root> + </configuration> + </source> + + <p> + A more recommended configuration is to capture only messages from loggers you opt in to. For example, + you might want to capture all messages from <code>com.example.myapplication</code> at <code>INFO</code> + but only POI messages at <code>WARN</code> or more severe. + </p> + <source> + <configuration ...> + <logger name="com.example.myapplication" level="INFO" /> + <logger name="org.apache.poi" level="WARN" /> + + <root level="OFF"> + ... + </root> + </configuration> + </source> + + <p>Another strategy you may decide to use is to capture all messages except those coming from POI.</p> + <source> + <configuration ...> + <logger name="org.apache.poi" level="OFF" /> + + <root level="INFO"> + ... + </root> + </configuration> + </source> + </section> + <section> + <title>POI 5.0.0</title> + <p> + POI 5.0.0 switched to using <a href="https://www.slf4j.org/">SLF4J</a> for logging. If you want + to enable logging, please read up on the various SLF4J compatible logging frameworks. + <a href="https://logging.apache.org/log4j/2.x/">Apache Log4j v2</a> is a good choice. + <a href="https://logback.qos.ch/">Logback</a> is also widely used. + </p> + </section> + <section> + <title>Legacy POI Logging Framework (no longer supported in POI 5.0.0 and above)</title> + <p> + Prior to POI 5.0.0, POI used a custom logging framework which allows to configure where logs are sent to. + </p> + <p> + Logging in POI 3 and 4 is used only as a debugging mechanism, not as a normal runtime + logging system. Logging at level debug/info is ONLY for debugging, and should + NEVER be enabled on a production system. + </p> + <p> + The framework is extensible so that you can send log messages to any logging framework + that your application uses. + </p> + <p> + A number of default logging implementations are supported by POI out-of-the-box and can be selected via a + system property. + </p> + </section> + <section><title>POI 4.x and before: Enable Legacy POI Logging Framework</title> + <p> + By default, logging is disabled in POI 3 and 4. Sometimes, it might be useful + to enable logging to see some debug messages printed out which can + help in analyzing problems. + </p> + <p> + You can select the logging framework by setting the system property <em>org.apache.poi.util.POILogger</em> during application startup or by calling System.setProperty(): + </p> + <source> + System.setProperty("org.apache.poi.util.POILogger", "org.apache.poi.util.CommonsLogger" ); + </source> + <p> + Note: You need to call <em>setProperty()</em> before any POI functionality is invoked as the logger is only initialized during startup. + </p> + </section> + <section><title>POI 4.x and before: Available Legacy POI Logging Framework implementations</title> + <p> + The following logger implementations are provided by POI 3 and 4: + </p> + <table> + <tr> + <th>Class</th> + <th>Type</th> + </tr> + <tr> + <td>org.apache.poi.util.SystemOutLogger</td> + <td>Sends log output to the system console</td> + </tr> + <tr> + <td>org.apache.poi.util.NullLogger</td> + <td>Default logger, does not log anything</td> + </tr> + <tr> + <td>org.apache.poi.util.CommonsLogger</td> + <td>Allows to use <a href="https://commons.apache.org/proper/commons-logging/">Apache Commons Logging</a> for logging. This can use JDK1.4 logging, + log4j, logkit, etc. The log4j dependency was removed in POI 5.0.0, so you will need to include this dependency yourself if you need it.</td> + </tr> + <tr> + <td>org.apache.poi.util.DummyPOILogger</td> + <td>Simple logger which will keep all log-lines in memory for later analysis (this class is not in the jar, just in the test source). + Used primarily for testing. Note: this may cause a memory leak if used in production application!</td> + </tr> + </table> + </section> + <section><title>POI 4.x and before: Sending logs to a different log framework</title> + <p> + You can send logs to other logging frameworks by implementing the interface <em>org.apache.poi.util.POILogger</em>. + </p> + </section> + <section><title>POI 4.x and before: Implementation details</title> + <p> + Every class uses a <code>POILogger</code> to log, and gets it using a static method + of the <code>POILogFactory</code> . + </p> + <p> + Each class in POI can log using a <code>POILogger</code>, which is an abstract class. + We decided to make our own logging facade because:</p> + <ol> + <li>we need to log many values and we put many methods in this class to facilitate the + programmer, without having him write string concatenations;</li> + <li>we need to be able to use POI without any logger package present.</li> + </ol> + </section> + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/components/oxml4j/index.xml b/src/documentation/content/xdocs/components/oxml4j/index.xml new file mode 100644 index 0000000000..06cf00d20a --- /dev/null +++ b/src/documentation/content/xdocs/components/oxml4j/index.xml @@ -0,0 +1,45 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>POI-OpenXML4J - Java API To Access Office Open XML documents</title> + <subtitle>Overview</subtitle> + </header> + + <body> + <section> + <title>Overview</title> + <p>OpenXML4J is the POI Project's pure Java implementation of the Open Packaging Conventions (OPC) defined in + <a href="https://ecma-international.org/publications-and-standards/standards/ecma-376/">ECMA-376</a>.</p> + <p>Every OpenXML file comprises a collection of byte streams called parts, combined into a container called a package. + POI OpenXML4J provides a physical implementation of the OPC that uses the Zip file format.</p> + </section> + <section> + <title>History</title> + <p>OpenXML4J was originally developed by + <a href="https://web.archive.org/web/20090611063015/https://www.openxml4j.org/">openxml4j.org</a>, + and was contributed to Apache POI in 2008. The original code is available at + <a href="https://sourceforge.net/projects/openxml4j/">https://sourceforge.net/projects/openxml4j/</a>. + Thanks to the support and guidance of Julien Chable</p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/poi-jvm-languages.xml b/src/documentation/content/xdocs/components/poi-jvm-languages.xml new file mode 100644 index 0000000000..26ab85094d --- /dev/null +++ b/src/documentation/content/xdocs/components/poi-jvm-languages.xml @@ -0,0 +1,351 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>JVM languages</title> + <authors> + <person id="JO" name="Javen O'Neal" email="onealj@apache.org"/> + </authors> + </header> + + <body> + <section><title>Intro</title> + <p> + Apache POI can be used with any + <a href="https://en.wikipedia.org/wiki/List_of_JVM_languages">JVM language</a> + that can import Java jar files such as Jython, Groovy, Scala, Kotlin, and JRuby. + </p> + <ul> + <li><a href="#Jython+example">Jython</a></li> + <li><a href="#Scala+example">Scala</a></li> + <li><a href="#Groovy+example">Groovy</a></li> + <li><a href="#Clojure+example">Clojure</a></li> + </ul> + </section> + + + <section><title>Tested Environments</title> + <ul> + <li><a href="https://www.jython.org/">Jython</a> 2.5+ (older versions probably work, but are untested)</li> + <li><a href="https://www.scala-lang.org/">Scala</a> 2.x</li> + <li><a href="https://groovy-lang.org/">Groovy</a> 2.4 (anything from 1.6 onwards ought to work, but only the latest 2.4 releases have been tested by us)</li> + <li><a href="https://clojure.org/">Clojure</a> 1.5.1+</li> + </ul> + <p>If you use POI in a different language (Kotlin, JRuby, ...) and would like to share a <em>Hello POI!</em> example, + please share it.</p> + <p>Please <a href="site:mailinglists">let us know</a> if you use POI in an environment not listed here</p> + </section> + + <!-- FIXME: Need to make each language section expandable/collapseable so that users can compare their language to Java on one screen. See https://jsfiddle.net/eJX8z/ for an example implementation. --> + <section><title>Java code</title> + <section><title>POILanguageExample.java</title> + <source> <!-- lang="java" --> + // include poi-{version}-{yyyymmdd}.jar, poi-ooxml-{version}-{yyyymmdd}.jar, + // and poi-ooxml-lite-{version}-{yyyymmdd}.jar on Java classpath + + // Import the POI classes + import java.io.File; + import java.io.FileOutputStream; + import java.io.OutputStream; + import org.apache.poi.ss.usermodel.Cell; + import org.apache.poi.ss.usermodel.Row; + import org.apache.poi.ss.usermodel.Sheet; + import org.apache.poi.ss.usermodel.Workbook; + import org.apache.poi.ss.usermodel.WorkbookFactory; + import org.apache.poi.ss.usermodel.DataFormatter; + + // Read the contents of the workbook + File f = new File("SampleSS.xlsx"); + Workbook wb = WorkbookFactory.create(f); + DataFormatter formatter = new DataFormatter(); + int i = 1; + int numberOfSheets = wb.getNumberOfSheets(); + for ( Sheet sheet : wb ) { + System.out.println("Sheet " + i + " of " + numberOfSheets + ": " + sheet.getSheetName()); + for ( Row row : sheet ) { + System.out.println("\tRow " + row.getRowNum()); + for ( Cell cell : row ) { + System.out.println("\t\t"+ cell.getAddress().formatAsString() + ": " + formatter.formatCellValue(cell)); + } + } + } + + // Modify the workbook + Sheet sh = wb.createSheet("new sheet"); + Row row = sh.createRow(7); + Cell cell = row.createCell(42); + cell.setActiveCell(true); + cell.setCellValue("The answer to life, the universe, and everything"); + + // Save and close the workbook + OutputStream fos = new FileOutputStream("SampleSS-updated.xlsx"); + wb.write(fos); + fos.close(); + </source> + </section> <!-- POILanguageExample.java --> + </section> <!-- Java code --> + + <section><title>Jython example</title> + <source> <!-- lang="python" --> + # Add <a href="site:components">poi jars</a> onto the python classpath or add them at run time + import sys + for jar in ('poi', 'poi-ooxml', 'poi-ooxml-lite'): + sys.path.append('/path/to/%s-5.4.1.jar') + + from java.io import File, FileOutputStream + from contextlib import closing + + # Import the POI classes + from org.apache.poi.ss.usermodel import <a href="../apidocs/dev/org/apache/poi/ss/usermodel/WorkbookFactory.html">WorkbookFactory</a>, <a href="../apidocs/dev/org/apache/poi/ss/usermodel/DataFormatter.html">DataFormatter</a> + + # Read the contents of the workbook + wb = WorkbookFactory.create(File('<a href="https://github.com/apache/poi/tree/trunk/test-data/spreadsheet/SampleSS.xlsx">SampleSS.xlsx</a>')) + formatter = DataFormatter() + for i, sheet in enumerate(wb, start=1): + print('Sheet %d of %d: %s'.format(i, wb.numberOfSheets, sheet.sheetName)) + for row in sheet: + print('\tRow %i' % row.rowNum) + for cell in row: + print('\t\t%s: %s' % (cell.address, formatter.formatCellValue(cell))) + + # Modify the workbook + sh = wb.createSheet('new sheet') + row = sh.createRow(7) + cell = sh.createCell(42) + cell.activeCell = True + cell.cellValue = 'The answer to life, the universe, and everything' + + # Save and close the workbook + with closing(FileOutputStream('SampleSS-updated.xlsx')) as fos: + wb.write(fos) + wb.close() + </source> + <p>There are several websites that have examples of using Apache POI in Jython projects: + <a href="https://wiki.python.org/jython/PoiExample">python.org</a>, + <a href="https://www.jython.org/jythonbook/en/1.0/appendixB.html#working-with-spreadsheets">jython.org</a>, and many others. + </p> + </section> + + <section><title>Scala example</title> + <section><title>build.sbt</title> + <source> <!-- lang="scala" --> + // Add the POI core and OOXML support dependencies into your build.sbt + libraryDependencies ++= Seq( + "org.apache.poi" % "poi" % "5.4.1", + "org.apache.poi" % "poi-ooxml" % "5.4.1", + "org.apache.poi" % "poi-ooxml-lite" % "5.4.1" + ) + </source> + </section> + <section><title>XSSFMain.scala</title> + <source> <!-- lang="scala" --> + // Import the required classes + import org.apache.poi.ss.usermodel.{<a href="../apidocs/dev/org/apache/poi/ss/usermodel/WorkbookFactory.html">WorkbookFactory</a>, <a href="../apidocs/dev/org/apache/poi/ss/usermodel/DataFormatter.html">DataFormatter</a>} + import java.io.{File, FileOutputStream} + + object XSSFMain extends App { + + // Automatically convert Java collections to Scala equivalents + import scala.collection.JavaConversions._ + + // Read the contents of the workbook + val workbook = WorkbookFactory.create(new File("<a href="https://github.com/apache/poi/tree/trunk/test-data/spreadsheet/SampleSS.xlsx">SampleSS.xlsx</a>")) + val formatter = new DataFormatter() + for { + // Iterate and print the sheets + (sheet, i) <- workbook.zipWithIndex + _ = println(s"Sheet $i of ${workbook.getNumberOfSheets}: ${sheet.getSheetName}") + + // Iterate and print the rows + row <- sheet + _ = println(s"\tRow ${row.getRowNum}") + + // Iterate and print the cells + cell <- row + } { + println(s"\t\t${cell.getCellAddress}: ${formatter.formatCellValue(cell)}") + } + + // Add a sheet to the workbook + val sheet = workbook.createSheet("new sheet") + val row = sheet.createRow(7) + val cell = row.createCell(42) + cell.setAsActiveCell() + cell.setCellValue("The answer to life, the universe, and everything") + + // Save the updated workbook as a new file + val fos = new FileOutputStream("SampleSS-updated.xlsx") + workbook.write(fos) + workbook.close() + } + </source> + </section> + </section> + + <section><title>Groovy example</title> + <section><title>build.gradle</title> + <source> <!-- lang="groovy" --> +// Add the POI core and OOXML support dependencies into your gradle build, +// along with all of Groovy so it can run as a standalone script +repositories { + mavenCentral() +} +dependencies { + runtime 'org.codehaus.groovy:groovy-all:2.5.15' + runtime 'org.apache.poi:poi:5.4.1' + runtime 'org.apache.poi:poi-ooxml:5.4.1' +} + </source> + </section> + <section><title>SpreadSheetDemo.groovy</title> + <source> <!-- lang="groovy" --> +import org.apache.poi.ss.usermodel.* +import org.apache.poi.ss.util.* +import java.io.File + +if (args.length == 0) { + println "Use:" + println " SpreadSheetDemo <excel-file> [output-file]" + return 1 +} + +File f = new File(args[0]) +DataFormatter formatter = new DataFormatter() +WorkbookFactory.create(f,null,true).withCloseable { workbook -> + println "Has ${workbook.getNumberOfSheets()} sheets" + + // Dump the contents of the spreadsheet + (0..<workbook.getNumberOfSheets()).each { sheetNum -> + println "Sheet ${sheetNum} is called ${workbook.getSheetName(sheetNum)}" + + def sheet = workbook.getSheetAt(sheetNum) + sheet.each { row -> + def nonEmptyCells = row.grep { c -> c.getCellType() != Cell.CELL_TYPE_BLANK } + println " Row ${row.getRowNum()} has ${nonEmptyCells.size()} non-empty cells:" + nonEmptyCells.each { c -> + def cRef = [c] as CellReference + println " * ${cRef.formatAsString()} = ${formatter.formatCellValue(c)}" + } + } + } + + // Add two new sheets and populate + CellStyle headerStyle = makeHeaderStyle(workbook) + Sheet ns1 = workbook.createSheet("Generated 1") + exportHeader(ns1, headerStyle, null, ["ID","Title","Num"] as String[]) + ns1.createRow(1).createCell(0).setCellValue("TODO - Populate with data") + + Sheet ns2 = workbook.createSheet("Generated 2") + exportHeader(ns2, headerStyle, "This is a demo sheet", + ["ID","Title","Date","Author","Num"] as String[]) + ns2.createRow(2).createCell(0).setCellValue(1) + ns2.createRow(3).createCell(0).setCellValue(4) + ns2.createRow(4).createCell(0).setCellValue(1) + + // Save + File output = File.createTempFile("output-", (f.getName() =~ /(\.\w+$)/)[0][0]) + output.withOutputStream { os -> workbook.write(os) } + println "Saved as ${output}" +} + +CellStyle makeHeaderStyle(Workbook wb) { + int HEADER_HEIGHT = 18 + CellStyle style = wb.createCellStyle() + + style.setFillForegroundColor(IndexedColors.AQUA.getIndex()) + style.setFillPattern(FillPatternType.SOLID_FOREGROUND) + + Font font = wb.createFont() + font.setFontHeightInPoints((short)HEADER_HEIGHT) + font.setBold(true) + style.setFont(font) + + return style +} +void exportHeader(Sheet s, CellStyle headerStyle, String info, String[] headers) { + Row r + int rn = 0 + int HEADER_HEIGHT = 18 + // Do they want an info row at the top? + if (info != null && !info.isEmpty()) { + r = s.createRow(rn) + r.setHeightInPoints(HEADER_HEIGHT+1) + rn++ + + Cell c = r.createCell(0) + c.setCellValue(info) + c.setCellStyle(headerStyle) + s.addMergedRegion(new CellRangeAddress(0,0,0,headers.length-1)) + } + // Create the header row, of the right size + r = s.createRow(rn) + r.setHeightInPoints(HEADER_HEIGHT+1) + // Add the column headings + headers.eachWithIndex { col, idx -> + Cell c = r.createCell(idx) + c.setCellValue(col) + c.setCellStyle(headerStyle) + s.autoSizeColumn(idx) + } + // Make all the columns filterable + s.setAutoFilter(new CellRangeAddress(rn, rn, 0, headers.length-1)) +} + </source> + </section> + </section> + + <section><title>Clojure example</title> + <section><title>SpreadSheetDemo.clj</title> + <!-- code example provided by Blake Watson --> + <source> <!-- lang="clojure" --> +(ns poi.core + (:gen-class) + (:use [clojure.java.io :only [input-stream]]) + (:import [org.apache.poi.ss.usermodel WorkbookFactory DataFormatter])) + + +(defn sheets [wb] (map #(.getSheetAt wb %1) (range 0 (.getNumberOfSheets wb)))) + +(defn print-all [wb] + (let [df (DataFormatter.)] + (doseq [sheet (sheets wb)] + (doseq [row (seq sheet)] + (doseq [cell (seq row)] + (println (.formatAsString (.getAddress cell)) ": " (.formatCellValue df cell))))))) + +(defn -main [& args] + (when-let [name (first args)] + (let [wb (WorkbookFactory/create (input-stream name))] + (print-all wb)))) + </source> + </section> + </section> + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/components/poi-ruby.xml b/src/documentation/content/xdocs/components/poi-ruby.xml new file mode 100644 index 0000000000..ba7ceb586e --- /dev/null +++ b/src/documentation/content/xdocs/components/poi-ruby.xml @@ -0,0 +1,151 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>POI Ruby Bindings</title> + <authors> + <person id="AS" name="Avik Sengupta" email="avik@apache.org"/> + </authors> + </header> + + <body> + <section><title>Intro</title> + <p>The POI library can now be compiled as a Ruby extension, allowing the API to be called from + Ruby language programs. Ruby users can therefore read and write OLE2 documents, such as Excel files + with ease + </p> + <p>The bindings are generated by compiling POI with <a href="https://gcc.gnu.org/java/">gcj</a>, + and generating the Ruby wrapper using <a href="https://www.swig.org">SWIG</a>. The aim is the keep + the POI api as-is. However, where java standard library objects are used, an effort is made to transform them smoothly + into Ruby objects. Therefore, where the POI API takes an OutputStream, you can pass an IO object. Where the POI works + java.util.Date or java.util.Calendar object, you can work with a Ruby Time object. </p> + </section> + + + <section><title>Getting Started</title> + <section><title>Pre-Requisites</title> + <p>The bindings have been developed with GCC 3.4.3 and Ruby 1.8.2. You are unlikely to get correct results with + versions of GCC prior to 3.4 or versions of Ruby prior to 1.8. To compile the Ruby extension, you must have + GCC (compiled with java language support), Ruby development headers, and SWIG. To run, you will need Ruby (obviously!) and + <em>libgcj </em>, presumably from the same version of GCC with which you compiled. + </p> + </section> + <section><title>Source Repository</title> + <p> + The POI-Ruby module sits under the POI <a href="https://github.com/apache/poi/tree/trunk/src/contrib/poi-ruby/">Git</a>. + Running <em>make</em> inside that directory will create a loadable ruby extension <em>poi4r.so</em> in the release subdirectory. Tests + are in the <em>tests/</em> subdirectory, and should be run from the <em>poi-ruby</em> directory. Please read the tests to figure out the usage. + </p> + <p>Note that the makefile, though designed to work across Linux/OS X/Cygwin, has been tested only on linux. + There are likely to be issues on other platform; fixes gratefully accepted! </p> + </section> + <section><title>Binary</title> + <p>A version of poi4r.so is available <a href="https://www.apache.org/~avik/dist/poi4r.so">here</a> (broken link). Its been compiled on a linux box + with GCC 3.4.3 and Ruby 1.8.2. It dynamically links to libgcj. No guarantees about working on any other box. </p> + </section> + </section> + + + + + <section> + <title>Usage</title> + <p>The following ruby code shows some of the things you can do with POI in Ruby</p> + <source> + h=Poi4r::HSSFWorkbook.new + #Test Sheet Creation + s=h.createSheet("Sheet1") + + #Test setting cell values + s=h.getSheetAt(0) + r=s.createRow(0) + c=r.createCell(0) + c.setCellValue(1.5) + + c=r.createCell(1) + c.setCellValue("Ruby") + + #Test styles + st = h.createCellStyle() + c=r.createCell(2) + st.setAlignment(Poi4r::HSSFCellStyle.ALIGN_CENTER) + c.setCellStyle(st) + c.setCellValue("centr'd") + + #Date handling + c=r.createCell(3) + t1=Time.now + c.setCellValue(Time.now) + t2= c.getDateCellValue().gmtime + + st=h.createCellStyle(); + st.setDataFormat(Poi4r::HSSFDataFormat.getBuiltinFormat("m/d/yy h:mm")) + c.setCellStyle(st) + + #Formulas + c=r.createCell(4) + c.setCellFormula("A1*2") + c.getCellFormula() + + #Writing + h.write(File.new("test.xls","w")) + </source> + <p> The <em>tc_base_tests.rb</em> file in the <em>tests</em> sub directory of the source distribution + contains examples of simple uses of the API. The <a href="spreadsheet/quick-guide.html">quick guide </a> is the best + place to learn HSSF API use. (Note however that none of the Drawing features are implemented in the Ruby binding.) + See also the <a href="site:javadocs">POI API documentation</a> for more details. + </p> + </section> + + <section> + <title>Future Directions</title> + <section><title>TODO's</title> + <ul> + <li>Implement support for reading Excel files (easy)</li> + <li>Expose POIFS API to read raw OLE2 files from Ruby</li> + <li>Expose HPSF API to read property streams </li> + <li>Tests... Tests... Tests...</li> + </ul> + </section> + <section><title>Limitations</title> + <ul> + <li>Check operations in 64bit machines - Java primitive types are fixed irrespective of machine type, unlike C/C++ types. The wrapping code + that converts C/C++ primitive types to/from Java types is making assumptions on type sizes that MAY be incorrect on wide architectures. </li> + <li>The current implementation is with the POI 2.0 release. The 2.5 release adds support for Excel drawing primitives, and + thus has a dependency on java AWT. Since AWT is not very mature in gcj, leaving it out seemed to be the safer option.</li> + <li>Packaging - The current make file makes no effort to install the extension into the standard ruby directories. This should probably be + packaged as a <a href="https://www.rubygems.org">gem</a>.</li> + </ul> + </section> + + </section> + + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/components/poifs/design.xml b/src/documentation/content/xdocs/components/poifs/design.xml new file mode 100644 index 0000000000..b4ab1d54f9 --- /dev/null +++ b/src/documentation/content/xdocs/components/poifs/design.xml @@ -0,0 +1,1099 @@ +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> + +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - POIFS - Design Document</title> + </header> + <body> + <section> + <title>POIFS Design Document</title> + <p>This document describes the design of the POIFS system. It is organized as follows:</p> + <ul> + <li> + <a href="#Scope">Scope:</a> + A description of the limitations of this document. + </li> + <li> + <a href="#Assumptions">Assumptions:</a> + The assumptions on which this design is based. + </li> + <li> + <a href="#Considerations">Design Considerations:</a> + The constraints and goals applied to the design. + </li> + <li> + <a href="#Design">Design:</a> + The design of the POIFS system. + </li> + </ul> + </section> + <section id="Scope"> + <title>Scope</title> + <p>This document is written as part of an iterative process. As that process is not yet complete, neither is + this document. + </p> + </section> + <section id="Assumptions"> + <title>Assumptions</title> + <p>The design of POIFS is not dependent on the code written for the proof-of-concept prototype POIFS + package. + </p> + </section> + <section id="Considerations"> + <title>Design Considerations</title> + <p>As usual, the primary considerations in the design of the POIFS assumption involve the classic space-time + tradeoff. In this case, the main consideration has to involve minimizing the memory footprint of POIFS. + POIFS may be called upon to create relatively large documents, and in web application server, it may be + called upon to create several documents simultaneously, and it will likely co-exist with other + Serializer systems, competing with those other systems for space on the server. + </p> + <p>We've addressed the risk of being too slow through a proof-of-concept prototype. This prototype for POIFS + involved reading an existing file, decomposing it into its constituent documents, composing a new POIFS + from the constituent documents, and writing the POIFS file back to disk and verifying that the output + file, while not necessarily a byte-for-byte image of the input file, could be read by the application + that generated the input file. This prototype proved to be quite fast, reading, decomposing, and + re-generating a large (300K) file in 2 to 2.5 seconds. + </p> + <p>While the POIFS format allows great flexibility in laying out the documents and the other internal data + structures, the layout of the filesystem will be kept as simple as possible. + </p> + </section> + <section id="Design"> + <title>Design</title> + <p>The design of the POIFS is broken down into two parts: <a href="#Classes">discussion of the classes and + interfaces</a>, and <a href="#Scenarios">discussion of how these classes and interfaces will be used to + convert an appropriate Java InputStream (such as an XML stream) to a POIFS output stream containing an + HSSF document</a>. + </p> + <p> + <strong id="Classes">Classes and Interfaces</strong> + </p> + <p>The classes and interfaces used in the POIFS are broken down as follows:</p> + <table> + <tr> + <th>Package</th> + <th>Contents</th> + </tr> + <tr> + <td> + <a href="#BlockClasses">net.sourceforge.poi.poifs.storage</a> + </td> + <td>Block classes and interfaces</td> + </tr> + <tr> + <td> + <a href="#PropertyClasses">net.sourceforge.poi.poifs.property</a> + </td> + <td>Property classes and interfaces</td> + </tr> + <tr> + <td> + <a href="#FilesystemClasses">net.sourceforge.poi.poifs.filesystem</a> + </td> + <td>Filesystem classes and interfaces</td> + </tr> + <tr> + <td> + <a href="#UtilityClasses">net.sourceforge.poi.util</a> + </td> + <td>Utility classes and interfaces</td> + </tr> + </table> + + <section id="BlockClasses"> + <title>Block Classes and Interfaces</title> + <p>The block classes and interfaces are shownin the following class diagram.</p> + <p> + <img src="images/BlockClassDiagram.gif" alt="Block Classes and Interfaces"/> + </p> + <table> + <tr> + <th>Class/Interface</th> + <th>Description</th> + </tr> + <tr> + <th id="BATBlock">BATBlock</th> + <td>The <strong>BATBlock</strong> class represents a single big block containing 128 + <a href="fileformat.html#BAT">BAT entries</a>.<br/>Its <code>_fields</code> array is used to + read and write the BAT entries into the <code>_data</code> array. + <br/>Its <code>createBATBlocks</code> method is used to create an array of BATBlock + instances from an array of int BAT entries. + <br/> + Its <code>calculateStorageRequirements</code> method calculates the number of BAT blocks + necessary to hold the specified number of BAT entries. + </td> + </tr> + <tr> + <th id="BigBlock">BigBlock</th> + <td>The <strong>BigBlock</strong> class is an abstract class representing the common big block + of 512 bytes. It implements <a href="#BlockWritable">BlockWritable</a>, trivially delegating + the <code>writeBlocks</code> method of BlockWritable to its own abstract <code>writeData + </code> method. + </td> + </tr> + <tr> + <th id="BlockWritable">BlockWritable</th> + <td>The <strong>BlockWritable</strong> interface defines a single method, + <code>writeBlocks</code>, that is used to write an implementation's block data to an <code> + OutputStream</code>. + </td> + </tr> + <tr> + <th id="DocumentBlock">DocumentBlock</th> + <td>The <strong>DocumentBlock</strong> class is used by a <a href="#Document"> + Document + </a> to holds its raw data. It also retains the number of bytes read, as this is used by the + Document class to determine the total size of the data, and is also used internally to + determine whether the block was filled by the + <code>InputStream</code> + or not. + <br/> + The <code>DocumentBlock</code> constructor is passed an <code>InputStream</code> from which + to fill its <code>_data</code> array. + <br/> + The <code>size</code> method returns the number of bytes read (<code>_bytes_read</code>) + when the instance was constructed. + <br/> + The <code>partiallyRead</code> method returns true if the <code>_data</code> array was not + completely filled, which may be interpreted by the Document as having reached the end of + file point.<br/>Typical use of the DocumentBlock class is like this: + <br/> + <source><![CDATA[ +while (true) { + DocumentBlock block = new DocumentBlock(stream); + blocks.add(block); + size += block.size(); + if (block.partiallyRead()) { + break; + } +}]]></source> + </td> + </tr> + <tr> + <th id="HeaderBlock">HeaderBlock</th> + <td>The <strong>HeaderBlock</strong> class is used to contain the data found in a POIFS header. + <br/> + Its <a href="#IntegerField">IntegerField</a> members are used to read and write the + appropriate entries into the + <code>_data</code> + array.<br/>Its + <code>setBATBlocks</code> + , + <code>setPropertyStart</code> + , and + <code>setXBATStart</code> + methods are used to set the appropriate fields in the + <code>_data</code> + array.<br/>The + <code>calculateXBATStorageRequirements</code> + method is used to determine how many XBAT blocks are necessary to accommodate the specified + number of BAT blocks. + </td> + </tr> + <tr> + <th id="PropertyBlock">PropertyBlock</th> + <td>The <strong>PropertyBlock</strong> class is used to contain + <a href="#Property">Property</a> + instances for the + <a href="#PropertyTable">PropertyTable</a> + class.<br/>It contains an array, <code>_properties</code> of 4 Property instances, which + together comprise the 512 bytes of a <a href="#BigBlock">BigBlock</a>. + <br/> + The <code>createPropertyBlockArray</code> method is used to convert a + <code>List</code> + of Property instances into an array of PropertyBlock instances. The number of Property + instances is rounded up to a multiple of 4 by creating empty anonymous inner class + extensions of Property. + </td> + </tr> + </table> + </section> + + <section id="PropertyClasses"> + <title>Property Classes and Interfaces</title> + + <p>The property classes and interfaces are shown in the following class diagram. + </p> + <p> + <img src="images/PropertyTableClassDiagram.gif" alt="Property Classes and Interfaces"/> + </p> + <table> + <tr> + <th>Class/Interface</th> + <th>Description</th> + </tr> + <tr> + <th id="Directory">Directory</th> + <td>The <strong>Directory</strong> interface is implemented by the + <a href="#RootProperty">RootProperty</a> + class. It is not strictly necessary for the initial POIFS implementation, but when the POIFS + supports <a href="fileformat.html#directoryEntry">directory elements</a>, this interface + will be more widely implemented, and so is included in the design at this point to ease the + eventual support of directory elements.<br/>Its methods are a getter/setter pair, + <code>getChildren</code> + , returning an <code>Iterator</code> of + <a href="#Property">Property</a> + instances; and + <code>addChild</code> + , which will allow the caller to add another Property instance to the Directory's children. + </td> + </tr> + <tr> + <th id="DocumentProperty">DocumentProperty</th> + <td>The <strong>DocumentProperty</strong> class is a trivial extension of <a href="#Property"> + Property + </a> and is used by <a href="#Document">Document</a> to keep track of its associated entry in + the + <a href="#PropertyTable">PropertyTable</a>.<br/>Its constructor takes a name and the + document size, on the assumption that the Document will not create a DocumentProperty until + after it has created the storage for the document data and therefore knows how much data + there is. + </td> + </tr> + <tr> + <th id="File">File</th> + <td>The <strong>File</strong> interface specifies the behavior of reading and writing the next + and previous child fields of a <a href="#Property">Property</a>. + </td> + </tr> + <tr> + <th id="Property">Property</th> + <td>The <strong>Property</strong> class is an abstract class that defines the basic data + structure of an element of the <a href="fileformat.html#PropertyTable"> + Property Table</a>.<br/>Its <a href="#ByteField">ByteField</a>, <a href="#ShortField"> + ShortField</a>, and + <a href="#IntegerField">IntegerField</a> + members are used to read and write data into the appropriate locations in the + <code>_raw_data</code> + array.<br/>The + <code>_index</code> + member is used to hold a Propery instance's index in the <code>List</code> of Property + instances maintained by <a href="#PropertyTable">PropertyTable</a>, which is used to + populate the child property of parent + <a href="#Directory">Directory</a> + properties and the next property and previous property of sibling + <a href="#File">File</a> + properties.<br/>The + <code>_name</code> + , + <code>_next_file</code> + , and + <code>_previous_file</code> + members are used to help fill the appropriate fields of the _raw_data array.<br/>Setters are + provided for some of the fields (name, property type, node color, child property, size, + index, start block), as well as a few getters (index, child property).<br/>The + <code>preWrite</code> + method is abstract and is used by the owning PropertyTable to iterate through its Property + instances and prepare each for writing.<br/>The + <code>shouldUseSmallBlocks</code> + method returns true if the Property's size is sufficiently small - how small is none of the + caller's business. + </td> + </tr> + <tr> + <th>PropertyBlock</th> + <td>See the description in <a href="#PropertyBlock">PropertyBlock</a>. + </td> + </tr> + <tr> + <th id="PropertyTable">PropertyTable</th> + <td>The <strong>PropertyTable</strong> class holds all of the + <a href="#DocumentProperty">DocumentProperty</a> + instances and the + <a href="#RootProperty">RootProperty</a> + instance for a + <a href="#Filesystem">Filesystem</a> + instance.<br/>It maintains a + <code>List</code> + of its + <a href="#Property">Property</a> + instances ( + <code>_properties</code> + ), and when prepared to write its data by a call to + <code>preWrite</code> + , it gets and holds an array of + <a href="#PropertyBlock">PropertyBlock</a> + instances ( + <code>_blocks</code>) .<br/>It also maintains its start block in its + <code>_start_block</code> + member.<br/>It has a method, + <code>getRoot</code> + , to get the RootProperty, returning it as an implementation of <a href="#Directory"> + Directory</a>, and a method to add a Property, + <code>addProperty</code> + , and a method to get its start block, + <code>getStartBlock</code> + . + </td> + </tr> + <tr> + <th id="RootProperty">RootProperty</th> + <td>The <strong>RootProperty</strong> class acts as the <a href="#Directory">Directory</a> for + all of the + <a href="#DocumentProperty">DocumentProperty</a> + instance. As such, it is more of a pure <a href="fileformat.html#directoryEntry">directory + entry + </a> than a proper <a href="fileformat.html#RootEntry">root entry + </a> in the <a href="fileformat.html#PropertyTable">Property Table</a>, but the initial + POIFS implementation does not warrant the additional complexity of a full-blown root entry, + and so it is not modeled in this design.<br/>It maintains a + <code>List</code> + of its children, + <code>_children</code> + , in order to perform its directory-oriented duties. + </td> + </tr> + </table> + </section> + + <section id="FilesystemClasses"> + <title>Filesystem Classes and Interfaces</title> + <p>The property classes and interfaces are shown in the following class diagram. + </p> + <p> + <img src="images/POIFSClassDiagram.gif" alt="Filesystem Classes and Interfaces"/> + </p> + <table> + <tr> + <th>Class/Interface</th> + <th>Description</th> + </tr> + <tr> + <th id="Filesystem">Filesystem</th> + <td>The <strong>Filesystem</strong> class is the top-level class that manages the creation of a + POIFS document.<br/>It maintains a + <a href="#PropertyTable">PropertyTable</a> + instance in its + <code>_property_table</code> + member, a + <a href="#HeaderBlock">HeaderBlock</a> + instance in its + <code>_header_block</code> + member, and a <code>List</code> of its + <a href="#Document">Document</a> + instances in its + <code>_documents</code> + member.<br/>It provides methods for a client to create a document ( + <code>createDocument</code> + ), and a method to write the Filesystem to an + <code>OutputStream</code> + ( + <code>writeFilesystem</code> + ). + </td> + </tr> + <tr> + <th>BATBlock</th> + <td>See the description in + <a href="#BATBlock">BATBlock</a> + </td> + </tr> + <tr> + <th id="BATManaged">BATManaged</th> + <td>The <strong>BATManaged</strong> interface defines common behavior for objects whose location + in the written file is managed by the <a href="fileformat.html#BAT">Block Allocation + Table</a>.<br/>It defines methods to get a count of the implementation's + <a href="#BigBlock">BigBlock</a> + instances ( + <code>countBlocks</code> + ), and to set an implementation's start block ( + <code>setStartBlock</code> + ). + </td> + </tr> + <tr> + <th id="BlockAllocationTable">BlockAllocationTable</th> + <td>The <strong>BlockAllocationTable</strong> is an implementation of the + POIFS <a href="fileformat.html#BAT">Block Allocation Table</a>. It is only created when the <a href="#Filesystem"> + Filesystem + </a> is about to be written to an + <code>OutputStream</code>.<br/>It contains an <a href="#IntList">IntList</a> of block + numbers for all of the + <a href="#BATManaged">BATManaged</a> + implementations owned by the Filesystem, + <code>_entries</code> + , which is filled by calls to + <code>allocateSpace</code> + .<br/>It fills its array, + <code>_blocks</code> + , of + <a href="#BATBlock">BATBlock</a> + instances when its + <code>createBATBlocks</code> + method is called. This method has to take into account its own storage requirements, as well + as those of the XBAT blocks, and so calls + <code>BATBlock.calculateStorageRequirements</code> + and + <code>HeaderBlock.calculateXBATStorageRequirements</code> + repeatedly until the counts returned by those methods stabilize.<br/>The + <code>countBlocks</code> + method returns the number of BATBlock instances created by the preceding call to + createBlocks. + </td> + </tr> + <tr> + <th>BlockWritable</th> + <td>See the description in + <a href="#BlockWritable">BlockWritable</a> + </td> + </tr> + <tr> + <th id="Document">Document</th> + <td>The <strong>Document</strong> class is used to contain a document, such as an HSSF workbook. + <br/>It has its own + <a href="#DocumentProperty">DocumentProperty</a> + ( + <code>_property</code> + ) and stores its data in a collection of + <a href="#DocumentBlock">DocumentBlock</a> + instances ( + <code>_blocks</code> + ).<br/>It has a method, + <code>getDocumentProperty</code> + , to get its DocumentProperty. + </td> + </tr> + <tr> + <th>DocumentBlock</th> + <td>See the description in + <a href="#DocumentBlock">DocumentBlock</a> + </td> + </tr> + <tr> + <th>DocumentProperty</th> + <td>See the description in + <a href="#DocumentProperty">DocumentProperty</a> + </td> + </tr> + <tr> + <th>HeaderBlock</th> + <td>See the description in + <a href="#HeaderBlock">HeaderBlock</a> + </td> + </tr> + <tr> + <th>PropertyTable</th> + <td>See the description in + <a href="#PropertyTable">PropertyTable</a> + </td> + </tr> + </table> + </section> + + <section id="UtilityClasses"> + <title>Utility Classes and Interfaces</title> + <p>The utility classes and interfaces are shown in the following class diagram. + </p> + <p> + <img src="images/utilClasses.gif" alt="Utility Classes and Interfaces"/> + </p> + <table> + <tr> + <th>Class/Interface</th> + <th>Description</th> + </tr> + <tr> + <th id="BitField">BitField</th> + <td>The <strong>BitField</strong> class is used primarily by HSSF code to manage bit-mapped + fields of HSSF records. It is not likely to be used in the POIFS code itself and is only + included here for the sake of complete documentation of the POI utility classes. + </td> + </tr> + <tr> + <th id="ByteField">ByteField</th> + <td>The <strong>ByteField</strong> class is an implementation of <a href="#FixedField"> + FixedField + </a> for the purpose of managing reading and writing to a byte-wide field in an array of <code> + bytes</code>. + </td> + </tr> + <tr> + <th id="FixedField">FixedField</th> + <td>The <strong>FixedField</strong> interface defines a set of methods for reading a field from + an array of + <code>bytes</code> + or from an + <code>InputStream</code>, and for writing a field to an array of + <code>bytes</code>. Implementations typically require an offset in their constructors that, + for the purposes of reading and writing to an array of + <code>bytes</code>, makes sure that the correct <code>bytes</code> in the array are read or + written. + </td> + </tr> + <tr> + <th id="HexDump">HexDump</th> + <td>The <strong>HexDump</strong> class is a debugging class that can be used to dump an array of <code> + bytes + </code> to an <code>OutputStream</code>. The static method + <code>dump</code> + takes an array of <code>bytes</code>, a <code>long</code> offset that is used to label the + output, an open + <code>OutputStream</code>, and an + <code>int</code> + index that specifies the starting index within the array of + <code>bytes</code>.<br/>The data is displayed 16 bytes per line, with each byte displayed in + hexadecimal format and again in printable form, if possible (a byte is considered printable + if its value is in the range of 32 ... 126).<br/>Here is an example of a small array of + <code>bytes</code> + with an offset of 0x110: + <br/> + <source><![CDATA[ +00000110 C8 00 00 00 FF 7F 90 01 00 00 00 00 00 00 05 01 ................ +00000120 41 00 72 00 69 00 61 00 6C 00 A.r.i.a.l. + ]]></source> + </td> + </tr> + <tr> + <th id="IntegerField">IntegerField</th> + <td>The <strong>IntegerField</strong> class is an implementation of <a href="#FixedField"> + FixedField + </a> for the purpose of managing reading and writing to an integer-wide field in an array + of <code>bytes</code>. + </td> + </tr> + <tr> + <th id="IntList">IntList</th> + <td>The <strong>IntList</strong> class is a work-around for functionality missing in Java (see + <a href="https://developer.java.sun.com/developer/bugParade/bugs/4487555.html"> + https://developer.java.sun.com/developer/bugParade/bugs/4487555.html + </a> + for details); it is a simple growable array of <code>ints</code> that gets around the + requirement of wrapping and unwrapping <code>ints</code> in + <code>Integer</code> + instances in order to use the + <code>java.util.List</code> + interface. + <br/> + <strong>IntList</strong> + mimics the functionality of the + <code>java.util.List</code> + interface as much as possible. + </td> + </tr> + <tr> + <th id="LittleEndian">LittleEndian</th> + <td>The <strong>LittleEndian</strong> class provides a set of static methods for reading and + writing + <code>shorts</code>, + <code>ints</code>, <code>longs</code>, and <code>doubles</code> in and out of + <code>byte</code> + arrays, and out of + <code>InputStreams</code>, preserving the Intel byte ordering and encoding of these values. + </td> + </tr> + <tr> + <th id="LittleEndianConsts">LittleEndianConsts</th> + <td>The + <strong>LittleEndianConsts</strong> + interface defines the width of a + <code>short</code>, <code>int</code>, + <code>long</code>, and + <code>double</code> + as stored by Intel processors. + </td> + </tr> + <tr> + <th id="LongField">LongField</th> + <td>The <strong>LongField</strong> class is an implementation of <a href="#FixedField"> + FixedField + </a> for the purpose of managing reading and writing to a long-wide field in an array of <code> + bytes</code>. + </td> + </tr> + <tr> + <th id="ShortField">ShortField</th> + <td>The <strong>ShortField</strong> class is an implementation of <a href="#FixedField"> + FixedField + </a> for the purpose of managing reading and writing to a short-wide field in an array of <code> + bytes</code>. + </td> + </tr> + <tr> + <th id="ShortList">ShortList</th> + <td>The <strong>ShortList</strong> class is a work-around for functionality missing in Java (see + <a href="https://developer.java.sun.com/developer/bugParade/bugs/4487555.html"> + https://developer.java.sun.com/developer/bugParade/bugs/4487555.html + </a> + for details); it is a simple growable array of <code>shorts</code> that gets around the + requirement of wrapping and unwrapping <code>shorts</code> in + <code>Short</code> + instances in order to use the + <code>java.util.List</code> + interface. + <br/> + <strong>ShortList</strong> + mimics the functionality of the + <code>java.util.List</code> + interface as much as possible. + </td> + </tr> + <tr> + <th id="StringUtil">StringUtil</th> + <td>The <strong>StringUtil</strong> class manages the processing of Unicode strings. + </td> + </tr> + </table> + </section> + </section> + + <section id="Scenarios"> + <title>Scenarios</title> + <p>This section describes the scenarios of how the POIFS classes and interfaces will be used to convert an + appropriate XML stream to a POIFS output stream containing an HSSF document. + </p> + <p>It is broken down as suggested by the following scenario diagram: + </p> + <p> + <img src="images/POIFSLifeCycle.gif" alt="POIFS LifeCycle"/> + </p> + <table> + <tr> + <th>Step</th> + <th>Description</th> + </tr> + <tr> + <th>1</th> + <td> + <a href="#Initialization">The Filesystem is created by the client application. + </a> + </td> + </tr> + <tr> + <th>2</th> + <td><a href="#CreateDocument">The client application tells the Filesystem to create a document</a>, + providing an + <code>InputStream</code> + and the name of the document. This may be repeated several times. + </td> + </tr> + <tr> + <th>3</th> + <td> + <a href="#Initialization">The client application asks the Filesystem to write its data to + an <code>OutputStream</code>. + </a> + </td> + </tr> + </table> + + <section id="Initialization"> + <title>Initialization</title> + <p>Initialization of the POIFS system is shown in the following scenario diagram: + </p> + <p> + <img src="images/POIFSInitialization.gif" alt="Initialization"/> + </p> + <table> + <tr> + <th>Step</th> + <th>Description</th> + </tr> + <tr> + <th>1</th> + <td>The + <a href="#Filesystem">Filesystem</a> + object, which is created for each request to convert an appropriate XML stream to a POIFS + output stream containing an HSSF document, creates its <a href="#PropertyTable"> + PropertyTable</a>. + </td> + </tr> + <tr> + <th>2</th> + <td>The + <a href="#PropertyTable">PropertyTable</a> + creates its + <a href="#RootProperty">RootProperty</a> + instance, making the RootProperty the first + <a href="#Property">Property</a> + in its <code>List</code> of Property instances. + </td> + </tr> + <tr> + <th>3</th> + <td>The + <a href="#Filesystem">Filesystem</a> + creates its + <a href="#HeaderBlock">HeaderBlock</a> + instance. It should be noted that the decision to create the HeaderBlock at Filesystem + initialization is arbitrary; creation of the HeaderBlock could easily and harmlessly be + postponed to the appropriate moment in + <a href="#WriteFilesystem">writing the filesystem</a>. + </td> + </tr> + </table> + </section> + + <section id="CreateDocument"> + <title>Creating a Document</title> + <p>Creating and adding a document to a POIFS system is shown in the following scenario diagram: + </p> + <p> + <img src="images/POIFSAddDocument.gif" alt="Add Document"/> + </p> + <table> + <tr> + <th>Step</th> + <th>Description</th> + </tr> + <tr> + <th>1</th> + <td>The + <a href="#Filesystem">Filesystem</a> + instance creates a new + <a href="#Document">Document</a> + instance. It will store the newly created Document in a + <code>List</code> + of + <a href="#BATManaged">BATManaged</a> + instances. + </td> + </tr> + <tr> + <th>2</th> + <td>The <a href="#Document">Document</a> reads data from the provided + <code>InputStream</code>, storing the data in + <a href="#DocumentBlock">DocumentBlock</a> + instances. It keeps track of the byte count as it reads the data. + </td> + </tr> + <tr> + <th>3</th> + <td>The <a href="#Document">Document</a> creates a + <a href="#DocumentProperty">DocumentProperty</a> + to keep track of its property data. The byte count is stored in the newly created + DocumentProperty instance. + </td> + </tr> + <tr> + <th>4</th> + <td>The + <a href="#Filesystem">Filesystem</a> + requests the newly created + <a href="#DocumentProperty">DocumentProperty</a> + from the newly created + <a href="#Document">Document</a> + instance. + </td> + </tr> + <tr> + <th>5</th> + <td>The + <a href="#Filesystem">Filesystem</a> + sends the newly created + <a href="#DocumentProperty">DocumentProperty</a> + to the Filesystem's + <a href="#PropertyTable">PropertyTable</a> + so that the PropertyTable can add the DocumentProperty to its + <code>List</code> + of + <a href="#Property">Property</a> + instances. + </td> + </tr> + <tr> + <th>6</th> + <td>The <a href="#Filesystem">Filesystem</a> gets the + <a href="#RootProperty">RootProperty</a> + from its <a href="#PropertyTable">PropertyTable</a>. + </td> + </tr> + <tr> + <th>7</th> + <td>The <a href="#Filesystem">Filesystem</a> adds the newly created + <a href="#DocumentProperty">DocumentProperty</a> + to the <a href="#RootProperty">RootProperty</a>. + </td> + </tr> + </table> + <p>Although typical deployment of the POIFS system will only entail adding a single <a href="#Document"> + Document + </a> (the workbook) to the <a href="#Filesystem">Filesystem</a>, there is nothing in the design to + prevent multiple Documents from being added to the Filesystem. This flexibility can be employed to + write summary information document(s) in addition to the workbook. + </p> + </section> + + <section id="WriteFilesystem"> + <title>Writing the Filesystem</title> + <p>Writing the filesystem is shown in the following scenario diagram: + </p> + <p> + <img src="images/POIFSWriteFilesystem.gif" alt="Writing the Filesystem"/> + </p> + <table> + <tr> + <th>Step</th> + <th colspan="2">Description</th> + </tr> + <tr> + <th>1</th> + <td colspan="2">The <a href="#Filesystem">Filesystem</a> adds the + <a href="#PropertyTable">PropertyTable</a> + to its <code>List</code> of + <a href="#BATManaged">BATManaged</a> + instances and calls the PropertyTable's + <code>preWrite</code> + method. The action taken by the PropertyTable is shown in + the <a href="#PropertyTablePreWrite">PropertyTable preWrite scenario diagram</a>. + </td> + </tr> + <tr> + <th>2</th> + <td colspan="2">The + <a href="#Filesystem">Filesystem</a> + creates the <a href="#BlockAllocationTable">BlockAllocationTable</a>. + </td> + </tr> + <tr> + <th>3</th> + <td>The <a href="#Filesystem">Filesystem</a> gets the block count from the + <a href="#BATManaged">BATManaged</a> + instance. + </td> + <td rowspan="3">These three steps are repeated for each + <a href="#BATManaged">BATManaged</a> + instance in the <a href="#Filesystem">Filesystem</a>'s + <code>List</code> + of BATManaged instances (i.e., the <a href="#Document">Documents</a>, in order of their + addition to the Filesystem, followed by the <a href="#PropertyTable">PropertyTable</a>). + </td> + </tr> + <tr> + <th>4</th> + <td>The + <a href="#Filesystem">Filesystem</a> + sends the block count to the <a href="#BlockAllocationTable"> + BlockAllocationTable</a>, which adds the appropriate entries to is <a href="#IntList"> + IntList + </a> of entries, returning the starting block for the newly added entries. + </td> + </tr> + <tr> + <th>5</th> + <td>The + <a href="#Filesystem">Filesystem</a> + gives the start block number to the + <a href="#BATManaged">BATManaged</a> + instance. If the BATManaged instance is a <a href="#Document">Document</a>, it sets the + start block field in its + <a href="#DocumentProperty">DocumentProperty</a>. + </td> + </tr> + <tr> + <th>6</th> + <td colspan="2">The + <a href="#Filesystem">Filesystem</a> + tells the + <a href="#BlockAllocationTable">BlockAllocationTable</a> + to create its <a href="#BATBlock">BatBlocks</a>. + </td> + </tr> + <tr> + <th>7</th> + <td colspan="2">The + <a href="#Filesystem">Filesystem</a> + gives the BAT information to the <a href="#HeaderBlock">HeaderBlock</a> so that it can set + its BAT fields and, if necessary, create XBAT blocks. + </td> + </tr> + <tr> + <th>8</th> + <td colspan="2">If the filesystem is unusually large (over <strong>7MB</strong>), the + <a href="#HeaderBlock">HeaderBlock</a> + will create XBAT blocks to contain the BAT data that it cannot hold directly. In this case, + the + <a href="#Filesystem">Filesystem</a> + tells the HeaderBlock where those additional blocks will be stored. + </td> + </tr> + <tr> + <th>9</th> + <td colspan="2">The + <a href="#Filesystem">Filesystem</a> + gives the + <a href="#PropertyTable">PropertyTable</a> + start block to the <a href="#HeaderBlock">HeaderBlock</a>. + </td> + </tr> + <tr> + <th>10</th> + <td colspan="2">The + <a href="#Filesystem">Filesystem</a> + tells the + <a href="#BlockWritable">BlockWritable</a> + instance to write its blocks to the provided + <code>OutputStream</code>.<br/>This step is repeated for each BlockWritable instance, in + this order: + <br/> + <ol> + <li> + The <a href="#HeaderBlock">HeaderBlock</a>. + </li> + <li> + Each <a href="#Document">Document</a>, in the order in which it was added to + the <a href="#Filesystem">Filesystem</a>. + </li> + <li> + The <a href="#PropertyTable">PropertyTable</a>. + </li> + <li> + The + <a href="#BlockAllocationTable">BlockAllocationTable</a> + </li> + <li> + The XBAT blocks created by the + <a href="#HeaderBlock">HeaderBlock</a>, if any. + </li> + </ol> + </td> + </tr> + </table> + </section> + + <section id="PropertyTablePreWrite"> + <title>PropertyTable preWrite scenario diagram</title> + <p> + <img src="images/POIFSPropertyTablePreWrite.gif" alt="PropertyTable preWrite scenario diagram"/> + </p> + <table> + <tr> + <th>Step</th> + <th>Description</th> + </tr> + <tr> + <th>1</th> + <td>The + <a href="#PropertyTable">PropertyTable</a> + calls + <code>setIndex</code> + for each of its + <a href="#Property">Property</a> + instances, so that each Property now knows its index within the PropertyTable's <code>List + </code> of Property instances. + </td> + </tr> + <tr> + <th>2</th> + <td>The + <a href="#PropertyTable">PropertyTable</a> + requests the + <a href="#PropertyBlock">PropertyBlock</a> + class to create an array of + <a href="#PropertyBlock">PropertyBlock</a> + instances. + </td> + </tr> + <tr> + <th>3</th> + + <td>The + <a href="#PropertyBlock">PropertyBlock</a> + calculates the number of empty + <a href="#Property">Property</a> + instances it needs to create and creates them. The algorithm for the number to create is: + <br/> + <source><![CDATA[ +block_count = (properties.size() + 3) / 4; +emptyPropertiesNeeded = (block_count * 4) - properties.size();]]></source> + </td> + </tr> + <tr> + <th>4</th> + <td>The + <a href="#PropertyBlock">PropertyBlock</a> + creates the required number of + <a href="#PropertyBlock">PropertyBlock</a> + instances from the + <code>List</code> + of + <a href="#Property">Property</a> + instances, including the newly created empty + <a href="#Property">Property</a> + instances. + </td> + </tr> + <tr> + <th>5</th> + <td>The + <a href="#PropertyTable">PropertyTable</a> + calls + <code>preWrite</code> + on each of its + <a href="#Property">Property</a> + instances. For + <a href="#DocumentProperty">DocumentProperty</a> + instances, this call is a no-op. For the <a href="#RootProperty">RootProperty</a>, the + action taken is shown in the <a href="#RootPropertyPreWrite">RootProperty preWrite scenario + diagram</a>. + </td> + </tr> + </table> + </section> + + <section id="RootPropertyPreWrite"> + <title>RootProperty preWrite scenario diagram</title> + <p> + <img src="images/POIFSRootPropertyPreWrite.gif" alt="RootProperty preWrite scenario diagram"/> + </p> + <table> + <tr> + <th>Step</th> + <th colspan="2">Description</th> + </tr> + <tr> + <th>1</th> + <td colspan="2">The + <a href="#RootProperty">RootProperty</a> + sets its child property with the index of the child <a href="#Property">Property</a> that is + first in its <code>List</code> of children. + </td> + </tr> + <tr> + <th>2</th> + <td>The + <a href="#RootProperty">RootProperty</a> + sets its child's next property field with the index of the child's next sibling in the + RootProperty's + <code>List</code> + of children. If the child is the last in the + <code>List</code>, its next property field is set to <code>-1</code>. + </td> + <td rowspan="2">These two steps are repeated for each <a href="#File">File</a> in + the <a href="#RootProperty"> + RootProperty</a>'s + <code>List</code> + of children. + </td> + </tr> + <tr> + <th>3</th> + <td>The + <a href="#RootProperty">RootProperty</a> + sets its child's previous property field with a value of + <code>-1</code>. + </td> + </tr> + </table> + </section> + </section> + </body> +</document>
\ No newline at end of file diff --git a/src/documentation/content/xdocs/components/poifs/embeded.xml b/src/documentation/content/xdocs/components/poifs/embeded.xml new file mode 100644 index 0000000000..30852e199d --- /dev/null +++ b/src/documentation/content/xdocs/components/poifs/embeded.xml @@ -0,0 +1,95 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> +<document> + <header> + <title>Apache POI™ - POIFS - Documents embedded in other documents</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Nick Burch" email="nick@apache.org"/> + <person name="Yegor Kozlov" email="yegor@apache.org"/> + </authors> + </header> + <body> + <section><title>Overview</title> + <p>It is possible for one OLE 2 based document to have other + OLE 2 documents embedded in it. For example, an Excel file + may have a Word document and a PowerPoint slideshow + embedded as part of it.</p> + <p>Normally, these other documents are stored in subdirectories + of the OLE 2 (POIFS) filesystem. The exact location of the + embedded documents will vary depending on the type of the + master document, and the exact directory names will differ + each time. To figure out exactly which directory to look + in, you will either need to process the appropriate OLE 2 + linking entry in the master document, or simple iterate + over all the directories in the filesystem.</p> + <p>As a general rule, you will find the same OLE 2 entries + in the subdirectories, as you would've found at the root + of the filesystem were a document to not be embedded.</p> + + <section><title>Files embedded in Excel</title> + <p>Excel normally stores embedded files in subdirectories + of the filesystem root. Typically these subdirectories + are named starting with MBD, with 8 hex characters following.</p> + </section> + + <section><title>Files embedded in Word</title> + <p>Word normally stores embedded files in subdirectories + of the ObjectPool directory, itself a subdirectory of the + filesystem root. Typically these subdirectories and named + starting with an underscore, followed by 10 numbers.</p> + </section> + + <section><title>Files embedded in PowerPoint</title> + <p>PowerPoint does not normally store embedded files + in the OLE2 layer. Instead, they are held within records + of the main PowerPoint file. + <br/>See the <a href="./../slideshow/how-to-shapes.html#OLE">HSLF Tutorial</a> + for how to retrieve embedded OLE objects from a presentation</p> + </section> + </section> + + <section><title>Listing POIFS contents</title> + <p>POIFS provides a simple tool for listing the contents of + OLE2 files. This can allow you to see what your POIFS file + contents, and hence if it has any embedded documents in it, + and where.</p> + <p>The tool to use is <em>org.apache.poi.poifs.dev.POIFSLister</em>. + This tool may be run from the command line, and takes a filename + as its parameter. It will print out all the directories and + files contained within the POIFS file.</p> + </section> + + <section><title>Opening embedded files</title> + <p>All of the POIDocument classes (HSSFWorkbook, HSLFSlideShow, + HWPFDocument and HDGFDiagram) can either be opened from + a POIFSFileSystem, or from a specific directory within a + POIFSFileSystem. So, to open embedded files, simply locate the + appropriate DirectoryNode that represents the subdirectory + of interest, and pass this + the overall POIFSFileSystem to + the constructor.</p> + <p>I you want to extract the textual contents of the embedded file, + then open the appropriate POIDocument, and then pass this to + the extractor class, instead of simply passing the POIFSFilesystem + to the extractor.</p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/poifs/fileformat.xml b/src/documentation/content/xdocs/components/poifs/fileformat.xml new file mode 100644 index 0000000000..0452c9adc3 --- /dev/null +++ b/src/documentation/content/xdocs/components/poifs/fileformat.xml @@ -0,0 +1,703 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> +<document> + <header> + <title>POIFS File System Internals</title> + <authors> + <person email="mjohnson@apache.org" name="Marc Johnson" id="MJ"/> + </authors> + </header> + <body> + <section><title>POIFS File System Internals</title> + <section><title>Introduction</title> + <p>POIFS file systems are essentially normal files stored on a + Java-compatible platform's native file system. They are + typically identified by names ending in a four character + extension noting what type of data they contain. For + example, a file ending in ".xls" would likely + contain spreadsheet data, and a file ending in + ".doc" would probably contain a word processing + document. POIFS file systems are called "file + system", because they contain multiple embedded files + in a manner similar to traditional file systems. Along + functional lines, it would be more accurate to call these + POIFS archives. For the remainder of this document it is + referred to as a file system in order to avoid confusion + with the "files" it contains.</p> + <p>POIFS file systems are compatible with those document + formats used by a well-known software company's popular + office productivity suite and programs outputting + compatible data. Because the POIFS file system does not + provide compression, encryption or any other worthwhile + feature, its not a good choice unless you require + interoperability with these programs.</p> + <p>The POIFS file system does not encode the documents + themselves. For example, if you had a word processor file + with the extension ".doc", you would actually + have a POIFS file system with a document file archived + inside of that file system.</p> + <p>Note - this document is a good overview and explanation of + the file format, but for the very nitty-gritty details, + you should refer to + <a href="https://msdn.microsoft.com/en-us/library/dd942138%28v=prot.13%29.aspx">[MS-CFB].pdf</a> + in the (now public) Microsoft Documentation.</p> + </section> + <section><title>Document Conventions</title> + <p>This document utilizes the numeric types as described by + the Java Language Specification, which can be found at + <a href="https://java.sun.com">https://java.sun.com</a>. In + short:</p> + <ul> + <li>A <em>byte</em> is an 8 bit signed integer ranging from + -128 to 127.</li> + <li>A <em>short</em> is a 16 bit signed integer ranging from + -32768 to 32767</li> + <li>An <em>int</em> is a 32 bit signed integer ranging from + -2147483648 to 2147483647</li> + <li>A <em>long</em> is a 64 bit signed integer ranging from + -9.22E18 to 9.22E18.</li> + </ul> + <p>The Java Language Specification spells out a number of + other types that are not referred to by this document.</p> + <p>Where this document makes references to "endian + conversion" it is referring to the byte order of + stored numbers. Numbers in "little-endian order" + are stored with the <em>least</em> significant byte first. In + order to properly read a short, for example, you'd read two + bytes and then shift the second byte 8 bits to the left + before performing an <code>or</code> operation to it + against the first byte. The following code illustrates this + method:</p> + <source> +public int getShort (byte[] rec) +{ + return ((rec[1] << 8) | (rec[0] & 0x00ff)); +}</source> + </section> + <section><title>File System Walkthrough</title> + <p>This is a walkthrough of a POIFS file system and how it is + put together. It is not intended to give a concise + description but to give a "big picture" of the + general structure and how it's interpreted.</p> + <p>A POIFS file system begins with a header. This header + identifies locations in the file by function and provides a + sanity check identifying a file as a POIFS file system.</p> + <p>The first 64 bits of the header compose a <em>magic number + identifier.</em> This identifier tells the client software + that this is indeed a POIFS file system and that it should + be treated as such. This is a "sanity check" to + make sure this is a POIFS file system and not some other + format. The header also contains an <em>array of block + numbers</em>. These block numbers refer to blocks in the + file. When these blocks are read together they form the + <em>Block Allocation Table</em>. The header also contains a + pointer to the first element in the <em>property table</em>, + also known as the <em>root element</em>, and a pointer to the + <em>small Block Allocation Table (SBAT)</em>.</p> + <p>The <em>block allocation table</em> or <em>BAT</em>, along with + the <em>property table</em>, specify which blocks in the file + system belong to which files. After the header block, the + file system is divided into identically sized blocks of + data, numbered from 0 to however many blocks there are in + the file system. For each file in the file system, its + entry in the property table includes the index of the first + block in the array of blocks. Each block's index into the + array of blocks is also its index into the BAT, and the + integer value stored at that index in the BAT gives the + index of the next block in the array (and thus the index of + the next BAT value). A special value is stored in the BAT + to indicate "end of file".</p> + <p>The <em>property table</em> is essentially the directory + storage for the file system. It consists of the name of the + file or directory, its <em>start block</em> in both the file + system and <em>BAT</em>, and its actual size. The first + property in the property table is the <em>root + element</em>. It has two purposes: to be a directory entry + (the root of the directory tree, to be specific), and to + hold the start block for the <em>small block data</em>.</p> + <p>Small block data is a special file that contains the data + for small files (less than 4K bytes). It subdivides its + blocks into smaller blocks and there is a special small + block allocation table that, like the main BAT for larger + files, is used to map a small file to its small blocks.</p> + </section> + <section><title>Header Block</title> + <p>The POIFS file system begins with a <em>header + block</em>. The first 64 bits of the header form a long + <em>file type id</em> or <em>magic number identifier</em> of + <code>0xE11AB1A1E011CFD0L</code>. This is basically a + sanity check. If this isn't the first thing in the header + (and consequently the file system) then this is not a + POIFS file system and should be read with some other + library.</p> + <p>It's important to know the most important parts of the + header. These are discussed in the rest of this + section.</p> + <section><title>BATs</title> + <p>At offset <em>0x2C</em> is an int specifying the number + of elements in the <em>BAT array</em>. The array at + <em>0x4C</em> an array of ints. This array contains the + indices of every block in the Block Allocation + Table.</p> + </section> + <section><title>XBATs</title> + <p>Very large POIFS archives may have more blocks than can + be addressed by the BAT blocks enumerated in the header + block. How large? Well, the BAT array in the header can + contain up to 109 BAT block indices; each BAT block + references up to 128 blocks, and each block is 512 + bytes, so we're talking about 109 * 128 * 512 = + 6.8MB. That's a pretty respectable document! But, you + could have much more data than that, and in today's + world of cheap gigabyte drives, why not? So, the BAT + may be extended in that event. The integer value at + offset <em>0x44</em> of the header is the index of the + first <em>extended BAT (XBAT) block</em>. At offset + <em>0x48</em> of the header, there is an int value that + specifies how many XBAT blocks there are. The XBAT + blocks begin at the specified index into the array of + blocks making up the POIFS file system, and are chained + for the specified count of XBAT blocks.</p> + <p>Each XBAT block contains the indices of up to 127 BAT + blocks, so the document size can be expanded by another + ~8MB for each XBAT block. The BAT blocks indexed by an + XBAT block are appended to the end of the list of BAT + blocks enumerated in the header block. Thus the BAT + blocks enumerated in the header block are BAT blocks 0 + through 108, the BAT blocks enumerated in the first + XBAT block are BAT blocks 109 through 235, the BAT + blocks enumerated in the second XBAT block are BAT + blocks 236 through 362, and so on.</p> + <p>While a normal BAT block holds 128 entries, each XBAT + only references 127 BAT blocks. The last, 128th entry + in an XBAT is the offset to the next XBAT block in the + chain (or -1 if this is the last XBAT).</p> + <p>Through the use of XBAT blocks, the limit on the + overall document size is that imposed by the 4-byte + block indices; if the indices are unsigned ints, the + maximum file size is 2 terabytes, 1 terabyte if the + indices are treated as signed ints. Either way, I have + yet to see a disk drive large enough to accommodate + such a file on the shelves at the local office supply + stores.</p> + </section> + <section><title>SBATs</title> + <p>If a file contained in a POIFS archive is smaller than + 4096 bytes, it is stored in small blocks. Small blocks + are 64 bytes in length and are contained within big + blocks, up to 8 to a big block. As the main BAT is used + to navigate the array of big blocks, so the <em>small + block allocation table</em> is used to navigate the + array of small blocks. The SBAT's start block index is + found at offset <em>0x3C</em> of the header block, and + remaining blocks constituting the SBAT are found by + walking the main BAT as if it were an ordinary file in + the POIFS file system (this process is described + below).</p> + </section> + <section><title>Property Table Start Index</title> + <p>An integer at address <em>0x30</em> specifies the start + index of the property table. This integer is specified + as a <em>"block index"</em>. The Property Table + is stored, as is almost everything in a POIFS file + system, in big blocks and walked via the BAT. The + Property Table is described below.</p> + </section> + </section> + <section><title>Property Table</title> + <p>The property table is essentially nothing more than the + directory system. Properties are 128 byte records + contained within the 512 byte blocks. The first property + is always the Root Entry. The following applies to + individual properties within a property table:</p> + <ul> + <li>At offset <em>0x00</em> in the property is the + "<em>name</em>". This is stored as an + uncompressed 16 bit unicode string. In short every + other byte corresponds to an "ASCII" + character. The size of this string is stored at offset + <em>0x40</em> (<em>string size</em>) as a short.</li> + <li>At offset <em>0x42</em> is the <em>property type</em> + (byte). The type is 1 for directory, 2 for file or 5 + for the Root Entry.</li> + <li>At offset <em>0x43</em> is the <em>node color</em> + (byte). The color is either 1, (black), or 0, + (red). Properties are apparently meant to be arranged + in a red-black binary tree, subject to the following + rules: + <ol> + <li>The root of the tree is always black</li> + <li>Two consecutive nodes cannot both be red</li> + <li>A property is less than another property if its + name length is less than the other property's name + length</li> + <li>If two properties have the same name length, the + sort order is determined by the sort order of the + properties' names.</li> + </ol></li> + <li>At offset <em>0x44</em> is the index (int) of the + <em>previous property</em>.</li> + <li>At offset <em>0x48</em> is the index (int) of the + <em>next property</em>.</li> + <li>At offset <em>0x4C</em> is the index (int) of the + <em>first directory entry</em>. This is used by + directory entries.</li> + <li>At offset <em>0x74</em> is an integer giving the + <em>start block</em> for the file described by this + property. This index corresponds to an index in the + array of indices that is the Block Allocation Table + (or the Small Block Allocation Table) as well as the + index of the first block in the file. This is used by + files and the root entry.</li> + <li>At offset <em>0x78</em> is an integer giving the total + <em>actual size</em> of the file pointed at by this + property. If the file size is less than 4096, the file + is stored in small blocks and the SBAT is used to walk + the small blocks making up the file. If the file size + is 4096 or larger, the file is stored in big blocks + and the main BAT is used to walk the big blocks making + up the file. The exception to this rule is the <em>Root + Entry</em>, which, regardless of its size, is + <em>always</em> stored in big blocks and the main BAT is + used to walk the big blocks making up this special + file.</li> + </ul> + </section> + <section><title>Root Entry</title> + <p>The <em>Root Entry</em> in the <em>Property Table</em> + contains the information necessary to read and write + small files, which are files less than 4096 bytes + long. The start block field of the Root Entry is the + start index of the <em>Small Block Array</em>, which is + read like any other file in the POIFS file system. Since + the SBAT cannot be used without the Small Block Array, + the Root Entry MUST be read or written using the <em>Block + Allocation Table</em>. The blocks making up the Small + Block Array are divided into 64-byte small blocks, up to + the size indicated in the Root Entry (which should always + be a multiple of 64).</p> + </section> + <section><title>Walking the Nodes of the Property Table</title> + <p>The individual properties form a directory tree, with the + <em>Root Entry</em> as the directory tree's root, as shown + in the accompanying drawing. Note the numbers in + parentheses in each node; they represent the node's index + in the array of properties. The <em>NEXT_PROP</em>, + <em>PREVIOUS_PROP</em>, and <em>CHILD_PROP</em> fields hold + these indices, and are used to navigate the tree.</p> + <p><img alt="property set" src="images/PropertySet.jpg" /></p> + <p>Each directory entry (i.e., a property whose type is + <em>directory</em> or <em>root entry</em>) uses its + <em>CHILD_PROP</em> field to point to one of its + subordinate (child) properties. It doesn't seem to matter + which of its children it points to. Thus in the previous + drawing, the Root Entry's CHILD_PROP field may contain 1, + 4, or the index of one of its other children. Similarly, + the directory node (index 1) may have, in its CHILD_PROP + field, 2, 3, or the index of one of its other + children.</p> + <p>The children of a given directory property point to each + other in a similar fashion by using their + <em>NEXT_PROP</em> and <em>PREVIOUS_PROP</em> fields.</p> + <p>Unused <em>NEXT_PROP</em>, <em>PREVIOUS_PROP</em>, and + <em>CHILD_PROP</em> fields contain the marker value of + -1. All file properties have a value of -1 for their + CHILD_PROP fields for example.</p> + </section> + <section><title>Block Allocation Table</title> + <p>The <em>BAT blocks</em> are pointed at by the bat array + contained in the header and supplemented, if necessary, + by the <em>XBAT blocks</em>. These blocks form a large + table of integers. These integers are block numbers. The + <em>Block Allocation Table</em> holds chains of integers. + These chains are terminated with -2. The elements in + these chains refer to blocks in the files. The starting + block of a file is NOT specified in the BAT. It is + specified by the <em>property</em> for a given file. The + elements in this BAT are both the block number (within + the file minus the header) <em>and</em> the number of the + next BAT element in the chain. This can be thought of as + a linked list of blocks. The BAT array contains the links + from one block to the next, including the end of chain + marker.</p> + <p>Here's an example: Let's assume that the BAT begins as + follows:</p> + <p><code>BAT[ 0 ] = 2</code></p> + <p><code>BAT[ 1 ] = 5</code></p> + <p><code>BAT[ 2 ] = 3</code></p> + <p><code>BAT[ 3 ] = 4</code></p> + <p><code>BAT[ 4 ] = 6</code></p> + <p><code>BAT[ 5 ] = -2</code></p> + <p><code>BAT[ 6 ] = 7</code></p> + <p><code>BAT[ 7 ] = -2</code></p> + <p><code>...</code></p> + <p>Now, if we have a file whose Property Table entry says it + begins with index 0, we walk the BAT array and see that + the file consists of blocks 0 (because the start block is + 0), 2 (because BAT[ 0 ] is 2), 3 (BAT[ 2 ] is 3), 4 (BAT[ + 3 ] is 4), 6 (BAT[ 4 ] is 6), and 7 (BAT[ 6 ] is 7). It + ends at block 7 because BAT[ 7 ] is -2, which is the end + of chain marker.</p> + <p>Similarly, a file beginning at index 1 consists of + blocks 1 and 5.</p> + <p>Other special numbers in a BAT array are:</p> + <ul> + <li>-1, which indicates an unused block</li> + <li>-3, which indicates a "special" block, such + as a block used to make up the Small Block Array, the + Property Table, the main BAT, or the SBAT</li> + </ul> + </section> + <section><title>File System Structures</title> + <p>The following outlines the basic file system structures.</p> + <section><title>Header (block 1) -- 512 (0x200) bytes</title> + <table> + <tr> + <td><em>Field</em></td> + <td><em>Description</em></td> + <td><em>Offset</em></td> + <td><em>Length</em></td> + <td><em>Default value or const</em></td> + </tr> + <tr> + <td>FILETYPE</td> + <td>Magic number identifying this as a POIFS file + system.</td> + <td>0x0000</td> + <td>Long</td> + <td>0xE11AB1A1E011CFD0</td> + </tr> + <tr> + <td>UK1</td> + <td>Unknown constant</td> + <td>0x0008</td> + <td>Integer</td> + <td>0</td> + </tr> + <tr> + <td>UK2</td> + <td>Unknown Constant</td> + <td>0x000C</td> + <td>Integer</td> + <td>0</td> + </tr> + <tr> + <td>UK3</td> + <td>Unknown Constant</td> + <td>0x0014</td> + <td>Integer</td> + <td>0</td> + </tr> + <tr> + <td>UK4</td> + <td>Unknown Constant (revision?)</td> + <td>0x0018</td> + <td>Short</td> + <td>0x003B</td> + </tr> + <tr> + <td>UK5</td> + <td>Unknown Constant (version?)</td> + <td>0x001A</td> + <td>Short</td> + <td>0x0003</td> + </tr> + <tr> + <td>UK6</td> + <td>Unknown Constant</td> + <td>0x001C</td> + <td>Short</td> + <td>-2</td> + </tr> + <tr> + <td>LOG_2_BIG_BLOCK_SIZE</td> + <td>Log, base 2, of the big block size</td> + <td>0x001E</td> + <td>Short</td> + <td>9 (2 ^ 9 = 512 bytes)</td> + </tr> + <tr> + <td>LOG_2_SMALL_BLOCK_SIZE</td> + <td>Log, base 2, of the small block size</td> + <td>0x0020</td> + <td>Integer</td> + <td>6 (2 ^ 6 = 64 bytes)</td> + </tr> + <tr> + <td>UK7</td> + <td>Unknown Constant</td> + <td>0x0024</td> + <td>Integer</td> + <td>0</td> + </tr> + <tr> + <td>UK8</td> + <td>Unknown Constant</td> + <td>0x0028</td> + <td>Integer</td> + <td>0</td> + </tr> + <tr> + <td>BAT_COUNT</td> + <td>Number of elements in the BAT array</td> + <td>0x002C</td> + <td>Integer</td> + <td>required</td> + </tr> + <tr> + <td>PROPERTIES_START</td> + <td>Block index of the first block of the property + table</td> + <td>0x0030</td> + <td>Integer</td> + <td>required</td> + </tr> + <tr> + <td>UK9</td> + <td>Unknown Constant</td> + <td>0x0034</td> + <td>Integer</td> + <td>0</td> + </tr> + <tr> + <td>UK10</td> + <td>Unknown Constant</td> + <td>0x0038</td> + <td>Integer</td> + <td>0x00001000</td> + </tr> + <tr> + <td>SBAT_START</td> + <td>Block index of first big block containing the small + block allocation table (SBAT)</td> + <td>0x003C</td> + <td>Integer</td> + <td>-2</td> + </tr> + <tr> + <td>SBAT_Block_Count</td> + <td>Number of big blocks holding the SBAT</td> + <td>0x0040</td> + <td>Integer</td> + <td>1</td> + </tr> + <tr> + <td>XBAT_START</td> + <td>Block index of the first block in the Extended Block + Allocation Table (XBAT)</td> + <td>0x0044</td> + <td>Integer</td> + <td>-2</td> + </tr> + <tr> + <td>XBAT_COUNT</td> + <td>Number of elements in the Extended Block Allocation + Table (to be added to the BAT)</td> + <td>0x0048</td> + <td>Integer</td> + <td>0</td> + </tr> + <tr> + <td>BAT_ARRAY</td> + <td>Array of block indices constituting the Block + Allocation Table (BAT)</td> + <td>0x004C, 0x0050, 0x0054 ... 0x01FC</td> + <td>Integer[]</td> + <td>-1 for unused elements, at least first element must + be filled.</td> + </tr> + <tr> + <td>N/A</td> + <td>Header block data not otherwise described in this + table</td> + <td>N/A</td> + <td>N/A</td> + <td>-1</td> + </tr> + </table> + </section> + <section> + <title>Block Allocation Table Block -- 512 (0x200) bytes</title> + <table> + <tr> + <td> + <em>Field</em> + </td> + <td> + <em>Description</em> + </td> + <td> + <em>Offset</em> + </td> + <td> + <em>Length</em> + </td> + <td> + <em>Default value or const</em> + </td> + </tr> + <tr> + <td>BAT_ELEMENT</td> + <td>Any given element in the BAT block</td> + <td>0x0000, 0x0004, 0x0008, ... 0x01FC</td> + <td>Integer</td> + <td> + -1 = unused<br/> + -2 = end of chain<br/> + -3 = special (e.g., BAT block)<br/> + All other values point to the next element in the + chain and the next index of a block composing the + file. + </td> + </tr> + </table> + </section> + <section><title>Property Block -- 512 (0x200) byte block</title> + <table> + <tr> + <td><em>Field</em></td> + <td><em>Description</em></td> + <td><em>Offset</em></td> + <td><em>Length</em></td> + <td><em>Default value or const</em></td> + </tr> + <tr> + <td>Properties[]</td> + <td>This block contains the properties.</td> + <td>0x0000, 0x0080, 0x0100, 0x0180</td> + <td>128 bytes</td> + <td>All unused space is set to -1.</td> + </tr> + </table> + </section> + <section><title>Property -- 128 (0x80) byte block</title> + <table> + <tr> + <td><em>Field</em></td> + <td><em>Description</em></td> + <td><em>Offset</em></td> + <td><em>Length</em></td> + <td><em>Default value or const</em></td> + </tr> + <tr> + <td>NAME</td> + <td>A unicode null-terminated uncompressed 16bit string + (lose the high bytes) containing the name of the + property.</td> + <td>0x00, 0x02, 0x04, ... 0x3E</td> + <td>Short[]</td> + <td>0x0000 for unused elements, field required, 32 + (0x40) element max</td> + </tr> + <tr> + <td>NAME_SIZE</td> + <td>Number of characters in the NAME field</td> + <td>0x40</td> + <td>Short</td> + <td>Required</td> + </tr> + <tr> + <td>PROPERTY_TYPE</td> + <td>Property type (directory, file, or root)</td> + <td>0x42</td> + <td>Byte</td> + <td>1 (directory), 2 (file), or 5 (root entry)</td> + </tr> + <tr> + <td>NODE_COLOR</td> + <td>Node color</td> + <td>0x43</td> + <td>Byte</td> + <td>0 (red) or 1 (black)</td> + </tr> + <tr> + <td>PREVIOUS_PROP</td> + <td>Previous property index</td> + <td>0x44</td> + <td>Integer</td> + <td>-1</td> + </tr> + <tr> + <td>NEXT_PROP</td> + <td>Next property index</td> + <td>0x48</td> + <td>Integer</td> + <td>-1</td> + </tr> + <tr> + <td>CHILD_PROP</td> + <td>First child property index</td> + <td>0x4c</td> + <td>Integer</td> + <td>-1</td> + </tr> + <tr> + <td>SECONDS_1</td> + <td>Seconds component of the created timestamp?</td> + <td>0x64</td> + <td>Integer</td> + <td>0</td> + </tr> + <tr> + <td>DAYS_1</td> + <td>Days component of the created timestamp?</td> + <td>0x68</td> + <td>Integer</td> + <td>0</td> + </tr> + <tr> + <td>SECONDS_2</td> + <td>Seconds component of the modified timestamp?</td> + <td>0x6C</td> + <td>Integer</td> + <td>0</td> + </tr> + <tr> + <td>DAYS_2</td> + <td>Days component of the modified timestamp?</td> + <td>0x70</td> + <td>Integer</td> + <td>0</td> + </tr> + <tr> + <td>START_BLOCK</td> + <td>Starting block of the file, used as the first block + in the file and the pointer to the next block from + the BAT</td> + <td>0x74</td> + <td>Integer</td> + <td>Required</td> + </tr> + <tr> + <td>SIZE</td> + <td>Actual size of the file this property points + to. (used to truncate the blocks to the real + size).</td> + <td>0x78</td> + <td>Integer</td> + <td>0</td> + </tr> + </table> + </section> + </section> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/poifs/how-to.xml b/src/documentation/content/xdocs/components/poifs/how-to.xml new file mode 100644 index 0000000000..234838608e --- /dev/null +++ b/src/documentation/content/xdocs/components/poifs/how-to.xml @@ -0,0 +1,649 @@ +<?xml version="1.0" encoding="UTF-8"?><!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> +<document> + <header> + <title>How To Use the POIFS APIs</title> + <authors> + <person email="mjohnson@apache.org" name="Marc Johnson" id="MJ"/> + </authors> + </header> + <body> + <section> + <title>How To Use the POIFS APIs</title> + <p>This document describes how to use the POIFS APIs to read, write, and modify files that employ a + POIFS-compatible data structure to organize their content. + </p> + <section> + <title>Target Audience</title> + <p>This document is intended for Java developers who need to use the POIFS APIs to read, write, or + modify files that employ a POIFS-compatible data structure to organize their content. It is not + necessary for developers to understand the POIFS data structures, and an explanation of those data + structures is beyond the scope of this document. It is expected that the members of the target + audience will understand the rudiments of a hierarchical file system, and familiarity with the event + pattern employed by Java APIs such as AWT would be helpful. + </p> + </section> + <section> + <title>Glossary</title> + <p>This document attempts to be consistent in its terminology, which is defined here:</p> + <dl> + <dt>Directory</dt> + <dd>A special file that may contain other directories and documents.</dd> + <dt>DirectoryEntry</dt> + <dd>Representation of a directory within another directory.</dd> + <dt>Document</dt> + <dd>A file containing data, such as word processing data or a spreadsheet workbook.</dd> + <dt>DocumentEntry</dt> + <dd>Representation of a document within a directory.</dd> + <dt>Entry</dt> + <dd>Representation of a file in a directory.</dd> + <dt>File</dt> + <dd>A named entity, managed and contained by the file system.</dd> + <dt>File System</dt> + <dd>The POIFS data structures, plus the contained directories and documents, which are maintained in + a hierarchical directory structure. + </dd> + <dt>Root Directory</dt> + <dd>The directory at the base of a file system. All file systems have a root directory. The POIFS + APIs will not allow the root directory to be removed or renamed, but it can be accessed for the + purpose of reading its contents or adding files (directories and documents) to it. + </dd> + </dl> + </section> + </section> + + <section> + <title>The different ways of working with POIFS</title> + <p>The POIFS API provides ways to read, modify and write files and streams that employ a POIFS-compatible + data structure to organize their content. The following use cases are covered: + </p> + <ul> + <li> + <a href="#reading">Reading a File System</a> + </li> + <li> + <a href="#reading_poifsfilesystem">Conventional Reading with POIFSFileSystem</a> + </li> + <li> + <a href="#reading_event">Event-Driven Reading</a> + </li> + <li> + <a href="#writing">Writing a File System</a> + </li> + <li> + <a href="#modifying">Modifying a File System</a> + </li> + </ul> + </section> + + <section> + <title>Reading a File System</title> + <anchor id="reading"/> + <p>This section covers reading a file system. There are two ways to read a file system; these techniques are + sketched out in the following table, and then explained in greater depth in the sections following the + table. + </p> + <dl> + <dt>Conventional Reading with POIFSFileSystem</dt> + <dd> + <ul> + <li class="pro">Simpler API similar to reading a conventional file system.</li> + <li class="pro">Can read documents in any order.</li> + <li class="pro">Well tested read and write support.</li> + <li class="con">If created from an InputStream, all files are resident in memory. (If created + from a File, only certain key structures are) + </li> + </ul> + </dd> + <dt>Event-Driven Reading</dt> + <dd> + <ul> + <li class="pro">Reduced footprint -- only the documents you care about are processed.</li> + <li class="pro">Improved performance -- no time is wasted reading the documents you're not + interested in. + </li> + <li class="con">More complicated API.</li> + <li class="con">Need to know in advance which documents you want to read.</li> + <li class="con">No control over the order in which the documents are read.</li> + <li class="con">No way to go back and get additional documents except to re-read the file + system, which may not be possible, e.g., if the file system is being read from an input + stream that lacks random access support. + </li> + </ul> + </dd> + </dl> + + <section> + <title>Conventional Reading with POIFSFileSystem</title> + <anchor id="reading_poifsfilesystem"/> + <p>In this technique for reading, certain key structures are loaded into memory, and the entire + directory tree can be walked by the application, reading specific documents at leisure. + </p> + <p>If you create a POIFSFileSystem instance from a File, the memory footprint is very small. However, if + you createa a POIFSFileSystem instance from an input stream, then the whole contents must be + buffered into memory to allow random access. As such, you should budget on memory use of up to 20% + of the file size when using a File, or up to 120% of the file size when using an InputStream. + </p> + + <section> + <title>Preparation</title> + <p>Before an application can read a file from the file system, the file system needs to be opened + and core parts processed. This is done using the + <code>org.apache.poi.poifs.filesystem.POIFSFileSystem</code> + class. Once the file system has been loaded into memory, the application may need the root + directory. The following code fragment will accomplish this preparation stage: + </p> + <source><![CDATA[ + // This is the most memory efficient way to open the FileSystem + try (POIFSFileSystem fs = new POIFSFileSystem(new File(filename))) { + DirectoryEntry root = fs.getRoot(); + } catch (IOException e) { + // an I/O error occurred, or the File did not provide a compatible + // POIFS data structure + } + + // Using an InputStream requires more memory than using a File + try (POIFSFileSystem fs = new POIFSFileSystem(inputStream)) { + DirectoryEntry root = fs.getRoot(); + } catch (IOException e) { + // an I/O error occurred, or the InputStream did not provide + // a compatible POIFS data structure + } + ]]></source> + <p>Assuming no exception was thrown, the file system can then be read.</p> + </section> + <section> + <title>Reading the Directory Tree</title> + <p>Once the file system has been loaded into memory and the root directory has been obtained, the + root directory can be read. The following code fragment shows how to read the entries in an <code> + org.apache.poi.poifs.filesystem.DirectoryEntry + </code> instance: + </p> + <source><![CDATA[ + // dir is an instance of DirectoryEntry ... + for (Entry entry : dir) { + System.out.println("found entry: " + entry.getName()); + if (entry instanceof DirectoryEntry) { + // .. recurse into this directory + } else if (entry instanceof DocumentEntry) { + // entry is a document, which you can read + } else { + // currently, either an Entry is a DirectoryEntry or a DocumentEntry, + // but in the future, there may be other entry subinterfaces. + // The internal data structure certainly allows for a lot more entry types. + } + } + ]]></source> + </section> + <section> + <title>Reading a Specific Document</title> + <p>There are a couple of ways to read a document, depending on whether the document resides in the + root directory or in another directory. Either way, you will obtain an <code> + org.apache.poi.poifs.filesystem.DocumentInputStream + </code> instance. + </p> + <section> + <title>DocumentInputStream</title> + <p>The DocumentInputStream class is a simple implementation of InputStream that makes a few + guarantees worth noting: + </p> + <ul> + <li> + <code>available()</code> + always returns the number of bytes in the document from your current position in the + document. + </li> + <li> + <code>markSupported()</code> + returns <code>true</code>. + </li> + <li> + <code>mark(int limit)</code> + ignores the limit parameter; basically the method marks the current position in the + document. + </li> + <li> + <code>reset()</code> + takes you back to the position when <code>mark()</code> was last called, or to the + beginning of the document if <code>mark()</code> has not been called. + </li> + <li> + <code>skip(long n)</code> + will take you to your current position + n (but not past the end of the document). + </li> + </ul> + <p>The behavior of <code>available</code> means you can read in a document in a single read call + like this: + </p> + <source><![CDATA[ + byte[] content = new byte[ stream.available() ]; + stream.read(content); + stream.close(); + ]]></source> + <p>The combination of <code>mark</code>, <code>reset</code>, and <code>skip</code> provide the + basic mechanisms needed for random access of the document contents. + </p> + </section> + <section> + <title>Reading a Document From the Root Directory</title> + <p>If the document resides in the root directory, you can obtain a <code>DocumentInputStream + </code> like this: + </p> + <source><![CDATA[ + // load file system + try (DocumentInputStream stream = filesystem.createDocumentInputStream(documentName)) { + // process data from stream + } catch (IOException e) { + // no such document, or the Entry represented by documentName is not a DocumentEntry + } + ]]></source> + </section> + <section> + <title>Reading a Document From an Arbitrary Directory</title> + <p>A more generic technique for reading a document is to obtain an <code> + org.apache.poi.poifs.filesystem.DirectoryEntry + </code> instance for the directory containing the desired document (recall that you can use <code> + getRoot() + </code> to obtain the root directory from its file system). From that DirectoryEntry, you can + then obtain a <code>DocumentInputStream</code> like this: + </p> + <source><![CDATA[ + DocumentEntry document = (DocumentEntry)directory.getEntry(documentName); + DocumentInputStream stream = new DocumentInputStream(document); + ]]></source> + </section> + </section> + </section> + + <section> + <title>Event-Driven Reading</title> + <anchor id="reading_event"/> + <p>The event-driven API for reading documents is a little more complicated and requires that your + application know, in advance, which files it wants to read. The benefit of using this API is that + each document is in memory just long enough for your application to read it, and documents that you + never read at all are not in memory at all. When you're finished reading the documents you wanted, + the file system has no data structures associated with it at all and can be discarded. + </p> + <section> + <title>Preparation</title> + <p>The preparation phase involves creating an instance of <code> + org.apache.poi.poifs.eventfilesystem.POIFSReader + </code> and to then register one or more <code> + org.apache.poi.poifs.eventfilesystem.POIFSReaderListener + </code> instances with the <code>POIFSReader</code>. + </p> + <source><![CDATA[ + POIFSReader reader = new POIFSReader(); + // register for everything + reader.registerListener(myOmnivorousListener); + // register for selective files + reader.registerListener(myPickyListener, "foo"); + reader.registerListener(myPickyListener, "bar"); + // register for selective files + reader.registerListener(myOtherPickyListener, new POIFSDocumentPath(), "fubar"); + reader.registerListener(myOtherPickyListener, new POIFSDocumentPath( new String[] { "usr", "bin" ), "fubar"); + ]]></source> + </section> + <section> + <title>POIFSReaderListener</title> + <p> + <code>org.apache.poi.poifs.eventfilesystem.POIFSReaderListener</code> + is an interface used to register for documents. When a matching document is read by the <code> + org.apache.poi.poifs.eventfilesystem.POIFSReader</code>, the <code>POIFSReaderListener</code> instance + receives an <code>org.apache.poi.poifs.eventfilesystem.POIFSReaderEvent</code> instance, which + contains an open <code>DocumentInputStream</code> and information about the document. + </p> + <p>A <code>POIFSReaderListener</code> instance can register for individual documents, or it can + register for all documents; once it has registered for all documents, subsequent (and previous!) + registration requests for individual documents are ignored. There is no way to unregister + a <code>POIFSReaderListener</code>. + </p> + <p>Thus, it is possible to register a single <code>POIFSReaderListener</code> for multiple documents + - one, some, or all documents. It is guaranteed that a single <code>POIFSReaderListener</code> will + receive exactly one notification per registered document. There is no guarantee as to the order + in which it will receive notification of its documents, as future implementations of <code> + POIFSReader + </code> are free to change the algorithm for walking the file system's directory structure. + </p> + <p>It is also permitted to register more than one <code>POIFSReaderListener</code> for the same + document. There is no guarantee of ordering for notification of <code>POIFSReaderListener</code> instances + that have registered for the same document when <code>POIFSReader</code> processes that + document. + </p> + <p>It is guaranteed that all notifications occur in the same thread. A future enhancement may be + made to provide multi-threaded notifications, but such an enhancement would very probably be + made in a new reader class, a <code>ThreadedPOIFSReader</code> perhaps. + </p> + <p>The following describes the three ways to register a <code>POIFSReaderListener</code> for a + document or set of documents: + </p> + <dl> + <dt>registers <em>listener</em> for all documents. + </dt> + <dd>registerListener(POIFSReaderListener <em>listener</em>) + </dd> + <dt>registers <em>listener</em> for a document with the specified <em>name</em> in the root + directory. + </dt> + <dd>registerListener(POIFSReaderListener <em>listener</em>, String <em>name</em>) + </dd> + <dt>registers <em>listener</em> for a document with the specified <em>name</em> in the directory + described by + <em>path</em> + </dt> + <dd>registerListener(POIFSReaderListener <em>listener</em>, POIFSDocumentPath <em>path</em>, + String <em>name</em>) + </dd> + </dl> + </section> + <section> + <title>POIFSDocumentPath</title> + <p>The <code>org.apache.poi.poifs.filesystem.POIFSDocumentPath</code> class is used to describe a + directory in a POIFS file system. Since there are no reserved characters in the name of a file + in a POIFS file system, a more traditional string-based solution for describing a directory, + with special characters delimiting the components of the directory name, is not feasible. The + constructors for the class are used as follows: + </p> + <table> + <tr> + <td> + <em>Constructor example</em> + </td> + <td> + <em>Directory described</em> + </td> + </tr> + <tr> + <td>new POIFSDocumentPath()</td> + <td>The root directory.</td> + </tr> + <tr> + <td>new POIFSDocumentPath(null)</td> + <td>The root directory.</td> + </tr> + <tr> + <td>new POIFSDocumentPath(new String[ 0 ])</td> + <td>The root directory.</td> + </tr> + <tr> + <td>new POIFSDocumentPath(new String[ ] { "foo", "bar"} )</td> + <td>in Unix terminology, "/foo/bar".</td> + </tr> + <tr> + <td>new POIFSDocumentPath(new POIFSDocumentPath(new String[] { "foo" }), new String[ ] { + "fu", "bar"} ) + </td> + <td>in Unix terminology, "/foo/fu/bar".</td> + </tr> + </table> + </section> + <section> + <title>Processing POIFSReaderEvent Events</title> + <p>Processing <code>org.apache.poi.poifs.eventfilesystem.POIFSReaderEvent</code> events is + relatively easy. After all of the <code>POIFSReaderListener</code> instances have been + registered with <code>POIFSReader</code>, the <code>POIFSReader.read(InputStream stream)</code> method + is called. + </p> + <p>Assuming that there are no problems with the data, as the <code>POIFSReader</code> processes the + documents in the specified <code>InputStream</code>'s data, it calls registered <code> + POIFSReaderListener + </code> instances' <code>processPOIFSReaderEvent</code> method with a <code>POIFSReaderEvent + </code> instance. + </p> + <p>The <code>POIFSReaderEvent</code> instance contains information to identify the document (a <code> + POIFSDocumentPath + </code> object to identify the directory that the document is in, and the document name), and an + open <code>DocumentInputStream</code> instance from which to read the document. + </p> + </section> + </section> + </section> + + <section> + <title>Writing a File System</title> + <anchor id="writing"/> + <p>Writing a file system is very much like reading a file system in that there are multiple ways to do so. + You can load an existing file system into memory and modify it (removing files, renaming files) and/or + add new files to it, and write it, or you can start with a new, empty file system: + </p> + <source> + POIFSFileSystem fs = new POIFSFileSystem(); + </source> + <section> + <title>The Naming of Names</title> + <p>There are two restrictions on the names of files in a file system that must be considered when + creating files: + </p> + <ol> + <li>The name of the file must not exceed 31 characters. If it does, the POIFS API will silently + truncate the name to fit. + </li> + <li>The name of the file must be unique within its containing directory. This seems pretty obvious, + but if it isn't spelled out, there'll be hell to pay, to be sure. Uniqueness, of course, is + determined <em>after</em> the name has been truncated, if the original name was too long to + begin with. + </li> + </ol> + </section> + <section> + <title>Creating a Document</title> + <p>A document can be created by acquiring a <code>DirectoryEntry</code> and calling one of the two <code> + createDocument + </code> methods: + </p> + + <dl> + <dt>createDocument(String name, InputStream stream)</dt> + <dd> + <ul> + <li class="pro">Simple API</li> + <li class="con">Increased memory footprint (document is in memory until file system is + written). + </li> + </ul> + </dd> + <dt>createDocument(String name, int size, POIFSWriterListener writer)</dt> + <dd> + <ul> + <li class="pro">Decreased memory footprint (only very small documents are held in memory, + and then only for a short time). + </li> + <li class="con">More complex API.</li> + <li class="con">Determining document size in advance may be difficult.</li> + <li class="con">Lose control over when document is to be written.</li> + </ul> + </dd> + </dl> + + <p>Unlike reading, you don't have to choose between the in-memory and event-driven writing models; both + can co-exist in the same file system. + </p> + <p>Writing is initiated when the <code>POIFSFileSystem</code> instance's <code>writeFilesystem()</code> method + is called with an <code>OutputStream</code> to write to. + </p> + <p>The event-driven model is quite similar to the event-driven model for reading, in that the file + system calls your <code>org.apache.poi.poifs.filesystem.POIFSWriterListener</code> when it's time to + write your document, just as the <code>POIFSReader</code> calls your <code>POIFSReaderListener + </code> when it's time to read your document. Internally, when <code>writeFilesystem()</code> is + called, the final POIFS data structures are created and are written to the specified <code> + OutputStream</code>. When the file system needs to write a document out that was created with + the event-driven model, it calls the <code>POIFSWriterListener</code> back, calling its <code> + processPOIFSWriterEvent() + </code> method, passing an <code>org.apache.poi.poifs.filesystem.POIFSWriterEvent</code> instance. + This object contains the <code>POIFSDocumentPath</code> and name of the document, its size, and an + open <code>org.apache.poi.poifs.filesystem.DocumentOutputStream</code> to which to write. A <code> + DocumentOutputStream + </code> is a wrapper over the <code>OutputStream</code> that was provided to the <code> + POIFSFileSystem + </code> to write to, and has the responsibility of making sure that the document your application + writes fits within the size you specified for it. + </p> + <p>If you are using a <code>POIFSFileSystem</code> loaded from a + <code>File</code> + with <code>readOnly</code> set to false, it is also possible to do an in-place write. Simply call <code> + writeFilesystem() + </code> to have the (limited) in-memory structures synced with the disk, then <code>close()</code> to + finish. + </p> + </section> + <section> + <title>Creating a Directory</title> + <p>Creating a directory is similar to creating a document, except that there's only one way to do so: + </p> + <source> + DirectoryEntry createdDir = existingDir.createDirectory(name); + </source> + </section> + <section> + <title>Using POIFSFileSystem Directly To Create a Document Or Directory</title> + <p>As with reading documents, it is possible to create a new document or directory in the root directory + by using convenience methods of POIFSFileSystem. + </p> + <table> + <tr> + <td> + <em>DirectoryEntry Method Signature</em> + </td> + <td> + <em>POIFSFileSystem Method Signature</em> + </td> + </tr> + <tr> + <td>createDocument(String name, InputStream stream)</td> + <td>createDocument(InputStream stream, String name)</td> + </tr> + <tr> + <td>createDocument(String name, int size, POIFSWriterListener writer)</td> + <td>createDocument(String name, int size, POIFSWriterListener writer)</td> + </tr> + <tr> + <td>createDirectory(String name)</td> + <td>createDirectory(String name)</td> + </tr> + </table> + </section> + </section> + + <section> + <title>Modifying a File System</title> + <anchor id="modifying"/> + <p>It is possible to modify an existing POIFS file system, whether it's one your application has loaded into + memory, or one which you are creating on the fly. + </p> + <section> + <title>Removing a Document</title> + <p>Removing a document is simple: you get the <code>Entry</code> corresponding to the document and call + its <code>delete()</code> method. This is a boolean method, but should always return <code> + true</code>, indicating that the operation succeeded. + </p> + </section> + <section> + <title>Removing a Directory</title> + <p>Removing a directory is also simple: you get the <code>Entry</code> corresponding to the directory + and call its <code>delete()</code> method. This is a boolean method, but, unlike deleting a + document, may not always return <code>true</code>, indicating that the operation succeeded. Here are + the reasons why the operation may fail: + </p> + <ul> + <li>The directory still has files in it (to check, call <code>isEmpty()</code> on its + DirectoryEntry; is the return value <code>false</code>?) + </li> + <li>The directory is the root directory. You cannot remove the root directory.</li> + </ul> + </section> + <section> + <title>Changing a File's contents</title> + <p>There are two ways available to change the contents of an existing file within a POIFS file system. + One is using a <code>DocumentOutputStream</code>, the other is with + <code>POIFSDocument.replaceContents</code> + </p> + <p>If you have available to you an <code>InputStream</code> to read the new File contents from, then the + easiest way is via + <code>POIFSDocument.replaceContents</code>. You would do something like: + </p> + <source><![CDATA[ + // Get the input stream from somewhere + InputStream inp = db.getContentStream(); + + // Open the POIFS File System, and get the entry of interest + + POIFSFileSystem fs = new POIFSFileSystem(new File(filename), false); + DirectoryEntry root = fs.getRoot(); + DocumentEntry myDocE = (DocumentEntry)root.getEntry("ToChange"); + + // Replace the contents + POIFSDocument myDoc = new POIFSDocument(myDocE); + myDoc.replaceContents(inp); + + // Save the changes to the file in-place + fs.writeFileSystem(); + fs.close(); + ]]></source> + <p>Alternately, if you either have a byte array, or you need to write as you go along, then the + OutputStream interface provided by + <code>DocumentOutputStream</code> + will likely be a better bet. Your code would want to look somewhat like: + </p> + <source><![CDATA[ + // Open the POIFS File System, and get the entry of interest + try (POIFSFileSystem fs = new POIFSFileSystem(new File(filename))) { + DirectoryEntry root = fs.getRoot(); + DocumentEntry myDoc = (DocumentEntry)root.getEntry("ToChange"); + + // Replace the content with a Write + try (DocumentOutputStream docOut = new DocumentOutputStream(myDoc)) { + myDoc.writeTo(docOut); + } + + // Save the changes to a new file + try (FileOutputStream out = new FileOutputStream("NewFile.ole2")) { + fs.write(out); + } + } + ]]></source> + <p>For an example of an in-place change to one stream within a file, you can see the example + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hpsf/ModifyDocumentSummaryInformation.java"> + org/apache/poi/hpsf/examples/ModifyDocumentSummaryInformation.java + </a> + </p> + </section> + <section> + <title>Renaming a File</title> + <p>Regardless of whether the file is a directory or a document, it can be renamed, with one exception - + the root directory has a special name that is expected by the components of a major software + vendor's office suite, and the POIFS API will not let that name be changed. Renaming is done by + acquiring the file's corresponding <code>Entry</code> instance and calling its <code>renameTo</code> method, + passing in the new name. + </p> + <p>Like <code>delete</code>, <code>renameTo</code> returns <code>true</code> if the operation succeeded, + otherwise <code>false</code>. Reasons for failure include these: + </p> + <ul> + <li>The new name is the same as another file in the same directory. And don't forget - if the new + name is longer than 31 characters, it <em>will</em> be silently truncated. In its original + length, the new name may have been unique, but truncated to 31 characters, it may not be unique + any longer. + </li> + <li>You tried to rename the root directory.</li> + </ul> + </section> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/poifs/index.xml b/src/documentation/content/xdocs/components/poifs/index.xml new file mode 100644 index 0000000000..986419d6f9 --- /dev/null +++ b/src/documentation/content/xdocs/components/poifs/index.xml @@ -0,0 +1,58 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> +<document> + <header> + <title>Apache POI™ - POIFS - Java implementation of the OLE 2 Compound Document format</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Andrew C. Oliver" email="acoliver@apache.org"/> + <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/> + </authors> + </header> + <body> + <section><title>Overview</title> + <p>POIFS is a pure Java implementation of the OLE 2 Compound + Document format.</p> + <p>By definition, all APIs developed by the POI project are + based somehow on the POIFS API.</p> + <p>A common confusion is on just what POIFS buys you or what OLE + 2 Compound Document format is exactly. POIFS does not buy you + DOC, or XLS, but is necessary to generate or read DOC or XLS + files. You see, all file formats based on the OLE 2 Compound + Document Format have a common structure. The OLE 2 Compound + Document Format is essentially a convoluted archive + format. Think of POIFS as a "zip" library. Once you can get + the data in a zip file you still need to interpret the + data. As a general rule, while all of our formats <em>use</em> + POIFS, most of them attempt to abstract you from it. There + are some circumstances where this is not possible, but as a + general rule this is true.</p> + <p>If you're an end user type just looking to generate XLS + files, then you'd be looking for HSSF not POIFS; however, if + you have legacy code that uses MFC property sets, POIFS is + for you! Regardless, you may or may not need to know how to + use POIFS but ultimately if you use technologies that come + from the POI project, you're using POIFS underneath. Perhaps + we should have a branding campaign "POIFS Inside!". ;-)</p> + + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/poifs/usecases.xml b/src/documentation/content/xdocs/components/poifs/usecases.xml new file mode 100644 index 0000000000..597f77ef4b --- /dev/null +++ b/src/documentation/content/xdocs/components/poifs/usecases.xml @@ -0,0 +1,653 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> +<document> + <header> + <title>POIFS Use Cases</title> + <authors> + <person email="mjohnson@apache.org" name="Marc Johnson" id="MJ"/> + </authors> + </header> + <body> + <section><title>POIFS Use Cases</title> + <section><title>Use Case 1: Read existing file system</title> + <table> + <tr> + <td><em>Primary Actor:</em></td> + <td>POIFS client</td> + </tr> + <tr> + <td><em>Scope:</em></td> + <td>POIFS</td> + </tr> + <tr> + <td><em>Level:</em></td> + <td>Summary</td> + </tr> + <tr> + <td><em>Stakeholders and Interests:</em></td> + <td> + POIFS client- wants to read content of file + system<br/> + POIFS - understands POIFS file system + </td> + </tr> + <tr> + <td><em>Precondition:</em></td> + <td>None</td> + </tr> + <tr> + <td><em>Minimal Guarantee:</em></td> + <td>None</td> + </tr> + <tr> + <td><em>Main Success Guarantee:</em></td> + <td> + 1. POIFS client requests POIFS to read a POIFS file + system, providing an + <code>InputStream</code> + containing POIFS file system in question.<br/> + 2. POIFS reads from the + <code>InputStream</code> in + 512 byte blocks.<br/> + 3. POIFS verifies that the first block begins with + the well known signature + ( + <code>0xE11AB1A1E011CFD0</code>)<br/> + 4. POIFS reads the Block Allocation Table from the + first block and, if necessary, from the XBAT + blocks.<br/> + 5. POIFS obtains the start block of the Property + Table and reads the Property Table (use case 9, + read file)<br/> + 6. POIFS reads the individual entries in the Property + Table<br/> + 7. POIFS obtains the start block of the Small Block + Allocation Table and reads the Small Block + Allocation Table (use case 9, read file)<br/> + 8. POIFS obtains the start block of the Small Block + store from the first entry in the Property Table + and reads the Small Block Array (use case 9, read + file)<br/> + </td> + </tr> + <tr> + <td><em>Extensions:</em></td> + <td> + 2a. If the last block read is not a 512 byte + block, the + <code>InputStream</code> is not that of + a POIFS file system, and POIFS throws an + appropriate exception. + <br/> + 3a. If the signature is incorrect, the + <code>InputStream</code> is not that of a POIFS + file system, and POIFS throws an appropriate + exception.<br/> + </td> + </tr> + </table> + </section> + <section><title>Use Case 2: Write file system</title> + <table> + <tr> + <th>Primary Actor:</th> + <th>POIFS client</th> + </tr> + <tr> + <th>Scope:</th> + <td>POIFS</td> + </tr> + <tr> + <th>Level:</th> + <td>Summary</td> + </tr> + <tr> + <th>Stakeholders and Interests:</th> + <td> + POIFS client- wants to write file system out.<br/> + POIFS - knows how to write file system out. + </td> + </tr> + <tr> + <th>Precondition:</th> + <td> + File system has been read (use case 1, read + existing file system) and subsequently modified + (use case 4, replace file in file system; use case + 5, delete file from file system; or use case 6, + write new file to file system; in any + combination) + <br/>or<br/> + File system has been created (use case 3, create + new file system) + </td> + </tr> + <tr> + <th>Minimal Guarantee:</th> + <td>None</td> + </tr> + <tr> + <th>Main Success Guarantee:</th> + <td> + 1. POIFS client provides an + <code>OutputStream</code> + to write the file system to. + <br/> + 2. POIFS gets the sizes of the Property Table and + each file in the file system.<br/> + 3. If any files in the file system requires storage + in a Small Block Array, POIFS creates a Small + Block Array of sufficient size to hold all of the + small files.<br/> + 4. POIFS calculates the number of big blocks needed + to hold all of the large files, the Property + Table, and, if necessary, the Small Block Array + and the Small Block Allocation Table.<br/> + 5. POIFS creates a set of big blocks sufficient to + store the Block Allocation Table<br/> + 6. POIFS creates and writes the header block<br/> + 7. POIFS writes out the XBAT blocks, if needed.<br/> + 8. POIFS writes out the Small Block Array, if + needed<br/> + 9. POIFS writes out the Small Block Allocation Table, + if needed<br/> + 10. POIFS writes out the Property Table<br/> + 11. POIFS writes out the large files, if needed<br/> + 12. POIFS closes the <code>OutputStream</code>. + </td> + </tr> + <tr> + <th>Extensions:</th> + <td> + 6a. Exceptions writing to the + <code>OutputStream</code> will be propagated back + to the POIFS client. + <br/> + 7a. Exceptions writing to the + <code>OutputStream</code> will be propagated back + to the POIFS client. + <br/> + 8a. Exceptions writing to the + <code>OutputStream</code> will be propagated back + to the POIFS client. + <br/> + 9a. Exceptions writing to the + <code>OutputStream</code> will be propagated back + to the POIFS client. + <br/> + 10a. Exceptions writing to the + <code>OutputStream</code> will be propagated back + to the POIFS client. + <br/> + 11a. Exceptions writing to the + <code>OutputStream</code> will be propagated back + to the POIFS client. + <br/> + 12a. Exceptions closing the + <code>OutputStream</code> will be propagated back + to the POIFS client. + <br/> + </td> + </tr> + </table> + </section> + <section><title>Use Case 3: Create new file system</title> + <table> + <tr> + <th>Primary Actor:</th> + <td>POIFS client</td> + </tr> + <tr> + <th>Scope:</th> + <td>POIFS</td> + </tr> + <tr> + <th>Level:</th> + <td>Summary</td> + </tr> + <tr> + <th>Stakeholders and Interests:</th> + <td> + POIFS client- wants to create a new file + system<br/> + POIFS - knows how to create a new file system + </td> + </tr> + <tr> + <th>Precondition:</th> + <td>None</td> + </tr> + <tr> + <th>Minimal Guarantee:</th> + <td>None</td> + </tr> + <tr> + <th>Main Success Guarantee:</th> + <td> + POIFS creates an empty Property Table. + </td> + </tr> + <tr> + <th>Extensions:</th> + <td>None</td> + </tr> + </table> + </section> + <section><title>Use Case 4: Replace file in file system</title> + <table> + <tr> + <td><em>Primary Actor:</em></td> + <td>POIFS client</td> + </tr> + <tr> + <td><em>Scope:</em></td> + <td>POIFS</td> + </tr> + <tr> + <td><em>Level:</em></td> + <td>Summary</td> + </tr> + <tr> + <td><em>Stakeholders and Interests:</em></td> + <td> + 1. POIFS client- wants to replace an existing file in + the file system<br/> + 2. POIFS - knows how to manage the file system + </td> + </tr> + <tr> + <td><em>Precondition:</em></td> + <td> + Either + <br/><br/> + The file system has been read (use case 1, read + existing file system) and a file has been + extracted from the file system (use case 7, read + existing file from file system) + <br/><br/>or<br/><br/> + The file system has been created (use case 3, + create new file system) and a file has been + written to the file system (use case 6, write new + file to file system) + </td> + </tr> + <tr> + <td><em>Minimal Guarantee:</em></td> + <td>None</td> + </tr> + <tr> + <td><em>Main Success Guarantee:</em></td> + <td> + 1. POIFS discards storage of the existing file.<br/> + 2. POIFS updates the existing file's entry in the + Property Table<br/> + 3. POIFS stores the new file's data + </td> + </tr> + <tr> + <td><em>Extensions:</em></td> + <td> + 1a. POIFS throws an exception if the file does not + exist. + </td> + </tr> + </table> + </section> + <section><title>Use Case 5: Delete file from file system</title> + <table> + <tr> + <td><em>Primary Actor:</em></td> + <td>POIFS client</td> + </tr> + <tr> + <td><em>Scope:</em></td> + <td>POIFS</td> + </tr> + <tr> + <td><em>Level:</em></td> + <td>Summary</td> + </tr> + <tr> + <td><em>Stakeholders and Interests:</em></td> + <td> + * POIFS client- wants to remove a file from a file + system<br/> + * POIFS - knows how to manage the file system + </td> + </tr> + <tr> + <td><em>Precondition:</em></td> + <td> + Either<br/><br/> + The file system has been read (use case 1, read + existing file system) and a file has been + extracted from the file system (use case 7, read + existing file from file system)<br/> + <br/> + or<br/> + <br/> + The file system has been created (use case 3, + create new file system) and a file has been + written to the file system (use case 6, write new + file to file system) + </td> + </tr> + <tr> + <td><em>Minimal Guarantee:</em></td> + <td>None</td> + </tr> + <tr> + <td><em>Main Success Guarantee:</em></td> + <td> + 1. POIFS discards the specified file's storage.<br/> + 2. POIFS discards the file's Property Table + entry. + </td> + </tr> + <tr> + <td><em>Extensions:</em></td> + <td> + 1a. POIFS throws an exception if the file does not + exist. + </td> + </tr> + </table> + </section> + <section><title>Use Case 6: Write new file to file system</title> + <table> + <tr> + <td><em>Primary Actor:</em></td> + <td>POIFS client</td> + </tr> + <tr> + <td><em>Scope:</em></td> + <td>POIFS</td> + </tr> + <tr> + <td><em>Level:</em></td> + <td>Summary</td> + </tr> + <tr> + <td><em>Stakeholders and Interests:</em></td> + <td> + * POIFS client- wants to add a new file to the file + system<br/> + * POIFS - knows how to manage the file system + </td> + </tr> + <tr> + <td><em>Precondition:</em></td> + <td>The specified file does not yet exist in the file + system</td> + </tr> + <tr> + <td><em>Minimal Guarantee:</em></td> + <td>None</td> + </tr> + <tr> + <td><em>Main Success Guarantee:</em></td> + <td> + 1. The POIFS client provides a file name<br/> + 2. POIFS creates a new Property Table entry for the + new file<br/> + 3. POIFS provides the POIFS client with an + <code>OutputStream</code> to write to.<br/> + 4. The POIFS client writes data to the provided + <code>OutputStream</code>.<br/> + 5. The POIFS client closes the provided + <code>OutputStream</code><br/> + 6. POIFS updates the Property Table entry with the + new file's size + </td> + </tr> + <tr> + <td><em>Extensions:</em></td> + <td> + 1a. POIFS throws an exception if a file with the + specified name already exists in the file + system.<br/> + 1b. POIFS throws an exception if the file name is + too long. The limit on file name length is 31 + characters. + </td> + </tr> + </table> + </section> + <section><title>Use Case 7: Read existing file from file system</title> + <table> + <tr> + <td><em>Primary Actor:</em></td> + <td>POIFS client</td> + </tr> + <tr> + <td><em>Scope:</em></td> + <td>POIFS</td> + </tr> + <tr> + <td><em>Level:</em></td> + <td>Summary</td> + </tr> + <tr> + <td><em>Stakeholders and Interests:</em></td> + <td> + * POIFS client- wants to read a file from the file + system<br/> + * POIFS - knows how to manage the file system + </td> + </tr> + <tr> + <td><em>Precondition:</em></td> + <td> + * The file system has been read (use case 1, read + existing file system) or has been created and + written to (use case 3, create new file system; + use case 6, write new file to file system).<br/> + * The specified file exists in the file system. + </td> + </tr> + <tr> + <td><em>Minimal Guarantee:</em></td> + <td>None</td> + </tr> + <tr> + <td><em>Main Success Guarantee:</em></td> + <td> + * The POIFS client provides the name of a file to be read <br/> + * POIFS provides an <code>InputStream</code> to read from. <br/> + * The POIFS client reads from the <code>InputStream</code>.<br/> + * The POIFS client closes the <code>InputStream</code>. + </td> + </tr> + <tr> + <td><em>Extensions:</em></td> + <td>1a. POIFS throws an exception if no file with the + specified name exists.</td> + </tr> + </table> + </section> + <section><title>Use Case 8: Read file system directory</title> + <table> + <tr> + <td><em>Primary Actor:</em></td> + <td>POIFS client</td> + </tr> + <tr> + <td><em>Scope:</em></td> + <td>POIFS</td> + </tr> + <tr> + <td><em>Level:</em></td> + <td>Summary</td> + </tr> + <tr> + <td><em>Stakeholders and Interests:</em></td> + <td> + * POIFS client- wants to know what files exist in + the file system<br/> + * POIFS - knows how to manage the file system + </td> + </tr> + <tr> + <td><em>Precondition:</em></td> + <td>The file system has been read (use case 1, read + existing file system) or created (use case 3, create + new file system)</td> + </tr> + <tr> + <td><em>Minimal Guarantee:</em></td> + <td>None</td> + </tr> + <tr> + <td><em>Main Success Guarantee:</em></td> + <td> + 1. The POIFS client requests the file system + directory. + 2. POIFS returns an <code>Iterator</code>. The + <code>Iterator</code> will not include the root + entry in the Property Table, and may be an + <code>Iterator</code> over an empty + <code>Collection</code>. + </td> + </tr> + <tr> + <td><em>Extensions:</em></td> + <td>None</td> + </tr> + </table> + </section> + <section><title>Use Case 9: Read file</title> + <table> + <tr> + <td><em>Primary Actor:</em></td> + <td>POIFS</td> + </tr> + <tr> + <td><em>Scope:</em></td> + <td>POIFS</td> + </tr> + <tr> + <td><em>Level:</em></td> + <td>Summary</td> + </tr> + <tr> + <td><em>Stakeholders and Interests:</em></td> + <td> + POIFS - POIFS needs to read a file, or something + resembling a file (i.e., the Property Table, the + Small Block Array, or the Small Block Allocation + Table) + </td> + </tr> + <tr> + <td><em>Precondition:</em></td> + <td>None</td> + </tr> + <tr> + <td><em>Minimal Guarantee:</em></td> + <td>None</td> + </tr> + <tr> + <td><em>Main Success Guarantee:</em></td> + <td> + 1. POIFS begins with a start block, a file size, and + a flag indicating whether to use the Big Block + Allocation Table or the Small Block Allocation + Table<br/> + 2. POIFS returns an <code>InputStream</code>.<br/> + 3. Reads from the <code>InputStream</code> are + performed by walking the specified Block + Allocation Table and reading the blocks + indicated.<br/> + 4. POIFS closes the <code>InputStream</code> when + finished reading the file, or its client wants to + close the <code>InputStream</code>. + </td> + </tr> + <tr> + <td><em>Extensions:</em></td> + <td>3a. An exception will be thrown if the specified Block + Allocation Table is corrupt, as evidenced by an index + pointing to a non-existent block, or by a chain + extending past the known size of the file.</td> + </tr> + </table> + </section> + <section><title>Use Case 10: Rename existing file in the file system</title> + <table> + <tr> + <td><em>Primary Actor:</em></td> + <td>POIFS client</td> + </tr> + <tr> + <td><em>Scope:</em></td> + <td>POIFS</td> + </tr> + <tr> + <td><em>Level:</em></td> + <td>Summary</td> + </tr> + <tr> + <td><em>Stakeholders and Interests:</em></td> + <td> + * POIFS client- wants to rename an existing file in + the file system.<br/> + * POIFS - knows how to manage the file system. + </td> + </tr> + <tr> + <td><em>Precondition:</em></td> + <td> + * The file system is has been read (use case 1, read + existing file system) or has been created and + written to (use case 3, create new file system; + use case 6, write new file to file system.<br/> + * The specified file exists in the file system.<br/> + * The new name for the file does not duplicate + another file in the file system. + </td> + </tr> + <tr> + <td><em>Minimal Guarantee:</em></td> + <td>None</td> + </tr> + <tr> + <td><em>Main Success Guarantee:</em></td> + <td> + 1. POIFS updates the Property Table entry for the + specified file with its new name. + </td> + </tr> + <tr> + <td><em>Extensions:</em></td> + <td> + * 1a. If the old file name is not in the file + system, POIFS throws an exception.<br/> + * 1b. If the new file name already exists in the + file system, POIFS throws an exception.<br/> + * 1c. If the new file name is too long (the limit is + 31 characters), POIFS throws an exception. + </td> + </tr> + </table> + </section> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/slideshow/how-to-shapes.xml b/src/documentation/content/xdocs/components/slideshow/how-to-shapes.xml new file mode 100644 index 0000000000..f1183c357d --- /dev/null +++ b/src/documentation/content/xdocs/components/slideshow/how-to-shapes.xml @@ -0,0 +1,642 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Busy Developers' Guide to HSLF drawing layer</title> + <authors> + <person email="yegor@dinom.ru" name="Yegor Kozlov" id="CO"/> + </authors> + </header> + <body> + <section><title>Busy Developers' Guide to HSLF drawing layer</title> + <section><title>Index of Features</title> + <ul> + <li><a href="#NewPresentation">How to create a new presentation and add new slides to it</a></li> + <li><a href="#PageSize">How to retrieve or change slide size</a></li> + <li><a href="#GetShapes">How to get shapes contained in a particular slide</a></li> + <li><a href="#Shapes">Drawing a shape on a slide</a></li> + <li><a href="#Pictures">How to work with pictures</a></li> + <li><a href="#SlideTitle">How to set slide title</a></li> + <li><a href="#Fill">How to work with slide/shape background</a></li> + <li><a href="#Bullets">How to create bulleted lists</a></li> + <li><a href="#Hyperlinks">Hyperlinks</a></li> + <li><a href="#Tables">Tables</a></li> + <li><a href="#RemoveShape">How to remove shapes</a></li> + <li><a href="#OLE">How to retrieve embedded OLE objects</a></li> + <li><a href="#Sound">How to retrieve embedded sounds</a></li> + <li><a href="#Freeform">How to create shapes of arbitrary geometry</a></li> + <li><a href="#Graphics2D">Shapes and Graphics2D</a></li> + <li><a href="#Render">How to convert slides into images</a></li> + <li><a href="#HeadersFooters">Headers / Footers</a></li> + </ul> + </section> + <section><title>Features</title> + <anchor id="NewPresentation"/> + <section><title>New Presentation</title> + <source> + //create a new empty slide show + HSLFSlideShow ppt = new HSLFSlideShow(); + + //add first slide + HSLFSlide s1 = ppt.createSlide(); + + //add second slide + HSLFSlide s2 = ppt.createSlide(); + + //save changes in a file + FileOutputStream out = new FileOutputStream("slideshow.ppt"); + ppt.write(out); + out.close(); + </source> + </section> + <anchor id="PageSize"/> + <section><title>How to retrieve or change slide size</title> + <source> + HSLFSlideShow ppt = new HSLFSlideShow(new HSLFSlideShowImpl("slideshow.ppt")); + //retrieve page size. Coordinates are expressed in points (72 dpi) + java.awt.Dimension pgsize = ppt.getPageSize(); + int pgx = pgsize.width; //slide width + int pgy = pgsize.height; //slide height + + //set new page size + ppt.setPageSize(new java.awt.Dimension(1024, 768)); + //save changes + FileOutputStream out = new FileOutputStream("slideshow.ppt"); + ppt.write(out); + out.close(); + </source> + </section> + <anchor id="GetShapes"/> + <section><title>How to get shapes contained in a particular slide</title> + <p> + The following code demonstrates how to iterate over shapes for each slide. + </p> + <source> + HSLFSlideShow ppt = new HSLFSlideShow(new HSLFSlideShowImpl("slideshow.ppt")); + // get slides + for (HSLFSlide slide : ppt.getSlides()) { + for (HSLFShape sh : slide.getShapes()) { + // name of the shape + String name = sh.getShapeName(); + + // shapes's anchor which defines the position of this shape in the slide + java.awt.Rectangle anchor = sh.getAnchor(); + + if (sh instanceof Line) { + Line line = (Line) sh; + // work with Line + } else if (sh instanceof HSLFAutoShape) { + HSLFAutoShape shape = (HSLFAutoShape) sh; + // work with AutoShape + } else if (sh instanceof HSLFTextBox) { + HSLFTextBox shape = (HSLFTextBox) sh; + // work with TextBox + } else if (sh instanceof HSLFPictureShape) { + HSLFPictureShape shape = (HSLFPictureShape) sh; + // work with Picture + } + } + } + </source> + </section> + <anchor id="Shapes"/> + <section><title>Drawing a shape on a slide</title> + <warning> + To work with graphic objects HSLF uses Java2D classes + that may throw exceptions if graphical environment is not available. In case if graphical environment + is not available, you must tell Java that you are running in headless mode and + set the following system property: <code> java.awt.headless=true </code> + (either via <code>-Djava.awt.headless=true</code> startup parameter or via <code>System.setProperty("java.awt.headless", "true")</code>). + </warning> + <p> + When you add a shape, you usually specify the dimensions of the shape and the position + of the upper left corner of the bounding box for the shape relative to the upper left + corner of the slide. Distances in the drawing layer are measured in points (72 points = 1 inch). + </p> + <source> + HSLFSlideShow ppt = new HSLFSlideShow(); + + HSLFSlide slide = ppt.createSlide(); + + //Line shape + Line line = new Line(); + line.setAnchor(new java.awt.Rectangle(50, 50, 100, 20)); + line.setLineColor(new Color(0, 128, 0)); + line.setLineCompound(LineCompound.DOUBLE); + slide.addShape(line); + + //TextBox + HSLFTextBox txt = new HSLFTextBox(); + txt.setText("Hello, World!"); + txt.setAnchor(new java.awt.Rectangle(300, 100, 300, 50)); + + // use TextRun to work with the text format + HSLFTextParagraph tp = txt.getTextParagraphs().get(0); + tp.setAlignment(TextAlign.RIGHT); + HSLFTextRun rt = tp.getTextRuns().get(0); + rt.setFontSize(32.); + rt.setFontFamily("Arial"); + rt.setBold(true); + rt.setItalic(true); + rt.setUnderlined(true); + rt.setFontColor(Color.red); + + slide.addShape(txt); + + // Autoshape + // 32-point star + HSLFAutoShape sh1 = new HSLFAutoShape(ShapeType.STAR_32); + sh1.setAnchor(new java.awt.Rectangle(50, 50, 100, 200)); + sh1.setFillColor(Color.red); + slide.addShape(sh1); + + //Trapezoid + HSLFAutoShape sh2 = new HSLFAutoShape(ShapeType.TRAPEZOID); + sh2.setAnchor(new java.awt.Rectangle(150, 150, 100, 200)); + sh2.setFillColor(Color.blue); + slide.addShape(sh2); + + FileOutputStream out = new FileOutputStream("slideshow.ppt"); + ppt.write(out); + out.close(); + </source> + </section> + <anchor id="Pictures"/> + <section><title>How to work with pictures</title> + + <p> + Currently, HSLF API supports the following types of pictures: + </p> + <ul> + <li>Windows Metafiles (WMF)</li> + <li>Enhanced Metafiles (EMF)</li> + <li>JPEG Interchange Format</li> + <li>Portable Network Graphics (PNG)</li> + <li>Macintosh PICT</li> + </ul> + + <source> + HSLFSlideShow ppt = new HSLFSlideShow(new HSLFSlideShowImpl("slideshow.ppt")); + + // extract all pictures contained in the presentation + int idx = 1; + for (HSLFPictureData pict : ppt.getPictureData()) { + // picture data + byte[] data = pict.getData(); + + PictureData.PictureType type = pict.getType(); + String ext = type.extension; + FileOutputStream out = new FileOutputStream("pict_" + idx + ext); + out.write(data); + out.close(); + idx++; + } + + // add a new picture to this slideshow and insert it in a new slide + HSLFPictureData pd = ppt.addPicture(new File("clock.jpg"), PictureData.PictureType.JPEG); + + HSLFPictureShape pictNew = new HSLFPictureShape(pd); + + // set image position in the slide + pictNew.setAnchor(new java.awt.Rectangle(100, 100, 300, 200)); + + HSLFSlide slide = ppt.createSlide(); + slide.addShape(pictNew); + + // now retrieve pictures containes in the first slide and save them on disk + idx = 1; + slide = ppt.getSlides().get(0); + for (HSLFShape sh : slide.getShapes()) { + if (sh instanceof HSLFPictureShape) { + HSLFPictureShape pict = (HSLFPictureShape) sh; + HSLFPictureData pictData = pict.getPictureData(); + byte[] data = pictData.getData(); + PictureData.PictureType type = pictData.getType(); + FileOutputStream out = new FileOutputStream("slide0_" + idx + type.extension); + out.write(data); + out.close(); + idx++; + } + } + + FileOutputStream out = new FileOutputStream("slideshow.ppt"); + ppt.write(out); + out.close(); + </source> + </section> + <anchor id="SlideTitle"/> + <section><title>How to set slide title</title> + <source> + HSLFSlideShow ppt = new HSLFSlideShow(); + HSLFSlide slide = ppt.createSlide(); + HSLFTextBox title = slide.addTitle(); + title.setText("Hello, World!"); + + // save changes + FileOutputStream out = new FileOutputStream("slideshow.ppt"); + ppt.write(out); + out.close(); + </source> + <p> + Below is the equivalent code in PowerPoint VBA: + </p> + <source> + Set myDocument = ActivePresentation.Slides(1) + myDocument.Shapes.AddTitle.TextFrame.TextRange.Text = "Hello, World!" + </source> + </section> + <anchor id="Fill"/> + <section><title>How to modify background of a slide master</title> + <source> + HSLFSlideShow ppt = new HSLFSlideShow(); + HSLFSlideMaster master = ppt.getSlideMasters().get(0); + + HSLFFill fill = master.getBackground().getFill(); + HSLFPictureData pd = ppt.addPicture(new File("background.png"), PictureData.PictureType.PNG); + fill.setFillType(HSLFFill.FILL_PICTURE); + fill.setPictureData(pd); + </source> + </section> + <section><title>How to modify background of a slide</title> + <source> + HSLFSlideShow ppt = new HSLFSlideShow(); + HSLFSlide slide = ppt.createSlide(); + + // This slide has its own background. + // Without this line it will use master's background. + slide.setFollowMasterBackground(false); + HSLFFill fill = slide.getBackground().getFill(); + HSLFPictureData pd = ppt.addPicture(new File("background.png"), PictureData.PictureType.PNG); + fill.setFillType(HSLFFill.FILL_PATTERN); + fill.setPictureData(pd); + </source> + </section> + <section><title>How to modify background of a shape</title> + <source> + HSLFSlideShow ppt = new HSLFSlideShow(); + HSLFSlide slide = ppt.createSlide(); + + HSLFShape shape = new HSLFAutoShape(ShapeType.RECT); + shape.setAnchor(new java.awt.Rectangle(100, 100, 200, 200)); + HSLFFill fill = shape.getFill(); + fill.setFillType(HSLFFill.FILL_SHADE); + fill.setBackgroundColor(Color.red); + fill.setForegroundColor(Color.green); + + slide.addShape(shape); + </source> + </section> + <anchor id="Bullets"/> + <section><title>How to create bulleted lists</title> + <source> + HSLFSlideShow ppt = new HSLFSlideShow(); + + HSLFSlide slide = ppt.createSlide(); + + HSLFTextBox shape = new HSLFTextBox(); + HSLFTextParagraph tp = shape.getTextParagraphs().get(0); + tp.setBullet(true); + tp.setBulletChar('\u263A'); //bullet character + tp.setIndent(0.); //bullet offset + tp.setLeftMargin(50.); //text offset (should be greater than bullet offset) + HSLFTextRun rt = tp.getTextRuns().get(0); + shape.setText( + "January\r" + + "February\r" + + "March\r" + + "April"); + rt.setFontSize(42.); + slide.addShape(shape); + + shape.setAnchor(new java.awt.Rectangle(50, 50, 500, 300)); //position of the text box in the slide + slide.addShape(shape); + + FileOutputStream out = new FileOutputStream("bullets.ppt"); + ppt.write(out); + out.close(); + </source> + </section> + <anchor id="Hyperlinks"/> + <section><title>How to read hyperlinks from a slide show</title> + <source> + FileInputStream is = new FileInputStream("slideshow.ppt"); + HSLFSlideShow ppt = new HSLFSlideShow(is); + is.close(); + + for (HSLFSlide slide : ppt.getSlides()) { + //read hyperlinks from the text runs + for (List<HSLFTextParagraph> txt : slide.getTextParagraphs()) { + for (HSLFTextParagraph para : txt) { + for (HSLFTextRun run : para) { + HSLFHyperlink link = run.getHyperlink(); + if (link != null) { + String title = link.getLabel(); + String address = link.getAddress(); + String text = run.getRawText(); + } + } + } + } + + //in PowerPoint you can assign a hyperlink to a shape without text, + //for example to a Line object. The code below demonstrates how to + //read such hyperlinks + for (HSLFShape sh : slide.getShapes()) { + if (sh instanceof HSLFSimpleShape) { + HSLFHyperlink link = ((HSLFSimpleShape)sh).getHyperlink(); + if(link != null) { + String title = link.getLabel(); + String address = link.getAddress(); + } + } + } + } + </source> + </section> + <anchor id="Tables"/> + <section><title>How to create tables</title> + <source> + //table data + String[][] data = { + {"INPUT FILE", "NUMBER OF RECORDS"}, + {"Item File", "11,559"}, + {"Vendor File", "300"}, + {"Purchase History File", "10,000"}, + {"Total # of requisitions", "10,200,038"} + }; + + HSLFSlideShow ppt = new HSLFSlideShow(); + + HSLFSlide slide = ppt.createSlide(); + //create a table of 5 rows and 2 columns + HSLFTable table = new HSLFTable(5, 2); + for (int i = 0; i < data.length; i++) { + for (int j = 0; j < data[i].length; j++) { + HSLFTableCell cell = table.getCell(i, j); + cell.setText(data[i][j]); + + HSLFTextRun rt = cell.getTextParagraphs().get(0).getTextRuns().get(0); + rt.setFontFamily("Arial"); + rt.setFontSize(10.); + + cell.setVerticalAlignment(VerticalAlignment.MIDDLE); + cell.setHorizontalCentered(true); + } + } + + //set table borders + Line border = table.createBorder(); + border.setLineColor(Color.black); + border.setLineWidth(1.0); + table.setAllBorders(border); + + //set width of the 1st column + table.setColumnWidth(0, 300); + //set width of the 2nd column + table.setColumnWidth(1, 150); + + slide.addShape(table); + table.moveTo(100, 100); + + FileOutputStream out = new FileOutputStream("hslf-table.ppt"); + ppt.write(out); + out.close(); + </source> + </section> + + <anchor id="RemoveShape"/> + <section><title>How to remove shapes from a slide</title> + <source> + for (HSLFShape shape : slide.getShapes()) { + // remove the shape + boolean ok = slide.removeShape(shape); + if (ok) { + // the shape was removed. Do something. + } + } + </source> + </section> + <anchor id="OLE"/> + <section><title>How to retrieve embedded OLE objects</title> + <source> + for (HSLFShape shape : slide.getShapes()) { + if (shape instanceof OLEShape) { + OLEShape ole = (OLEShape) shape; + HSLFObjectData data = ole.getObjectData(); + String name = ole.getInstanceName(); + if ("Worksheet".equals(name)) { + HSSFWorkbook wb = new HSSFWorkbook(data.getData()); + } else if ("Document".equals(name)) { + HWPFDocument doc = new HWPFDocument(data.getData()); + } + } + } + </source> + </section> + + <anchor id="Sound"/> + <section><title>How to retrieve embedded sounds</title> + <source> + FileInputStream is = new FileInputStream(args[0]); + HSLFSlideShow ppt = new HSLFSlideShow(is); + is.close(); + + for (HSLFSoundData sound : ppt.getSoundData()) { + // save *WAV sounds on disk + if (sound.getSoundType().equals(".WAV")) { + FileOutputStream out = new FileOutputStream(sound.getSoundName()); + out.write(sound.getData()); + out.close(); + } + } + </source> + </section> + + <anchor id="Freeform"/> + <section><title>How to create shapes of arbitrary geometry</title> + <source> + HSLFSlideShow ppt = new HSLFSlideShow(); + HSLFSlide slide = ppt.createSlide(); + + java.awt.geom.GeneralPath path = new java.awt.geom.GeneralPath(); + path.moveTo(100, 100); + path.lineTo(200, 100); + path.curveTo(50, 45, 134, 22, 78, 133); + path.curveTo(10, 45, 134, 56, 78, 100); + path.lineTo(100, 200); + path.closePath(); + + HSLFFreeformShape shape = new HSLFFreeformShape(); + shape.setPath(path); + slide.addShape(shape); + </source> + </section> + + <anchor id="Graphics2D"/> + <section><title>How to draw into a slide using Graphics2D</title> + <warning> + Current implementation of the PowerPoint Graphics2D driver is not fully compliant with the java.awt.Graphics2D specification. + Some features like clipping, drawing of images are not yet supported. + </warning> + <source> + HSLFSlideShow ppt = new HSLFSlideShow(); + HSLFSlide slide = ppt.createSlide(); + + // draw a simple bar graph + // bar chart data. + // The first value is the bar color, + // the second is the width + Object[] def = new Object[]{ + Color.yellow, new Integer(100), + Color.green, new Integer(150), + Color.gray, new Integer(75), + Color.red, new Integer(200), + }; + + // all objects are drawn into a shape group so we need to create one + + HSLFGroupShape group = new HSLFGroupShape(); + // define position of the drawing in the slide + Rectangle bounds = new java.awt.Rectangle(200, 100, 350, 300); + // if you want to draw in the entire slide area then define the anchor + // as follows: + // Dimension pgsize = ppt.getPageSize(); + // java.awt.Rectangle bounds = new java.awt.Rectangle(0, 0, + // pgsize.width, pgsize.height); + + group.setAnchor(bounds); + slide.addShape(group); + + // draw a simple bar chart + Graphics2D graphics = new PPGraphics2D(group); + int x = bounds.x + 50, y = bounds.y + 50; + graphics.setFont(new Font("Arial", Font.BOLD, 10)); + for (int i = 0, idx = 1; i < def.length; i += 2, idx++) { + graphics.setColor(Color.black); + int width = ((Integer) def[i + 1]).intValue(); + graphics.drawString("Q" + idx, x - 20, y + 20); + graphics.drawString(width + "%", x + width + 10, y + 20); + graphics.setColor((Color) def[i]); + graphics.fill(new Rectangle(x, y, width, 30)); + y += 40; + } + graphics.setColor(Color.black); + graphics.setFont(new Font("Arial", Font.BOLD, 14)); + graphics.draw(bounds); + graphics.drawString("Performance", x + 70, y + 40); + + FileOutputStream out = new FileOutputStream("hslf-graphics2d.ppt"); + ppt.write(out); + out.close(); + </source> + </section> + + <anchor id="Render"/> + <section><title>Export PowerPoint slides into java.awt.Graphics2D</title> + <p> + HSLF provides a way to export slides into images. You can capture slides into java.awt.Graphics2D object (or any other) + and serialize it into a PNG or JPEG format. Please note, although HSLF attempts to render slides as close to PowerPoint as possible, + the output may look differently from PowerPoint due to the following reasons: + </p> + <ul> + <li>Java2D renders fonts differently vs PowerPoint. There are always some differences in the way the font glyphs are painted</li> + <li>HSLF uses java.awt.font.LineBreakMeasurer to break text into lines. PowerPoint may do it in a different way.</li> + <li>If a font from the presentation is not available, then the JDK default font will be used.</li> + </ul> + <p> + Current Limitations: + </p> + <ul> + <li>Some types of shapes are not yet supported (WordArt, complex auto-shapes)</li> + <li>Only Bitmap images (PNG, JPEG, DIB) can be rendered in Java</li> + </ul> + <source> + FileInputStream is = new FileInputStream("slideshow.ppt"); + HSLFSlideShow ppt = new HSLFSlideShow(is); + is.close(); + + Dimension pgsize = ppt.getPageSize(); + + int idx = 1; + for (HSLFSlide slide : ppt.getSlides()) { + + BufferedImage img = new BufferedImage(pgsize.width, pgsize.height, BufferedImage.TYPE_INT_RGB); + Graphics2D graphics = img.createGraphics(); + // clear the drawing area + graphics.setPaint(Color.white); + graphics.fill(new Rectangle2D.Float(0, 0, pgsize.width, pgsize.height)); + + // render + slide.draw(graphics); + + // save the output + FileOutputStream out = new FileOutputStream("slide-" + idx + ".png"); + javax.imageio.ImageIO.write(img, "png", out); + out.close(); + + idx++; + } + </source> + </section> + + </section> + <anchor id="HeadersFooters"/> + <section><title>How to extract Headers / Footers from an existing presentation</title> + <source> + FileInputStream is = new FileInputStream("slideshow.ppt"); + HSLFSlideShow ppt = new HSLFSlideShow(is); + is.close(); + + // presentation-scope headers / footers + HeadersFooters hdd = ppt.getSlideHeadersFooters(); + if (hdd.isFooterVisible()) { + String footerText = hdd.getFooterText(); + } + + // per-slide headers / footers + for (HSLFSlide slide : ppt.getSlides()) { + HeadersFooters hdd2 = slide.getHeadersFooters(); + if (hdd2.isFooterVisible()) { + String footerText = hdd2.getFooterText(); + } + if (hdd2.isUserDateVisible()) { + String customDate = hdd2.getDateTimeText(); + } + if (hdd2.isSlideNumberVisible()) { + int slideNUm = slide.getSlideNumber(); + } + } + </source> + </section> + <section><title>How to set Headers / Footers</title> + <source> + HSLFSlideShow ppt = new HSLFSlideShow(); + + // presentation-scope headers / footers + HeadersFooters hdd = ppt.getSlideHeadersFooters(); + hdd.setSlideNumberVisible(true); + hdd.setFootersText("Created by POI-HSLF"); + </source> + </section> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/slideshow/index.xml b/src/documentation/content/xdocs/components/slideshow/index.xml new file mode 100644 index 0000000000..b963d928a7 --- /dev/null +++ b/src/documentation/content/xdocs/components/slideshow/index.xml @@ -0,0 +1,72 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>POI-HSLF and and POI-XLSF - Java API To Access Microsoft Powerpoint Format Files</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Avik Sengupta" email="avik at apache dot org"/> + <person name="Nick Burch" email="nick at apache dot org"/> + <person name="Yegor Kozlov" email="yegor at apache dot org"/> + </authors> + </header> + + <body> + <section> + <title>POI-HSLF</title> + + <p>HSLF is the POI Project's pure Java implementation of the Powerpoint '97(-2007) file format. </p> + <p>HSLF provides a way to read, create or modify PowerPoint presentations. In particular, it provides: + </p> + <ul> + <li>api for data extraction (text, pictures, embedded objects, sounds)</li> + <li>usermodel api for creating, reading and modifying ppt files</li> + </ul> + <note> + This code currently lives the + <a href="https://github.com/apache/poi/tree/trunk/poi-scratchpad/">scratchpad area</a> + of the POI Git repository. To use this component, ensure + you have the Scratchpad Jar on your classpath, or a dependency + defined on the <em>poi-scratchpad</em> artifact - the main POI + jar is not enough! See the + <a href="site:components">POI Components Map</a> + for more details. + </note> + <p>The <a href="./quick-guide.html">quick guide</a> documentation provides + information on using this API. Comments and fixes gratefully accepted on the POI + dev mailing lists.</p> + </section> + <section> + <title>POI-XSLF</title> + <p> + XSLF is the POI Project's pure Java implementation of the PowerPoint 2007 OOXML (.xlsx) file format. + Whilst HSLF and XSLF provide similar features, there is not a common interface across the two of them at this time. + </p> + <p> + Please note that XSLF is still in early development and is a subject to incompatible changes in future. + </p> + <p> + A quick guide is available in the <a href="./xslf-cookbook.html">XSLF Cookbook</a> + </p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/slideshow/ppt-file-format.xml b/src/documentation/content/xdocs/components/slideshow/ppt-file-format.xml new file mode 100644 index 0000000000..202df1d436 --- /dev/null +++ b/src/documentation/content/xdocs/components/slideshow/ppt-file-format.xml @@ -0,0 +1,367 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>POI-HSLF - A Guide to the PowerPoint File Format</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Nick Burch" email="nick at torchbox dot com"/> + <person name="Yegor Kozlov" email="yegor at dinom dot ru"/> + </authors> + </header> + + <body> + <section><title>Records, Containers and Atoms</title> + <p> + PowerPoint documents are made up of a tree of records. A record may + contain either other records (in which case it is a Container), + or data (in which case it's an Atom). A record can't hold both. + </p> + <p> + PowerPoint documents don't have one overall container record. Instead, + there are a number of different container records to be found at + the top level. + </p> + <p> + Any numbers or strings stored in the records are always stored in + Little Endian format (least important bytes first). This is the case + no matter what platform the file was written on - be that a + Little Endian or a Big Endian system. + </p> + <p> + PowerPoint may have Escher (DDF) records embedded in it. These + are always held as the children of a PPDrawing record (record + type 1036). Escher records have the same format as PowerPoint + records. + </p> + </section> + + <section><title>Record Headers</title> + <p> + All records, be they containers or atoms, have the same standard + 8 byte header. It is: + </p> + <ul><li>1/2 byte container flag</li> + <li>1.5 byte option field</li> + <li>2 byte record type</li> + <li>4 byte record length</li></ul> + <p> + If the first byte of the header, BINARY_AND with 0x0f, is 0x0f, + then the record is a container. Otherwise, it's an atom. The rest + of the first two bytes are used to store the "options" for the + record. Most commonly, this is used to indicate the version of + the record, but the exact usage is record specific. + </p> + <p> + The record type is a little endian number, which tells you what + kind of record you're dealing with. Each different kind of record + has its own value that gets stored here. PowerPoint records have + a type that's normally less than 6000 (decimal). Escher records + normally have a type between 0xF000 and 0xF1FF. + </p> + <p> + The record length is another little endian number. For an atom, + it's the size of the data part of the record, i.e. the length + of the record <em>less</em> its 8 byte record header. For a + container, it's the size of all the records that are children of + this record. That means that the size of a container record is the + length, plus 8 bytes for its record header. + </p> + </section> + + <section><title>CurrentUserAtom, UserEditAtom and PersistPtrIncrementalBlock</title> + <p><strong>aka Records that care about the byte level position of other records</strong></p> + <p> + A small number of records contain byte level position offsets to other + records. If you change the position of any records in the file, then + there's a good chance that you will need to update some of these + special records. + </p> + <p> + First up, CurrentUserAtom. This is actually stored in a different + OLE2 (POIFS) stream to the main PowerPoint document. It contains + a few bits of information on who lasted edited the file. Most + importantly, at byte 8 of its contents, it stores (as a 32 bit + little endian number) the offset in the main stream to the most + recent UserEditAtom. + </p> + <p> + The UserEditAtom contains two byte level offsets (again as 32 bit + little endian numbers). At byte 12 is the offset to the + PersistPtrIncrementalBlock associated with this UserEditAtom + (each UserEditAtom has one and only one PersistPtrIncrementalBlock). + At byte 8, there's the offset to the previous UserEditAtom. If this + is 0, then you're at the first one. + </p> + <p> + Every time you do a non full save in PowerPoint, it tacks on another + UserEditAtom and another PersistPtrIncrementalBlock. The + CurrentUserAtom is updated to point to this new UserEditAtom, and the + new UserEditAtom points back to the previous UserEditAtom. You then + end up with a chain, starting from the CurrentUserAtom, linking + back through all the UserEditAtoms, until you reach the first one + from a full save. + </p> +<source> +/-------------------------------\ +| CurrentUserAtom (own stream) | +| OffsetToCurrentEdit = 10562 |==\ +\-------------------------------/ | + | +/==================================/ +| /-----------------------------------\ +| | PersistPtrIncrementalBlock @ 6144 | +| \-----------------------------------/ +| /---------------------------------\ | +| | UserEditAtom @ 6176 | | +| | LastUserEditAtomOffset = 0 | | +| | PersistPointersOffset = 6144 |==================/ +| \---------------------------------/ +| | /-----------------------------------\ +| \====================\ | PersistPtrIncrementalBlock @ 8646 | +| | \-----------------------------------/ +| /---------------------------------\ | | +| | UserEditAtom @ 8674 | | | +| | LastUserEditAtomOffset = 6176 |=/ | +| | PersistPointersOffset = 8646 |==================/ +| \---------------------------------/ +| | /------------------------------------\ +| \====================\ | PersistPtrIncrementalBlock @ 10538 | +| | \------------------------------------/ +| /---------------------------------\ | | +\==| UserEditAtom @ 10562 | | | + | LastUserEditAtomOffset = 8674 |=/ | + | PersistPointersOffset = 10538 |==================/ + \---------------------------------/ +</source> + <p> + The PersistPtrIncrementalBlock contains byte offsets to all the + Slides, Notes, Documents and MasterSlides in the file. The first + PersistPtrIncrementalBlock will point to all the ones that + were present the first time the file was saved. Subsequent + PersistPtrIncrementalBlocks will contain pointers to all the ones + that were changed in that edit. To find the offset to a given + sheet in the latest version, then start with the most recent + PersistPtrIncrementalBlock. If this knows about the sheet, use the + offset it has. If it doesn't, then work back through older + PersistPtrIncrementalBlocks until you find one which does, and + use that. + </p> + <p> + Each PersistPtrIncrementalBlock can contain a number of entries + blocks. Each block holds information on a sequence of sheets. + Each block starts with a 32 bit little endian integer. Once read + into memory, the lower 20 bits contain the starting number for the + sequence of sheets to be described. The higher 12 bits contain + the count of the number of sheets described. Following that is + one 32 bit little endian integer for each sheet in the sequence, + the value being the offset to that sheet. If there is any data + left after parsing a block, then it corresponds to the next block. + </p> +<source> +hex on disk decimal description +----------- ------- ----------- +0000 0 No options +7217 6002 Record type is 6002 +2000 0000 32 Length of data is 32 bytes +0100 5000 5242881 Count is 5 (12 highest bits) + Starting number is 1 (20 lowest bits) +0000 0000 0 Sheet (1+0)=1 starts at offset 0 +900D 0000 3472 Sheet (1+1)=2 starts at offset 3472 +E403 0000 996 Sheet (1+2)=3 starts at offset 996 +9213 0000 5010 Sheet (1+3)=4 starts at offset 5010 +BE15 0000 5566 Sheet (1+4)=5 starts at offset 5566 +0900 1000 1048585 Count is 1 (12 highest bits) + Starting number is 9 (20 lowest bits) +4418 0000 6212 Sheet (9+0)=9 starts at offset 9212 +</source> + </section> + + <section><title>Paragraph and Text Styling</title> + <p> + There are quite a number of records that affect the styling + of text, and a smaller number that are responsible for the + styling of paragraphs. + </p> + <p> + By default, a given set of text will inherit paragraph and text + stylings from the appropriate master sheet. If anything differs + from the master sheet, then appropriate styling records will + follow the text record. + </p> + <p> + <em>(We don't currently know enough about master sheet styling + to write about it)</em> + </p> + <p> + Normally, powerpoint will have one text record (TextBytesAtom + or TextCharsAtom) for every paragraph, with a preceding + TextHeaderAtom to describe what sort of paragraph it is. + If any of the stylings differ from the master's, then a + StyleTextPropAtom will follow the text record. This contains + the paragraph style information, and the styling information + for each section of the text which has a different style. + (More on StyleTextPropAtom later) + </p> + <p> + For every font used, a FontEntityAtom must exist for that font. + The FontEntityAtoms live inside a FontCollection record, and + there's one of those inside Environment record inside the + Document record. <em>(More on Fonts to be discovered)</em> + </p> + </section> + + <section><title>StyleTextPropAtom</title> + <p> + If the text or paragraph stylings for a given text record + differ from those of the appropriate master, then there will + be one of these records. + </p> + <p> + This record is made up of two lists of lists. Firstly, + there's a list of paragraph stylings - each made up of the + number of characters it applies two, followed by the matching + styling elements. Following that is the equivalent for + character stylings. + </p> + <p> + Each styling list (in either list) starts with the number + of characters it applies to, stored in a 2 byte little + endian number. If it is a paragraph styling, it will be + followed by a 2 byte number (of unknown use). After this is + a four byte number, which is a mask indicating which stylings + will follow. You then have an entry for each of the stylings + indicated in the mask. Finally, you move onto the next set + of stylings. + </p> + <p> + Each styling has a specific mask flag to indicate its + presence. (The list may be found towards the top of + org.apache.poi.hslf.record.StyleTextPropAtom.java, and is + too long to sensibly include here). For each styling entry + will occur in the order of its mask value (so one with mask + 1 will come first, followed by the next highest mask value). + Depending on the styling, it is either made up of a 2 byte + or 4 byte numeric value. The meaning of the value will + depend on the styling (eg for font.size, it is the font + size in points). + </p> + <p> + Some stylings are actually mask stylings. For these, the + value will be a 4 byte number. This is then processed as + mask, to indicate a number of different sub-stylings. + The styling for bold/italic/underline is one such example. + </p> +<source> +hex on disk decimal description +----------- ------- ----------- + +0000 0 No options +A10F 4001 Record type is 4001 +8000 0000 128 Length of data is 128 bytes +1E00 0000 30 The paragraph styling applies to 30 characters +0000 0 Paragraph options are 0 +0018 0000 6144 0x0800=Text Alignment, 0x1000=Line Spacing +0000 0 Text Alignment = Left +5000 80 Line Spacing = 80 + +1C00 0000 28 The paragraph styling applies to 28 characters +0000 0 Paragraph options are 0 +0010 0000 4096 0x1000=Line Spacing +5000 80 Line Spacing = 80 + +1900 0000 25 The paragraph styling applies to 25 characters +0000 0 Paragraph options are 0 +0018 0000 6144 0x0800=Text Alignment, 0x1000=Line Spacing +0200 0 Text Alignment = Right +5000 80 Line Spacing = 80 + +6100 0000 61 The paragraph styling applies to 61 characters + (includes final CR) +0000 0 Paragraph options are 0 +0018 0000 6144 0x0800=Text Alignment, 0x1000=Line Spacing +0000 0 Text Alignment = Left +5000 80 Line Spacing = 80 + +1E00 0000 30 The character styling applies to 30 characters +0100 0200 131073 0x0001=Char Props Mask, 0x20000=Font Size +0100 1 Char Props 0x0001=Bold +1400 20 Font Size = 20 + +1C00 0000 28 The character styling applies to 28 characters +0200 0600 393218 0x0002=Char Props Mask, 0x20000=Font Size, 0x40000=Font Color +0200 2 Char Props 0x0002=Italic +1400 20 Font Size = 20 +0000 0005 83886080 Blue + +1900 0000 25 The character styling applies to 25 characters +0000 0600 393216 0x20000=Font Size, 0x40000=Font Color +1400 20 Font Size = 20 +FF33 00FE 4261426175 Red + +6000 0000 96 The character styling applies to 96 characters +0400 0300 196612 0x0004=Char Props Mask, 0x10000=Font Index, 0x20000=Font Size +0400 4 Char Props 0x0004=Underlined +0100 1 Font Index = 1 (2nd Font in table) +1800 24 Font Size = 24 +</source> + </section> + + <section><title>Fonts in PowerPoint</title> + <p> + PowerPoint stores information about the fonts used in FontEntityAtoms, + which live inside Document.Environment.FontCollection. For every different + font used, a FontEntityAtom must exist for that font. There is always at + least one FontEntityAtom in Document.Environment.FontCollection, + which describes the default font. + </p> + </section> + + <section><title>FontEntityAtom</title> + <p> + The instance field of the record header contains the zero based index of the + font. Font index entries in StyleTextPropAtoms will refer to their required + font via this index. + </p> + <p> + The length of FontEntityAtoms is always 68 bytes. The first 64 bytes of + it hold the typeface name of the font to be used. This is stored as + a null-terminated string, and encoded as little endian unicode. (The + length of the string must not exceed 32 characters including the null + termination, so the typeface name cannot exceed 31 characters). + </p> + + <p> + After the typeface name there are 4 bytes of bitmask flags. The details of these + can be found in the Windows API, under the LOGFONT structure. + The 65th byte is the output precision, which defines how closely the system chosen + font must match the requested font, in terms of height, width, pitch etc. + The 66th byte is the clipping precision, which defines how to clip characters + that occur partly outside the clipping region. + The 67th byte is the output quality, which defines how closely the system + must match the logical font's attributes to those of the physical font used. + The 68th (and final) byte is the pitch and family, which is used by the + system when matching fonts. + </p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/slideshow/ppt-wmf-emf-renderer.xml b/src/documentation/content/xdocs/components/slideshow/ppt-wmf-emf-renderer.xml new file mode 100644 index 0000000000..7421db5733 --- /dev/null +++ b/src/documentation/content/xdocs/components/slideshow/ppt-wmf-emf-renderer.xml @@ -0,0 +1,209 @@ +<?xml version="1.0" encoding="UTF-8"?><!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Rendering slideshows, WMF, EMF and EMF+</title> + </header> + <body> + <note>Please be aware, that the documentation on this page reflects the current development, which might not + have been released. If you rely on an unreleased feature, either use a + <a href="site:download">nightly development build</a> or feel free to ask on the + <a href="site:mailinglists">mailing list</a> for the release schedule.</note> + <section> + <title>Rendering slideshows, WMF, EMF and EMF+</title> + <p> + For rendering slideshow (HSLF/XSLF), WMF, EMF and EMF+ pictures, POI provides an utility class + <a href="https://github.com/apache/poi/tree/trunk/poi-ooxml/src/main/java/org/apache/poi/xslf/util/PPTX2PNG.java?view=markup"> + PPTX2PNG</a>: + </p> + + <source><![CDATA[ + Usage: PPTX2PNG [options] <.ppt/.pptx/.emf/.wmf file or 'stdin'> + + Options: + -scale <float> scale factor + -fixSide <side> specify side (long,short,width,height) to fix - use <scale> as amount of pixels + -slide <integer> 1-based index of a slide to render + -format <type> png,gif,jpg,svg,pdf (log,null for testing) + -outdir <dir> output directory, defaults to origin of the ppt/pptx file + -outfile <file> output filename, defaults to "${basename}-${slideno}.${format}" + -outpat <pattern> output filename pattern, defaults to "${basename}-${slideno}.${format}" + patterns: basename, slideno, format, ext + -dump <file> dump the annotated records to a file + -quiet do not write to console (for normal processing) + -ignoreParse ignore parsing error and continue with the records read until the error + -extractEmbedded extract embedded parts + -inputType <type> default input file type (OLE2,WMF,EMF), default is OLE2 = Powerpoint + some files (usually wmf) don't have a header, i.e. an identifiable file magic + -textAsShapes text elements are saved as shapes in SVG, necessary for variable spacing + often found in math formulas + -charset <cs> sets the default charset to be used, defaults to Windows-1252 + -emfHeaderBounds force the usage of the emf header bounds to calculate the bounding box + + -fontdir <dir> (PDF only) font directories separated by ";" - use $HOME for current users home dir + defaults to the usual plattform directories + -fontTtf <regex> (PDF only) regex to match the .ttf filenames + -fontMap <map> ";"-separated list of font mappings <typeface from>:<typeface to> + ]]> + </source> + + <section> + <title>Instructions to run</title> + <p> + Download the <a href="https://ci-builds.apache.org/job/POI/job/POI-DSL-1.8/lastSuccessfulBuild/artifact/build/dist/">current nightly</a> + and for SVG/PDF the <a href="site:components/index/batikpdf">additional dependencies</a>.</p> + <p>Execute the java command (Unix-paths needs to be replaced for Windows - use "-charset" for non-western WMF/EMFs):</p> + <source> + java -cp poi-5.4.1.jar:poi-ooxml-5.4.1.jar:poi-ooxml-lite-5.4.1.jar:poi-scratchpad-5.4.1.jar:lib/*:ooxml-lib/*:auxiliary/* org.apache.poi.xslf.util.PPTX2PNG -format png -fixside long -scale 1000 -charset GBK file.pptx + </source> + <p> + If you want to use the renderer on the module path (JPMS) there a currently a few more steps necessary: + </p> + <ul> + <li>Create a build project using Maven, Gradle or your favorite build tool.</li> + <li>Alternatively, download the jars from https://repo1.maven.org/maven2/org/apache/poi/</li> + <li>Exclude poi-ooxml-full-5.4.1.jar,poi-javadoc-5.4.1.jar and auxiliary/xml-apis-1.4.01.jar (Java 11+) into new subdirectory "unused"</li> + <li>Move all other jars in current directory into a new subdirectory "poi"</li> + <li>Invoke PPTX2PNG: + <source> + java --module-path poi:lib:auxiliary:ooxml-lib --module org.apache.poi.ooxml/org.apache.poi.xslf.util.PPTX2PNG -format png -fixside long -scale 1000 file.pptx + </source> + </li> + </ul> + <note> + JDK 1.8 is by default using the PiscesRenderingEngine and affected by + <a href="https://github.com/AdoptOpenJDK/openjdk-build/issues/716">Busy loop hangs</a>. + To workaround this, use the MarlinRenderingEngine which is experimental provided starting from + <a href="https://bugs.java.com/bugdatabase/view_bug.do?bug_id=8143849">openjdk8u252 (JDK-8143849)</a> + via <code>-Dsun.java2d.renderer=sun.java2d.marlin.MarlinRenderingEngine</code> or for older jdk builds, + <a href="https://github.com/bourgesl/marlin-renderer/wiki/How-to-use">preload the marlin jar</a>. + </note> + </section> + + </section> + <section> + <title>Integrate rendering in your code</title> + <section> + <title>#1 - Use PPTX2PNG via file or stdin</title> + <p>For file system access, you need to save your slideshow/WMF/EMF/EMF+ first to disc and then call <code> + PPTX2PNG.main() + </code> with the corresponding parameters. + </p> + + <p>for stdin access, you need to redirect <code>System.in</code> before: + </p> + <source><![CDATA[ + /* the file content */ + InputStream is = ...; + /* Save and set System.in */ + InputStream oldIn = System.in; + try { + System.setIn(is); + + String[] args = { + "-format", "png", // png,gif,jpg,svg or null for test + "-outdir", new File("out/").getCanonicalPath(), + "-outfile", "export.png", + "-fixside", "long", + "-scale", "800", + "-ignoreParse", + "stdin" + }; + PPTX2PNG.main(args); + + } finally { + System.setIn(oldIn); + } + ]]></source> + </section> + <section> + <title>#2 - Render WMF / EMF / EMF+ via the *Picture classes</title> + <source><![CDATA[ + File f = samples.getFile("santa.wmf"); + try (FileInputStream fis = new FileInputStream(f)) { + // for WMF + HwmfPicture wmf = new HwmfPicture(fis); + + // for EMF / EMF+ + HemfPicture emf = new HemfPicture(fis); + + Dimension dim = wmf.getSize(); + int width = Units.pointsToPixel(dim.getWidth()); + // keep aspect ratio for height + int height = Units.pointsToPixel(dim.getHeight()); + double max = Math.max(width, height); + if (max > 1500) { + width *= 1500/max; + height *= 1500/max; + } + + BufferedImage bufImg = new BufferedImage(width, height, BufferedImage.TYPE_INT_ARGB); + Graphics2D g = bufImg.createGraphics(); + g.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON); + g.setRenderingHint(RenderingHints.KEY_RENDERING, RenderingHints.VALUE_RENDER_QUALITY); + g.setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BICUBIC); + g.setRenderingHint(RenderingHints.KEY_FRACTIONALMETRICS, RenderingHints.VALUE_FRACTIONALMETRICS_ON); + + wmf.draw(g, new Rectangle2D.Double(0,0,width,height)); + + g.dispose(); + + ImageIO.write(bufImg, "PNG", new File("bla.png")); + } + ]]> + </source> + </section> + <section> + <title>#3 - Render slideshows directly</title> + <source><![CDATA[ + File file = new File("example.pptx"); + double scale = 1.5; + try (SlideShow<?, ?> ss = SlideShowFactory.create(file, null, true)) { + Dimension pgsize = ss.getPageSize(); + int width = (int) (pgsize.width * scale); + int height = (int) (pgsize.height * scale); + + for (Slide<?, ?> slide : ss.getSlides()) { + BufferedImage img = new BufferedImage(width, height, BufferedImage.TYPE_INT_ARGB); + Graphics2D graphics = img.createGraphics(); + + // default rendering options + graphics.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON); + graphics.setRenderingHint(RenderingHints.KEY_RENDERING, RenderingHints.VALUE_RENDER_QUALITY); + graphics.setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BICUBIC); + graphics.setRenderingHint(RenderingHints.KEY_FRACTIONALMETRICS, RenderingHints.VALUE_FRACTIONALMETRICS_ON); + graphics.setRenderingHint(Drawable.BUFFERED_IMAGE, new WeakReference<>(img)); + + graphics.scale(scale, scale); + + // draw stuff + slide.draw(graphics); + + ImageIO.write(img, "PNG", new File("output.png")); + graphics.dispose(); + img.flush(); + } + } + ]]></source> + </section> + </section> + </body> +</document>
\ No newline at end of file diff --git a/src/documentation/content/xdocs/components/slideshow/quick-guide.xml b/src/documentation/content/xdocs/components/slideshow/quick-guide.xml new file mode 100644 index 0000000000..88d85d877c --- /dev/null +++ b/src/documentation/content/xdocs/components/slideshow/quick-guide.xml @@ -0,0 +1,133 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>POI-HSLF - A Quick Guide</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Nick Burch" email="nick at torchbox dot com"/> + </authors> + </header> + + <body> + <section><title>Basic Text Extraction</title> + <p>For basic text extraction, make use of + <code>org.apache.poi.sl.extractor.SlideShowExtractor</code>. + It accepts a slideshow which can be created from a file or stream via <code>org.apache.poi.sl.usermodel.SlideShowFactory</code>. + The <code>getText()</code> method can be used to get the text from the slides. + </p> + </section> + + <section><title>Specific Text Extraction</title> + <p>To get specific bits of text, first create a <code>org.apache.poi.hslf.usermodel.HSLFSlideShow</code> +(from a <code>org.apache.poi.hslf.usermodel.HSLFSlideShowImpl</code>, which accepts a file or an input +stream). Use <code>getSlides()</code> and <code>getNotes()</code> to get the slides and notes. +These can be queried to get their page ID (though they should be returned +in the right order).</p> + <p>You can then call <code>getTextParagraphs()</code> on these, to get +their blocks of text. (A list of <code>HSLFTextParagraph</code> normally holds all the text in a +given area of the page, eg in the title bar, or in a box). +From the <code>HSLFTextParagraph</code>, you can extract the text, and check +what type of text it is (eg Body, Title). You can also call +<code>getTextRuns()</code>, which will return the +<code>HSLFTextRun</code>s that make up the <code>TextParagraph</code>. A +<code>HSLFTextRun</code> is a text fragment, having the same character formatting. +The paragraph formatting is defined in the parent <code>HSLFTextParagraph</code>. + </p> + </section> + + <section><title>Poor Quality Text Extraction</title> + <p>If speed is the most important thing for you, you don't care + about getting duplicate blocks of text, you don't care about + getting text from master sheets, and you don't care about getting + old text, then + <code>org.apache.poi.hslf.extractor.QuickButCruddyTextExtractor</code> + might be of use.</p> + <p>QuickButCruddyTextExtractor doesn't use the normal record + parsing code, instead it uses a tree structure blind search + method to get all text holding records. You will get all the text, + including lots of text you normally wouldn't ever want. However, + you will get it back very very fast!</p> + <p>There are two ways of getting the text back. + <code>getTextAsString()</code> will return a single string with all + the text in it. <code>getTextAsVector()</code> will return a + vector of strings, one for each text record found in the file. + </p> + </section> + + <section><title>Changing Text</title> + <p>It is possible to change the text via + <code>HSLFTextParagraph.setText(List<HSLFTextParagraph>,String)</code> or + <code>HSLFTextRun.setText(String)</code>. It is possible to add additional TextRuns + with <code>HSLFTextParagraph.appendText(List<HSLFTextParagraph>,String,boolean)</code> + or <code>HSLFTextParagraph.addTextRun(HSLFTextRun)</code></p> + <p>When calling <code>HSLFTextParagraph.setText(List<HSLFTextParagraph>,String)</code>, all + the text will end up with the same formatting. When calling + <code>HSLFTextRun.setText(String)</code>, the text will retain + the old formatting of that <code>HSLFTextRun</code>. + </p> + </section> + + <section><title>Adding Slides</title> + <p>You may add new slides by calling + <code>HSLFSlideShow.createSlide()</code>, which will add a new slide + to the end of the SlideShow. It is possible to re-order slides with <code>HSLFSlideShow.reorderSlide(...)</code>. + </p> + </section> + + <section><title>Guide to key classes</title> + <ul> + <li><code>org.apache.poi.hslf.usermodel.HSLFSlideShowImpl</code> + Handles reading in and writing out files. Calls + <code>org.apache.poi.hslf.record.record</code> to build a tree + of all the records in the file, which it allows access to. + </li> + <li><code>org.apache.poi.hslf.record.Record</code> + Base class of all records. Also provides the main record generation + code, which will build up a tree of records for a file. + </li> + <li><code>org.apache.poi.hslf.usermodel.HSLFSlideShow</code> + Builds up model entries from the records, and presents a user facing + view of the file + </li> + <li><code>org.apache.poi.hslf.usermodel.HSLFSlide</code> + A user facing view of a Slide in a slideshow. Allows you to get at the + Text of the slide, and at any drawing objects on it. + </li> + <li><code>org.apache.poi.hslf.usermodel.HSLFTextParagraph</code> + A list of <code>HSLFTextParagraph</code>s holds all the text in a given area of the Slide, and will + contain one or more <code>HSLFTextRun</code>s. + </li> + <li><code>org.apache.poi.hslf.usermodel.HSLFTextRun</code> + Holds a run of text, all having the same character stylings. It is possible to modify text, and/or text stylings. + </li> + <li><code>org.apache.poi.sl.extractor.SlideShowExtractor</code> + Uses the model code to allow extraction of text from files + </li> + <li><code>org.apache.poi.hslf.extractor.QuickButCruddyTextExtractor</code> + Uses the record code to extract all the text from files very fast, + but including deleted text (and other bits of Crud). + </li> + </ul> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/slideshow/xslf-cookbook.xml b/src/documentation/content/xdocs/components/slideshow/xslf-cookbook.xml new file mode 100644 index 0000000000..4f72295b5f --- /dev/null +++ b/src/documentation/content/xdocs/components/slideshow/xslf-cookbook.xml @@ -0,0 +1,304 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>XSLF Cookbook</title> + <authors> + <person email="yegor@apache.org" name="Yegor Kozlov" id="YK"/> + </authors> + </header> + <body> + <section><title>XSLF Cookbook</title> + <p> + This page offers a short introduction into the XSLF API. More examples can be found in the + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xslf/">XSLF Examples</a> + in the POI Git repository. + </p> + <note> + Please note that XSLF is still in early development and is a subject to incompatible changes in a future release. + </note> + <section><title>Index of Features</title> + <ul> + <li><a href="#NewPresentation">Create a new presentation</a></li> + <li><a href="#ReadPresentation">Read an existing presentation</a></li> + <li><a href="#SlideLayout">Create a slide with a predefined layout</a></li> + <li><a href="#DeleteSlide">Delete slide</a></li> + <li><a href="#MoveSlide">Re-order slides</a></li> + <li><a href="#SlideSize">Change slide size</a></li> + <li><a href="#GetShapes">Read shapes</a></li> + <li><a href="#AddImage">Add image</a></li> + <li><a href="#ReadImages">Read images contained in a presentation</a></li> + <li><a href="#Text">Format text</a></li> + <li><a href="#Hyperlinks">Hyperlinks</a></li> + <li><a href="#PPTX2PNG">Convert .pptx slides into images</a></li> + <li><a href="#Merge">Merge multiple presentations together</a></li> + </ul> + </section> + <section><title>Cookbook</title> + <anchor id="NewPresentation"/> + <section><title>New Presentation</title> + <p> + The following code creates a new .pptx slide show and adds a blank slide to it: + </p> + <source> + //create a new empty slide show + XMLSlideShow ppt = new XMLSlideShow(); + + //add first slide + XSLFSlide blankSlide = ppt.createSlide(); + </source> + </section> + <anchor id="ReadPresentation"/> + <section><title>Read an existing presentation and append a slide to it</title> + <source> + XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx")); + + //append a new slide to the end + XSLFSlide blankSlide = ppt.createSlide(); + </source> + </section> + + <anchor id="SlideLayout"/> + <section><title>Create a new slide from a predefined slide layout</title> + <source> + XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx")); + + // first see what slide layouts are available : + System.out.println("Available slide layouts:"); + for(XSLFSlideMaster master : ppt.getSlideMasters()){ + for(XSLFSlideLayout layout : master.getSlideLayouts()){ + System.out.println(layout.getType()); + } + } + + // blank slide + XSLFSlide blankSlide = ppt.createSlide(); + + // there can be multiple masters each referencing a number of layouts + // for demonstration purposes we use the first (default) slide master + XSLFSlideMaster defaultMaster = ppt.getSlideMasters().get(0); + + // title slide + XSLFSlideLayout titleLayout = defaultMaster.getLayout(SlideLayout.TITLE); + // fill the placeholders + XSLFSlide slide1 = ppt.createSlide(titleLayout); + XSLFTextShape title1 = slide1.getPlaceholder(0); + title1.setText("First Title"); + + // title and content + XSLFSlideLayout titleBodyLayout = defaultMaster.getLayout(SlideLayout.TITLE_AND_CONTENT); + XSLFSlide slide2 = ppt.createSlide(titleBodyLayout); + + XSLFTextShape title2 = slide2.getPlaceholder(0); + title2.setText("Second Title"); + + XSLFTextShape body2 = slide2.getPlaceholder(1); + body2.clearText(); // unset any existing text + body2.addNewTextParagraph().addNewTextRun().setText("First paragraph"); + body2.addNewTextParagraph().addNewTextRun().setText("Second paragraph"); + body2.addNewTextParagraph().addNewTextRun().setText("Third paragraph"); + </source> + </section> + + <anchor id="DeleteSlide"/> + <section><title>Delete slide</title> + <source> + XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx")); + + ppt.removeSlide(0); // 0-based index of a slide to be removed + </source> + </section> + + <anchor id="MoveSlide"/> + <section><title>Re-order slides</title> + <source> + XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx")); + List<XSLFSlide> slides = ppt.getSlides(); + + XSLFSlide thirdSlide = slides.get(2); + ppt.setSlideOrder(thirdSlide, 0); // move the third slide to the beginning + </source> + </section> + + <anchor id="SlideSize"/> + <section><title>How to retrieve or change slide size</title> + <source> + XMLSlideShow ppt = new XMLSlideShow(); + //retrieve page size. Coordinates are expressed in points (72 dpi) + java.awt.Dimension pgsize = ppt.getPageSize(); + int pgx = pgsize.width; //slide width in points + int pgy = pgsize.height; //slide height in points + + //set new page size + ppt.setPageSize(new java.awt.Dimension(1024, 768)); + </source> + </section> + <anchor id="GetShapes"/> + <section><title>How to read shapes contained in a particular slide</title> + <p> + The following code demonstrates how to iterate over shapes for each slide. + </p> + <source> + XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx")); + // get slides + for (XSLFSlide slide : ppt.getSlides()) { + for (XSLFShape sh : slide.getShapes()) { + // name of the shape + String name = sh.getShapeName(); + + // shapes's anchor which defines the position of this shape in the slide + if (sh instanceof PlaceableShape) { + java.awt.geom.Rectangle2D anchor = ((PlaceableShape)sh).getAnchor(); + } + + if (sh instanceof XSLFConnectorShape) { + XSLFConnectorShape line = (XSLFConnectorShape) sh; + // work with Line + } else if (sh instanceof XSLFTextShape) { + XSLFTextShape shape = (XSLFTextShape) sh; + // work with a shape that can hold text + } else if (sh instanceof XSLFPictureShape) { + XSLFPictureShape shape = (XSLFPictureShape) sh; + // work with Picture + } + } + } + </source> + </section> + <anchor id="AddImage"/> + <section><title>Add Image to Slide</title> + <source> + XMLSlideShow ppt = new XMLSlideShow(); + XSLFSlide slide = ppt.createSlide(); + + byte[] pictureData = IOUtils.toByteArray(new FileInputStream("image.png")); + + XSLFPictureData pd = ppt.addPicture(pictureData, PictureData.PictureType.PNG); + XSLFPictureShape pic = slide.createPicture(pd); + </source> + </section> + + <anchor id="ReadImages"/> + <section><title>Read Images contained within a presentation</title> + <source> + XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx")); + for(XSLFPictureData data : ppt.getAllPictures()){ + byte[] bytes = data.getData(); + String fileName = data.getFileName(); + + } + </source> + </section> + + <anchor id="Text"/> + <section><title>Basic text formatting</title> + <source> + XMLSlideShow ppt = new XMLSlideShow(); + XSLFSlide slide = ppt.createSlide(); + + XSLFTextBox shape = slide.createTextBox(); + XSLFTextParagraph p = shape.addNewTextParagraph(); + + XSLFTextRun r1 = p.addNewTextRun(); + r1.setText("The"); + r1.setFontColor(Color.blue); + r1.setFontSize(24.); + + XSLFTextRun r2 = p.addNewTextRun(); + r2.setText(" quick"); + r2.setFontColor(Color.red); + r2.setBold(true); + + XSLFTextRun r3 = p.addNewTextRun(); + r3.setText(" brown"); + r3.setFontSize(12.); + r3.setItalic(true); + r3.setStrikethrough(true); + + XSLFTextRun r4 = p.addNewTextRun(); + r4.setText(" fox"); + r4.setUnderline(true); + </source> + </section> + <anchor id="Hyperlinks"/> + <section><title>How to create a hyperlink</title> + <source> + XMLSlideShow ppt = new XMLSlideShow(); + XSLFSlide slide = ppt.createSlide(); + + // assign a hyperlink to a text run + XSLFTextBox shape = slide.createTextBox(); + XSLFTextRun r = shape.addNewTextParagraph().addNewTextRun(); + r.setText("Apache POI"); + XSLFHyperlink link = r.createHyperlink(); + link.setAddress("https://poi.apache.org"); + </source> + </section> + <anchor id="PPTX2PNG"/> + <section><title>PPTX2PNG is an application that converts each slide of a .pptx slideshow into a PNG image</title> + <source> +Usage: PPTX2PNG [options] <pptx file> +Options: + -scale <float> scale factor (default is 1.0) + -slide <integer> 1-based index of a slide to render. Default is to render all slides. + </source> + <p>How it works:</p> + <p> + The XSLFSlide object implements a draw(Graphics2D graphics) method that recursively paints all shapes + in the slide into the supplied graphics canvas: + </p> + <source> + slide.draw(graphics); + </source> + <p> + where graphics is a class implementing java.awt.Graphics2D. In PPTX2PNG the graphic canvas is derived from + java.awt.image.BufferedImage, i.e. the destination is an image in memory, but in general case you can pass + any compliant implementation of java.awt.Graphics2D. + Find more information in the designated <a href="site:slrender">render page</a>, e.g. on how to render SVG images. + </p> + </section> + <anchor id="Merge"/> + <section> + <title>Merge multiple presentations together</title> + <source> + XMLSlideShow ppt = new XMLSlideShow(); + String[] inputs = {"presentations1.pptx", "presentation2.pptx"}; + for(String arg : inputs){ + FileInputStream is = new FileInputStream(arg); + XMLSlideShow src = new XMLSlideShow(is); + is.close(); + + for(XSLFSlide srcSlide : src.getSlides()){ + ppt.createSlide().importContent(srcSlide); + } + } + + FileOutputStream out = new FileOutputStream("merged.pptx"); + ppt.write(out); + out.close(); + </source> + </section> + + </section> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/chart.xml b/src/documentation/content/xdocs/components/spreadsheet/chart.xml new file mode 100644 index 0000000000..8e4194af9a --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/chart.xml @@ -0,0 +1,1532 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Chart record information</title> + <authors> + <person email="user@poi.apache.org" name="Glen Stampoultzis" id="GS"/> + </authors> + </header> + <body> + <section><title>Introduction</title> + <p> + This document is intended as a work in progress for describing + our current understanding of how the chart records are + written to produce a valid chart. + </p> + </section> + <section><title>Bar chart</title> + <p> + The following records detail the records written for a + 'simple' bar chart. + </p> + <source> + + ============================================ + rectype = 0xec, recsize = 0xc8 + -BEGIN DUMP--------------------------------- + 00000000 0F 00 02 F0 C0 00 00 00 10 00 08 F0 08 00 00 00 ................ + 00000010 02 00 00 00 02 04 00 00 0F 00 03 F0 A8 00 00 00 ................ + 00000020 0F 00 04 F0 28 00 00 00 01 00 09 F0 10 00 00 00 ....(........... + 00000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000040 02 00 0A F0 08 00 00 00 00 04 00 00 05 00 00 00 ................ + 00000050 0F 00 04 F0 70 00 00 00 92 0C 0A F0 08 00 00 00 ....p........... + 00000060 02 04 00 00 00 0A 00 00 93 00 0B F0 36 00 00 00 ............6... + 00000070 7F 00 04 01 04 01 BF 00 08 00 08 00 81 01 4E 00 ..............N. + 00000080 00 08 83 01 4D 00 00 08 BF 01 10 00 11 00 C0 01 ....M........... + 00000090 4D 00 00 08 FF 01 08 00 08 00 3F 02 00 00 02 00 M.........?..... + 000000A0 BF 03 00 00 08 00 00 00 10 F0 12 00 00 00 00 00 ................ + 000000B0 04 00 C0 02 0A 00 F4 00 0E 00 66 01 20 00 E9 00 ..........f. ... + 000000C0 00 00 11 F0 00 00 00 00 ........ + -END DUMP----------------------------------- + recordid = 0xec, size =200 + [UNKNOWN RECORD:ec] + .id = ec + [/UNKNOWN RECORD] + + ============================================ + rectype = 0x5d, recsize = 0x1a + -BEGIN DUMP--------------------------------- + 00000000 15 00 12 00 05 00 02 00 11 60 00 00 00 00 B8 03 .........`...... + 00000010 87 03 00 00 00 00 00 00 00 00 .......... + -END DUMP----------------------------------- + recordid = 0x5d, size =26 + [UNKNOWN RECORD:5d] + .id = 5d + [/UNKNOWN RECORD] + + ============================================ + rectype = 0x809, recsize = 0x10 + -BEGIN DUMP--------------------------------- + 00000000 00 06 20 00 FE 1C CD 07 C9 40 00 00 06 01 00 00 .. ......@...... + -END DUMP----------------------------------- + recordid = 0x809, size =16 + [BOF RECORD] + .version = 600 + .type = 20 + .build = 1cfe + .buildyear = 1997 + .history = 40c9 + .requiredversion = 106 + [/BOF RECORD] + + ============================================ + rectype = 0x14, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x14, size =0 + [HEADER] + .length = 0 + .header = null + [/HEADER] + + ============================================ + rectype = 0x15, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x15, size =0 + [FOOTER] + .footerlen = 0 + .footer = null + [/FOOTER] + + ============================================ + rectype = 0x83, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 00 00 .. + -END DUMP----------------------------------- + recordid = 0x83, size =2 + [HCENTER] + .hcenter = false + [/HCENTER] + + ============================================ + rectype = 0x84, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 00 00 .. + -END DUMP----------------------------------- + recordid = 0x84, size =2 + [VCENTER] + .vcenter = false + [/VCENTER] + + ============================================ + rectype = 0xa1, recsize = 0x22 + -BEGIN DUMP--------------------------------- + 00000000 00 00 12 00 01 00 01 00 01 00 04 00 00 00 B8 03 ................ + 00000010 00 00 00 00 00 00 E0 3F 00 00 00 00 00 00 E0 3F .......?.......? + 00000020 0F 00 .. + -END DUMP----------------------------------- + recordid = 0xa1, size =34 + [PRINTSETUP] + .papersize = 0 + .scale = 18 + .pagestart = 1 + .fitwidth = 1 + .fitheight = 1 + .options = 4 + .ltor = false + .landscape = false + .valid = true + .mono = false + .draft = false + .notes = false + .noOrientat = false + .usepage = false + .hresolution = 0 + .vresolution = 952 + .headermargin = 0.5 + .footermargin = 0.5 + .copies = 15 + [/PRINTSETUP] + + <!-- Comment to avoid forrest bug --> + ============================================ + rectype = 0x33, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 03 00 .. + -END DUMP----------------------------------- + recordid = 0x33, size =2 + [UNKNOWN RECORD:33] + .id = 33 + [/UNKNOWN RECORD] + + ============================================ + rectype = 0x1060, recsize = 0xa + -BEGIN DUMP--------------------------------- + 00000000 A0 23 08 16 C8 00 00 00 05 00 .#........ + -END DUMP----------------------------------- + recordid = 0x1060, size =10 + [FBI] + .xBasis = 0x23A0 (9120 ) + .yBasis = 0x1608 (5640 ) + .heightBasis = 0x00C8 (200 ) + .scale = 0x0000 (0 ) + .indexToFontTable = 0x0005 (5 ) + [/FBI] + + ============================================ + rectype = 0x1060, recsize = 0xa + -BEGIN DUMP--------------------------------- + 00000000 A0 23 08 16 C8 00 01 00 06 00 .#........ + -END DUMP----------------------------------- + recordid = 0x1060, size =10 + [FBI] + .xBasis = 0x23A0 (9120 ) + .yBasis = 0x1608 (5640 ) + .heightBasis = 0x00C8 (200 ) + .scale = 0x0001 (1 ) + .indexToFontTable = 0x0006 (6 ) + [/FBI] + + ============================================ + rectype = 0x12, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 00 00 .. + -END DUMP----------------------------------- + recordid = 0x12, size =2 + [PROTECT] + .rowheight = 0 + [/PROTECT] + + ============================================ + Offset 0xf22 (3874) + rectype = 0x1001, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 00 00 .. + -END DUMP----------------------------------- + recordid = 0x1001, size =2 + [UNITS] + .units = 0x0000 (0 ) + [/UNITS] + + ============================================ + Offset 0xf28 (3880) + rectype = 0x1002, recsize = 0x10 + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 00 00 00 00 58 66 D0 01 40 66 22 01 ........Xf..@f". + -END DUMP----------------------------------- + recordid = 0x1002, size =16 + [CHART] + .x = 0x00000000 (0 ) + .y = 0x00000000 (0 ) + .width = 0x01D06658 (30434904 ) + .height = 0x01226640 (19031616 ) + [/CHART] + + ============================================ + Offset 0xf3c (3900) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0xf40 (3904) + rectype = 0xa0, recsize = 0x4 + -BEGIN DUMP--------------------------------- + 00000000 01 00 01 00 .... + -END DUMP----------------------------------- + recordid = 0xa0, size =4 + [SCL] + .numerator = 0x0001 (1 ) + .denominator = 0x0001 (1 ) + [/SCL] + + <!-- Comment to avoid forrest bug --> + ============================================ + Offset 0xf48 (3912) + rectype = 0x1064, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 00 00 01 00 00 00 01 00 ........ + -END DUMP----------------------------------- + recordid = 0x1064, size =8 + [PLOTGROWTH] + .horizontalScale = 0x00010000 (65536 ) + .verticalScale = 0x00010000 (65536 ) + [/PLOTGROWTH] + + ============================================ + Offset 0xf54 (3924) + rectype = 0x1032, recsize = 0x4 + -BEGIN DUMP--------------------------------- + 00000000 00 00 02 00 .... + -END DUMP----------------------------------- + recordid = 0x1032, size =4 + [FRAME] + .borderType = 0x0000 (0 ) + .options = 0x0002 (2 ) + .autoSize = false + .autoPosition = true + [/FRAME] + + ============================================ + Offset 0xf5c (3932) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0xf60 (3936) + rectype = 0x1007, recsize = 0xc + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 00 00 FF FF 09 00 4D 00 ..........M. + -END DUMP----------------------------------- + recordid = 0x1007, size =12 + [LINEFORMAT] + .lineColor = 0x00000000 (0 ) + .linePattern = 0x0000 (0 ) + .weight = 0xFFFF (-1 ) + .format = 0x0009 (9 ) + .auto = true + .drawTicks = false + .unknown = false + .colourPaletteIndex = 0x004D (77 ) + [/LINEFORMAT] + + ============================================ + Offset 0xf70 (3952) + rectype = 0x100a, recsize = 0x10 + -BEGIN DUMP--------------------------------- + 00000000 FF FF FF 00 00 00 00 00 01 00 01 00 4E 00 4D 00 ............N.M. + -END DUMP----------------------------------- + recordid = 0x100a, size =16 + [AREAFORMAT] + .foregroundColor = 0x00FFFFFF (16777215 ) + .backgroundColor = 0x00000000 (0 ) + .pattern = 0x0001 (1 ) + .formatFlags = 0x0001 (1 ) + .automatic = true + .invert = false + .forecolorIndex = 0x004E (78 ) + .backcolorIndex = 0x004D (77 ) + [/AREAFORMAT] + + ============================================ + Offset 0xf84 (3972) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0xf88 (3976) + rectype = 0x1003, recsize = 0xc + -BEGIN DUMP--------------------------------- + 00000000 01 00 01 00 20 00 1F 00 01 00 00 00 .... ....... + -END DUMP----------------------------------- + recordid = 0x1003, size =12 + [SERIES] + .categoryDataType = 0x0001 (1 ) + .valuesDataType = 0x0001 (1 ) + .numCategories = 0x0020 (32 ) + .numValues = 0x001F (31 ) + .bubbleSeriesType = 0x0001 (1 ) + .numBubbleValues = 0x0000 (0 ) + [/SERIES] + + ============================================ + Offset 0xf98 (3992) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + <!-- Comment to avoid forrest bug --> + ============================================ + Offset 0xf9c (3996) + rectype = 0x1051, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 00 01 00 00 00 00 00 00 ........ + -END DUMP----------------------------------- + recordid = 0x1051, size =8 + [AI] + .linkType = 0x00 (0 ) + .referenceType = 0x01 (1 ) + .options = 0x0000 (0 ) + .customNumberFormat = false + .indexNumberFmtRecord = 0x0000 (0 ) + .formulaOfLink = (org.apache.poi.hssf.record.LinkedDataFormulaField@1ee3914 ) + [/AI] + + ============================================ + Offset 0xfa8 (4008) + rectype = 0x1051, recsize = 0x13 + -BEGIN DUMP--------------------------------- + 00000000 01 02 00 00 00 00 0B 00 3B 00 00 00 00 1E 00 01 ........;....... + 00000010 00 01 00 ... + -END DUMP----------------------------------- + recordid = 0x1051, size =19 + [AI] + .linkType = 0x01 (1 ) + .referenceType = 0x02 (2 ) + .options = 0x0000 (0 ) + .customNumberFormat = false + .indexNumberFmtRecord = 0x0000 (0 ) + .formulaOfLink = (org.apache.poi.hssf.record.LinkedDataFormulaField@e5855a ) + [/AI] + + ============================================ + Offset 0xfbf (4031) + rectype = 0x1051, recsize = 0x13 + -BEGIN DUMP--------------------------------- + 00000000 02 02 00 00 69 01 0B 00 3B 00 00 00 00 1F 00 00 ....i...;....... + 00000010 00 00 00 ... + -END DUMP----------------------------------- + recordid = 0x1051, size =19 + [AI] + .linkType = 0x02 (2 ) + .referenceType = 0x02 (2 ) + .options = 0x0000 (0 ) + .customNumberFormat = false + .indexNumberFmtRecord = 0x0169 (361 ) + .formulaOfLink = (org.apache.poi.hssf.record.LinkedDataFormulaField@95fd19 ) + [/AI] + + ============================================ + Offset 0xfd6 (4054) + rectype = 0x1051, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 03 01 00 00 00 00 00 00 ........ + -END DUMP----------------------------------- + recordid = 0x1051, size =8 + [AI] + .linkType = 0x03 (3 ) + .referenceType = 0x01 (1 ) + .options = 0x0000 (0 ) + .customNumberFormat = false + .indexNumberFmtRecord = 0x0000 (0 ) + .formulaOfLink = (org.apache.poi.hssf.record.LinkedDataFormulaField@11b9fb1 ) + [/AI] + + ============================================ + Offset 0xfe2 (4066) + rectype = 0x1006, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 FF FF 00 00 00 00 00 00 ........ + -END DUMP----------------------------------- + recordid = 0x1006, size =8 + [DATAFORMAT] + .pointNumber = 0xFFFF (-1 ) + .seriesIndex = 0x0000 (0 ) + .seriesNumber = 0x0000 (0 ) + .formatFlags = 0x0000 (0 ) + .useExcel4Colors = false + [/DATAFORMAT] + + ============================================ + Offset 0xfee (4078) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0xff2 (4082) + rectype = 0x105f, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 00 00 .. + -END DUMP----------------------------------- + recordid = 0x105f, size =2 + [UNKNOWN RECORD] + .id = 105f + [/UNKNOWN RECORD] + + ============================================ + Offset 0xff8 (4088) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0xffc (4092) + rectype = 0x1045, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 00 00 .. + -END DUMP----------------------------------- + recordid = 0x1045, size =2 + [SeriesToChartGroup] + .chartGroupIndex = 0x0000 (0 ) + [/SeriesToChartGroup] + + ============================================ + Offset 0x1002 (4098) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x1006 (4102) + rectype = 0x1044, recsize = 0x4 + -BEGIN DUMP--------------------------------- + 00000000 0A 00 00 00 .... + -END DUMP----------------------------------- + recordid = 0x1044, size =4 + [SHTPROPS] + .flags = 0x000A (10 ) + .chartTypeManuallyFormatted = false + .plotVisibleOnly = true + .doNotSizeWithWindow = false + .defaultPlotDimensions = true + .autoPlotArea = false + .empty = 0x00 (0 ) + [/SHTPROPS] + + ============================================ + Offset 0x100e (4110) + rectype = 0x1024, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 02 00 .. + -END DUMP----------------------------------- + recordid = 0x1024, size =2 + [DEFAULTTEXT] + .categoryDataType = 0x0002 (2 ) + [/DEFAULTTEXT] + + ============================================ + Offset 0x1014 (4116) + rectype = 0x1025, recsize = 0x20 + -BEGIN DUMP--------------------------------- + 00000000 02 02 01 00 00 00 00 00 DB FF FF FF C4 FF FF FF ................ + 00000010 00 00 00 00 00 00 00 00 B1 00 4D 00 50 2B 00 00 ..........M.P+.. + -END DUMP----------------------------------- + recordid = 0x1025, size =32 + [TEXT] + .horizontalAlignment = 0x02 (2 ) + .verticalAlignment = 0x02 (2 ) + .displayMode = 0x0001 (1 ) + .rgbColor = 0x00000000 (0 ) + .x = 0xFFFFFFDB (-37 ) + .y = 0xFFFFFFC4 (-60 ) + .width = 0x00000000 (0 ) + .height = 0x00000000 (0 ) + .options1 = 0x00B1 (177 ) + .autoColor = true + .showKey = false + .showValue = false + .vertical = false + .autoGeneratedText = true + .generated = true + .autoLabelDeleted = false + .autoBackground = true + .rotation = 0 + .showCategoryLabelAsPercentage = false + .showValueAsPercentage = false + .showBubbleSizes = false + .showLabel = false + .indexOfColorValue = 0x004D (77 ) + .options2 = 0x2B50 (11088 ) + .dataLabelPlacement = 0 + .textRotation = 0x0000 (0 ) + [/TEXT] + + ============================================ + Offset 0x1038 (4152) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + <!-- Comment to avoid forrest bug --> + ============================================ + Offset 0x103c (4156) + rectype = 0x104f, recsize = 0x14 + -BEGIN DUMP--------------------------------- + 00000000 02 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 .... + -END DUMP----------------------------------- + recordid = 0x104f, size =20 + [UNKNOWN RECORD] + .id = 104f + [/UNKNOWN RECORD] + + ============================================ + Offset 0x1054 (4180) + rectype = 0x1026, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 05 00 .. + -END DUMP----------------------------------- + recordid = 0x1026, size =2 + [FONTX] + .fontIndex = 0x0005 (5 ) + [/FONTX] + + ============================================ + Offset 0x105a (4186) + rectype = 0x1051, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 00 01 00 00 00 00 00 00 ........ + -END DUMP----------------------------------- + recordid = 0x1051, size =8 + [AI] + .linkType = 0x00 (0 ) + .referenceType = 0x01 (1 ) + .options = 0x0000 (0 ) + .customNumberFormat = false + .indexNumberFmtRecord = 0x0000 (0 ) + .formulaOfLink = (org.apache.poi.hssf.record.LinkedDataFormulaField@913fe2 ) + [/AI] + + ============================================ + Offset 0x1066 (4198) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x106a (4202) + rectype = 0x1024, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 03 00 .. + -END DUMP----------------------------------- + recordid = 0x1024, size =2 + [DEFAULTTEXT] + .categoryDataType = 0x0003 (3 ) + [/DEFAULTTEXT] + + ============================================ + Offset 0x1070 (4208) + rectype = 0x1025, recsize = 0x20 + -BEGIN DUMP--------------------------------- + 00000000 02 02 01 00 00 00 00 00 DB FF FF FF C4 FF FF FF ................ + 00000010 00 00 00 00 00 00 00 00 B1 00 4D 00 50 2B 00 00 ..........M.P+.. + -END DUMP----------------------------------- + recordid = 0x1025, size =32 + [TEXT] + .horizontalAlignment = 0x02 (2 ) + .verticalAlignment = 0x02 (2 ) + .displayMode = 0x0001 (1 ) + .rgbColor = 0x00000000 (0 ) + .x = 0xFFFFFFDB (-37 ) + .y = 0xFFFFFFC4 (-60 ) + .width = 0x00000000 (0 ) + .height = 0x00000000 (0 ) + .options1 = 0x00B1 (177 ) + .autoColor = true + .showKey = false + .showValue = false + .vertical = false + .autoGeneratedText = true + .generated = true + .autoLabelDeleted = false + .autoBackground = true + .rotation = 0 + .showCategoryLabelAsPercentage = false + .showValueAsPercentage = false + .showBubbleSizes = false + .showLabel = false + .indexOfColorValue = 0x004D (77 ) + .options2 = 0x2B50 (11088 ) + .dataLabelPlacement = 0 + .textRotation = 0x0000 (0 ) + [/TEXT] + + ============================================ + Offset 0x1094 (4244) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x1098 (4248) + rectype = 0x104f, recsize = 0x14 + -BEGIN DUMP--------------------------------- + 00000000 02 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 .... + -END DUMP----------------------------------- + recordid = 0x104f, size =20 + [UNKNOWN RECORD] + .id = 104f + [/UNKNOWN RECORD] + + ============================================ + Offset 0x10b0 (4272) + rectype = 0x1026, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 06 00 .. + -END DUMP----------------------------------- + recordid = 0x1026, size =2 + [FONTX] + .fontIndex = 0x0006 (6 ) + [/FONTX] + + ============================================ + Offset 0x10b6 (4278) + rectype = 0x1051, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 00 01 00 00 00 00 00 00 ........ + -END DUMP----------------------------------- + recordid = 0x1051, size =8 + [AI] + .linkType = 0x00 (0 ) + .referenceType = 0x01 (1 ) + .options = 0x0000 (0 ) + .customNumberFormat = false + .indexNumberFmtRecord = 0x0000 (0 ) + .formulaOfLink = (org.apache.poi.hssf.record.LinkedDataFormulaField@1f934ad ) + [/AI] + + ============================================ + Offset 0x10c2 (4290) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x10c6 (4294) + rectype = 0x1046, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 01 00 .. + -END DUMP----------------------------------- + recordid = 0x1046, size =2 + [AXISUSED] + .numAxis = 0x0001 (1 ) + [/AXISUSED] + + ============================================ + Offset 0x10cc (4300) + rectype = 0x1041, recsize = 0x12 + -BEGIN DUMP--------------------------------- + 00000000 00 00 DF 01 00 00 DD 00 00 00 B3 0B 00 00 56 0B ..............V. + 00000010 00 00 .. + -END DUMP----------------------------------- + recordid = 0x1041, size =18 + [AXISPARENT] + .axisType = 0x0000 (0 ) + .x = 0x000001DF (479 ) + .y = 0x000000DD (221 ) + .width = 0x00000BB3 (2995 ) + .height = 0x00000B56 (2902 ) + [/AXISPARENT] + + ============================================ + Offset 0x10e2 (4322) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x10e6 (4326) + rectype = 0x104f, recsize = 0x14 + -BEGIN DUMP--------------------------------- + 00000000 02 00 02 00 3A 00 00 00 5E 00 00 00 58 0D 00 00 ....:...^...X... + 00000010 E5 0E 00 00 .... + -END DUMP----------------------------------- + recordid = 0x104f, size =20 + [UNKNOWN RECORD] + .id = 104f + [/UNKNOWN RECORD] + + ============================================ + Offset 0x10fe (4350) + rectype = 0x101d, recsize = 0x12 + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 .. + -END DUMP----------------------------------- + recordid = 0x101d, size =18 + [AXIS] + .axisType = 0x0000 (0 ) + .reserved1 = 0x00000000 (0 ) + .reserved2 = 0x00000000 (0 ) + .reserved3 = 0x00000000 (0 ) + .reserved4 = 0x00000000 (0 ) + [/AXIS] + + ============================================ + Offset 0x1114 (4372) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x1118 (4376) + rectype = 0x1020, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 01 00 01 00 01 00 01 00 ........ + -END DUMP----------------------------------- + recordid = 0x1020, size =8 + [CATSERRANGE] + .crossingPoint = 0x0001 (1 ) + .labelFrequency = 0x0001 (1 ) + .tickMarkFrequency = 0x0001 (1 ) + .options = 0x0001 (1 ) + .valueAxisCrossing = true + .crossesFarRight = false + .reversed = false + [/CATSERRANGE] + + ============================================ + Offset 0x1124 (4388) + rectype = 0x1062, recsize = 0x12 + -BEGIN DUMP--------------------------------- + 00000000 1C 90 39 90 02 00 00 00 01 00 00 00 00 00 1C 90 ..9............. + 00000010 FF 00 .. + -END DUMP----------------------------------- + recordid = 0x1062, size =18 + [AXCEXT] + .minimumCategory = 0x901C (-28644 ) + .maximumCategory = 0x9039 (-28615 ) + .majorUnitValue = 0x0002 (2 ) + .majorUnit = 0x0000 (0 ) + .minorUnitValue = 0x0001 (1 ) + .minorUnit = 0x0000 (0 ) + .baseUnit = 0x0000 (0 ) + .crossingPoint = 0x901C (-28644 ) + .options = 0x00FF (255 ) + .defaultMinimum = true + .defaultMaximum = true + .defaultMajor = true + .defaultMinorUnit = true + .isDate = true + .defaultBase = true + .defaultCross = true + .defaultDateSettings = true + [/AXCEXT] + + ============================================ + Offset 0x113a (4410) + rectype = 0x101e, recsize = 0x1e + -BEGIN DUMP--------------------------------- + 00000000 02 00 03 01 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 00 00 00 00 23 00 4D 00 2D 00 ........#.M.-. + -END DUMP----------------------------------- + recordid = 0x101e, size =30 + [TICK] + .majorTickType = 0x02 (2 ) + .minorTickType = 0x00 (0 ) + .labelPosition = 0x03 (3 ) + .background = 0x01 (1 ) + .labelColorRgb = 0x00000000 (0 ) + .zero1 = 0x0000 (0 ) + .zero2 = 0x0000 (0 ) + .options = 0x0023 (35 ) + .autoTextColor = true + .autoTextBackground = true + .rotation = 0 + .autorotate = true + .tickColor = 0x004D (77 ) + .zero3 = 0x002D (45 ) + [/TICK] + + ============================================ + Offset 0x115c (4444) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x1160 (4448) + rectype = 0x101d, recsize = 0x12 + -BEGIN DUMP--------------------------------- + 00000000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 .. + -END DUMP----------------------------------- + recordid = 0x101d, size =18 + [AXIS] + .axisType = 0x0001 (1 ) + .reserved1 = 0x00000000 (0 ) + .reserved2 = 0x00000000 (0 ) + .reserved3 = 0x00000000 (0 ) + .reserved4 = 0x00000000 (0 ) + [/AXIS] + + <!-- Comment to avoid forrest bug --> + ============================================ + Offset 0x1176 (4470) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x117a (4474) + rectype = 0x101f, recsize = 0x2a + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000020 00 00 00 00 00 00 00 00 1F 01 .......... + -END DUMP----------------------------------- + recordid = 0x101f, size =42 + [VALUERANGE] + .minimumAxisValue = (0.0 ) + .maximumAxisValue = (0.0 ) + .majorIncrement = (0.0 ) + .minorIncrement = (0.0 ) + .categoryAxisCross = (0.0 ) + .options = 0x011F (287 ) + .automaticMinimum = true + .automaticMaximum = true + .automaticMajor = true + .automaticMinor = true + .automaticCategoryCrossing = true + .logarithmicScale = false + .valuesInReverse = false + .crossCategoryAxisAtMaximum = false + .reserved = true + [/VALUERANGE] + + ============================================ + Offset 0x11a8 (4520) + rectype = 0x101e, recsize = 0x1e + -BEGIN DUMP--------------------------------- + 00000000 02 00 03 01 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 00 00 00 00 23 00 4D 00 00 00 ........#.M... + -END DUMP----------------------------------- + recordid = 0x101e, size =30 + [TICK] + .majorTickType = 0x02 (2 ) + .minorTickType = 0x00 (0 ) + .labelPosition = 0x03 (3 ) + .background = 0x01 (1 ) + .labelColorRgb = 0x00000000 (0 ) + .zero1 = 0x0000 (0 ) + .zero2 = 0x0000 (0 ) + .options = 0x0023 (35 ) + .autoTextColor = true + .autoTextBackground = true + .rotation = 0 + .autorotate = true + .tickColor = 0x004D (77 ) + .zero3 = 0x0000 (0 ) + [/TICK] + + ============================================ + Offset 0x11ca (4554) + rectype = 0x1021, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 01 00 .. + -END DUMP----------------------------------- + recordid = 0x1021, size =2 + [AXISLINEFORMAT] + .axisType = 0x0001 (1 ) + [/AXISLINEFORMAT] + + ============================================ + Offset 0x11d0 (4560) + rectype = 0x1007, recsize = 0xc + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 00 00 FF FF 09 00 4D 00 ..........M. + -END DUMP----------------------------------- + recordid = 0x1007, size =12 + [LINEFORMAT] + .lineColor = 0x00000000 (0 ) + .linePattern = 0x0000 (0 ) + .weight = 0xFFFF (-1 ) + .format = 0x0009 (9 ) + .auto = true + .drawTicks = false + .unknown = false + .colourPaletteIndex = 0x004D (77 ) + [/LINEFORMAT] + + ============================================ + Offset 0x11e0 (4576) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x11e4 (4580) + rectype = 0x1035, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1035, size =0 + [PLOTAREA] + [/PLOTAREA] + + ============================================ + Offset 0x11e8 (4584) + rectype = 0x1032, recsize = 0x4 + -BEGIN DUMP--------------------------------- + 00000000 00 00 03 00 .... + -END DUMP----------------------------------- + recordid = 0x1032, size =4 + [FRAME] + .borderType = 0x0000 (0 ) + .options = 0x0003 (3 ) + .autoSize = true + .autoPosition = true + [/FRAME] + + ============================================ + Offset 0x11f0 (4592) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x11f4 (4596) + rectype = 0x1007, recsize = 0xc + -BEGIN DUMP--------------------------------- + 00000000 80 80 80 00 00 00 00 00 00 00 17 00 ............ + -END DUMP----------------------------------- + recordid = 0x1007, size =12 + [LINEFORMAT] + .lineColor = 0x00808080 (8421504 ) + .linePattern = 0x0000 (0 ) + .weight = 0x0000 (0 ) + .format = 0x0000 (0 ) + .auto = false + .drawTicks = false + .unknown = false + .colourPaletteIndex = 0x0017 (23 ) + [/LINEFORMAT] + + ============================================ + Offset 0x1204 (4612) + rectype = 0x100a, recsize = 0x10 + -BEGIN DUMP--------------------------------- + 00000000 C0 C0 C0 00 00 00 00 00 01 00 00 00 16 00 4F 00 ..............O. + -END DUMP----------------------------------- + recordid = 0x100a, size =16 + [AREAFORMAT] + .foregroundColor = 0x00C0C0C0 (12632256 ) + .backgroundColor = 0x00000000 (0 ) + .pattern = 0x0001 (1 ) + .formatFlags = 0x0000 (0 ) + .automatic = false + .invert = false + .forecolorIndex = 0x0016 (22 ) + .backcolorIndex = 0x004F (79 ) + [/AREAFORMAT] + + ============================================ + Offset 0x1218 (4632) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x121c (4636) + rectype = 0x1014, recsize = 0x14 + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 .... + -END DUMP----------------------------------- + recordid = 0x1014, size =20 + [CHARTFORMAT] + .xPosition = 0 + .yPosition = 0 + .width = 0 + .height = 0 + .grBit = 0 + [/CHARTFORMAT] + + ============================================ + Offset 0x1234 (4660) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x1238 (4664) + rectype = 0x1017, recsize = 0x6 + -BEGIN DUMP--------------------------------- + 00000000 00 00 96 00 00 00 ...... + -END DUMP----------------------------------- + recordid = 0x1017, size =6 + [BAR] + .barSpace = 0x0000 (0 ) + .categorySpace = 0x0096 (150 ) + .formatFlags = 0x0000 (0 ) + .horizontal = false + .stacked = false + .displayAsPercentage = false + .shadow = false + [/BAR] + + ============================================ + Offset 0x1242 (4674) + rectype = 0x1022, recsize = 0xa + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 00 00 00 00 0F 00 .......... + -END DUMP----------------------------------- + recordid = 0x1022, size =10 + [UNKNOWN RECORD] + .id = 1022 + [/UNKNOWN RECORD] + + ============================================ + Offset 0x1250 (4688) + rectype = 0x1015, recsize = 0x14 + -BEGIN DUMP--------------------------------- + 00000000 D6 0D 00 00 1E 06 00 00 B5 01 00 00 D5 00 00 00 ................ + 00000010 03 01 1F 00 .... + -END DUMP----------------------------------- + recordid = 0x1015, size =20 + [LEGEND] + .xAxisUpperLeft = 0x00000DD6 (3542 ) + .yAxisUpperLeft = 0x0000061E (1566 ) + .xSize = 0x000001B5 (437 ) + .ySize = 0x000000D5 (213 ) + .type = 0x03 (3 ) + .spacing = 0x01 (1 ) + .options = 0x001F (31 ) + .autoPosition = true + .autoSeries = true + .autoXPositioning = true + .autoYPositioning = true + .vertical = true + .dataTable = false + [/LEGEND] + + ============================================ + Offset 0x1268 (4712) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x126c (4716) + rectype = 0x104f, recsize = 0x14 + -BEGIN DUMP--------------------------------- + 00000000 05 00 02 00 D6 0D 00 00 1E 06 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 .... + -END DUMP----------------------------------- + recordid = 0x104f, size =20 + [UNKNOWN RECORD] + .id = 104f + [/UNKNOWN RECORD] + + ============================================ + Offset 0x1284 (4740) + rectype = 0x1025, recsize = 0x20 + -BEGIN DUMP--------------------------------- + 00000000 02 02 01 00 00 00 00 00 DB FF FF FF C4 FF FF FF ................ + 00000010 00 00 00 00 00 00 00 00 B1 00 4D 00 70 37 00 00 ..........M.p7.. + -END DUMP----------------------------------- + recordid = 0x1025, size =32 + [TEXT] + .horizontalAlignment = 0x02 (2 ) + .verticalAlignment = 0x02 (2 ) + .displayMode = 0x0001 (1 ) + .rgbColor = 0x00000000 (0 ) + .x = 0xFFFFFFDB (-37 ) + .y = 0xFFFFFFC4 (-60 ) + .width = 0x00000000 (0 ) + .height = 0x00000000 (0 ) + .options1 = 0x00B1 (177 ) + .autoColor = true + .showKey = false + .showValue = false + .vertical = false + .autoGeneratedText = true + .generated = true + .autoLabelDeleted = false + .autoBackground = true + .rotation = 0 + .showCategoryLabelAsPercentage = false + .showValueAsPercentage = false + .showBubbleSizes = false + .showLabel = false + .indexOfColorValue = 0x004D (77 ) + .options2 = 0x3770 (14192 ) + .dataLabelPlacement = 0 + .textRotation = 0x0000 (0 ) + [/TEXT] + + ============================================ + Offset 0x12a8 (4776) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x12ac (4780) + rectype = 0x104f, recsize = 0x14 + -BEGIN DUMP--------------------------------- + 00000000 02 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 .... + -END DUMP----------------------------------- + recordid = 0x104f, size =20 + [UNKNOWN RECORD] + .id = 104f + [/UNKNOWN RECORD] + + ============================================ + Offset 0x12c4 (4804) + rectype = 0x1051, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 00 01 00 00 00 00 00 00 ........ + -END DUMP----------------------------------- + recordid = 0x1051, size =8 + [AI] + .linkType = 0x00 (0 ) + .referenceType = 0x01 (1 ) + .options = 0x0000 (0 ) + .customNumberFormat = false + .indexNumberFmtRecord = 0x0000 (0 ) + .formulaOfLink = (org.apache.poi.hssf.record.LinkedDataFormulaField@1d05c81 ) + [/AI] + + ============================================ + Offset 0x12d0 (4816) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + <!-- Comment to avoid forrest bug --> + ============================================ + Offset 0x12d4 (4820) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x12d8 (4824) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x12dc (4828) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x12e0 (4832) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + rectype = 0x200, recsize = 0xe + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 1F 00 00 00 00 00 01 00 00 00 .............. + -END DUMP----------------------------------- + recordid = 0x200, size =14 + [DIMENSIONS] + .firstrow = 0 + .lastrow = 1f + .firstcol = 0 + .lastcol = 1 + .zero = 0 + [/DIMENSIONS] + + ============================================ + rectype = 0x1065, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 02 00 .. + -END DUMP----------------------------------- + recordid = 0x1065, size =2 + [SINDEX] + .index = 0x0002 (2 ) + [/SINDEX] + + ============================================ + rectype = 0x1065, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 01 00 .. + -END DUMP----------------------------------- + recordid = 0x1065, size =2 + [SINDEX] + .index = 0x0001 (1 ) + [/SINDEX] + + ============================================ + rectype = 0x1065, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 03 00 .. + -END DUMP----------------------------------- + recordid = 0x1065, size =2 + [SINDEX] + .index = 0x0003 (3 ) + [/SINDEX] + + ============================================ + rectype = 0xa, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0xa, size =0 + [EOF] + [/EOF] + + + </source> + <p> + The next section breaks those records down into an easier + to read format: + </p> + <source> +[UNKNOWN RECORD:ec] +[UNKNOWN RECORD:5d] +[BOF RECORD] + [HEADER] + [FOOTER] + [HCENTER] + [VCENTER] + [PRINTSETUP] + [UNKNOWN RECORD:33] + [FBI] + [FBI] + [PROTECT] + [UNITS] + [CHART] + [BEGIN] + [SCL] // zoom magnification + [PLOTGROWTH] // font scaling + [FRAME] // border around text + [BEGIN] // default line and area format + [LINEFORMAT] + [AREAFORMAT] + [END] + [SERIES] // start of series + [BEGIN] + [AI] // LINK_TYPE_TITLE_OR_TEXT + [AI] // LINK_TYPE_VALUES + [AI] // LINK_TYPE_CATEGORIES + [AI] // ?? + [DATAFORMAT] // Formatting applies to series? + [BEGIN] // ?? + [UNKNOWN RECORD] + [END] + [SeriesToChartGroup] // Used to support > 1 chart? + [END] + [SHTPROPS] // Some defaults for how chart is displayed. + [DEFAULTTEXT] // Describes the characteristics of the next + // record + [TEXT] // Details of the text that follows in the + // next section + [BEGIN] + [UNKNOWN RECORD] // POS record... looks like I missed this one. + // docs seem to indicate it's better to use + // defaults... + [FONTX] // index to font record. + [AI] // link to text? seems to be linking to nothing + [END] + [DEFAULTTEXT] // contains a category type of 3 which is not + // documented (sigh). + [TEXT] // defines position, color etc for text on chart. + [BEGIN] + [UNKNOWN RECORD] // Another pos record + [FONTX] // font + [AI] // reference type is DIRECT (not sure what this + // means) + [END] + [AXISUSED] // number of axis on the chart. + [AXISPARENT] // axis size and location + [BEGIN] // beginning of axis details + [UNKNOWN RECORD] // Another pos record. + [AXIS] // Category axis + [BEGIN] + [CATSERRANGE] // defines tick marks and other stuff + [AXCEXT] // unit information + [TICK] // tick formating characteristics + [END] + [AXIS] // Value axis + [BEGIN] + [VALUERANGE] // defines tick marks and other stuff + [TICK] // tick formating characteristics + [AXISLINEFORMAT] // major grid line axis format + [LINEFORMAT] // what do the lines look like? + [END] + [PLOTAREA] // marks that the frame following belongs + // to the frame. + [FRAME] // border + [BEGIN] + [LINEFORMAT] // border line + [AREAFORMAT] // border area + [END] + [CHARTFORMAT] // marks a chart group + [BEGIN] + [BAR] // indicates a bar chart + [UNKNOWN RECORD] // apparently this record is ignoreable + [LEGEND] // positioning for the legend + [BEGIN] + [UNKNOWN RECORD] // another position record. + [TEXT] // details of the text that follows + // in the next section + [BEGIN] + [UNKNOWN RECORD] // yet another pos record + [AI] // another link (of type direct) + [END] + [END] + [END] + [END] + [END] + [DIMENSIONS] + [SINDEX] + [SINDEX] + [SINDEX] +[EOF] + </source> + <p> + Just a quick note on some of the unknown records: + </p> + <ul> + <li>EC: MSODRAWING - A Microsoft drawing record. (Need to + track down where this is documented).</li> + <li>5D: OBJ: Description of a drawing object. (This is going to + be a PITA to implement).</li> + <li>33: Not documented. :-(</li> + <li>105f: Not documented. :-(</li> + <li>104f: POS: Position record (should be able to safely leave this out).</li> + <li>1022: CHARTFORMATLINK: Can be left out.</li> + </ul> + <p> + It is currently suspected that many of those records could be + left out when generating a bar chart from scratch. The way + we will be proceeding with this is to write code that generates + most of these records and then start removing them to see + how this effects the chart in excel. + </p> + </section> + <section><title>Inserting the Chart into the Workbook</title> + <ul> + <li> + Unknown record (sid=00eb) is inserted before the SST + record. + </li> + </ul> + <source> + ============================================ + rectype = 0xeb, recsize = 0x5a + -BEGIN DUMP--------------------------------- + 00000000 0F 00 00 F0 52 00 00 00 00 00 06 F0 18 00 00 00 ....R........... + 00000010 01 08 00 00 02 00 00 00 02 00 00 00 01 00 00 00 ................ + 00000020 01 00 00 00 03 00 00 00 33 00 0B F0 12 00 00 00 ........3....... + 00000030 BF 00 08 00 08 00 81 01 09 00 00 08 C0 01 40 00 ..............@. + 00000040 00 08 40 00 1E F1 10 00 00 00 0D 00 00 08 0C 00 ..@............. + 00000050 00 08 17 00 00 08 F7 00 00 10 .......... + -END DUMP----------------------------------- + recordid = 0xeb, size =90 + [UNKNOWN RECORD:eb] + .id = eb + [/UNKNOWN RECORD] + + ============================================ + </source> + <ul> + <li> + Any extra font records are inserted as needed + </li> + <li> + Chart records inserted after DBCell records. + </li> + </ul> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/converting.xml b/src/documentation/content/xdocs/components/spreadsheet/converting.xml new file mode 100644 index 0000000000..0700cc4e43 --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/converting.xml @@ -0,0 +1,232 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Upgrading to POI 3.5, including converting existing HSSF Usermodel code to SS Usermodel (for XSSF and HSSF)</title> + <authors> + <person email="nick@apache.org" name="Nick Burch" id="NB"/> + </authors> + </header> + <body> +<section><title>Things that have to be changed when upgrading to POI 3.5</title> + <p>Wherever possible, we have tried to ensure that you can use your + existing POI code with POI 3.5 without requiring any changes. However, + Java doesn't always make that easy, and unfortunately there are a + few changes that may be required for some users.</p> + <section><title>org.apache.poi.hssf.usermodel.HSSFFormulaEvaluator.CellValue</title> + <p>Annoyingly, java will not let you access a static inner class via + a child of the parent one. So, all references to + <em>org.apache.poi.hssf.usermodel.HSSFFormulaEvaluator.CellValue</em> + will need to be changed to + <em>org.apache.poi.ss.usermodel.FormulaEvaluator.CellValue</em> + </p> + </section> + <section><title>org.apache.poi.hssf.usermodel.HSSFRow.MissingCellPolicy</title> + <p>Annoyingly, java will not let you access a static inner class via + a child of the parent one. So, all references to + <em>org.apache.poi.hssf.usermodel.HSSFRow.MissingCellPolicy</em> + will need to be changed to + <em>org.apache.poi.ss.usermodel.Row.MissingCellPolicy</em> + </p> + </section> + <section><title>DDF and org.apache.poi.hssf.record.RecordFormatException</title> + <p>Previously, record level errors within DDF would throw an + exception from the hssf class hierarchy. Now, record level errors + within DDF will throw a more general RecordFormatException, + <em>org.apache.poi.util.RecordFormatException</em></p> + <p>In addition, org.apache.poi.hssf.record.RecordFormatException + has been changed to inherit from the new + <em>org.apache.poi.util.RecordFormatException</em>, so you may + wish to change catches of the hssf version to the new util version. + </p> + </section> + </section> + <section><title>Converting existing HSSF Usermodel code to SS Usermodel (for XSSF and HSSF)</title> + + <section><title>Why change?</title> + <p>If you have existing HSSF usermodel code that works just + fine, and you don't want to use the new OOXML XSSF support, + then you probably don't need to. Your existing HSSF only code + will continue to work just fine.</p> + <p>However, if you want to be able to work with both HSSF for + your .xls files, and also XSSF for .xslx files, then you will + need to make some slight tweaks to your code.</p> + </section> + <section><title>org.apache.poi.ss.usermodel</title> + <p>The new SS usermodel (org.apache.poi.ss.usermodel) is very + heavily based on the old HSSF usermodel + (org.apache.poi.hssf.usermodel). The main difference is that + the package name and class names have been tweaked to remove + HSSF from them. Otherwise, the new SS Usermodel interfaces + should provide the same functionality.</p> + </section> + <section><title>Constructors</title> + <p>Calling the empty HSSFWorkbook remains as the way to + create a new, empty Workbook object. To open an existing + Workbook, you should now call WorkbookFactory.create(inp).</p> + <p>For all other cases when you would have called a + Usermodel constructor, such as 'new HSSFRichTextString()' or + 'new HSSFDataFormat', you should instead use a CreationHelper. + There's a method on the Workbook to get a CreationHelper, and + the CreationHelper will then handle constructing new objects + for you.</p> + </section> + <section><title>Other Code</title> + <p>For all other code, generally change a reference from + org.apache.poi.hssf.usermodel.HSSFFoo to a reference to + org.apache.poi.ss.usermodel.Foo. Method signatures should + otherwise remain the same, and it should all then work for + both XSSF and HSSF.</p> + </section> + </section> + <section><title>Worked Examples</title> + <section><title>Old HSSF Code</title> +<source><![CDATA[ +// import org.apache.poi.hssf.usermodel.*; + +HSSFWorkbook wb = new HSSFWorkbook(); +// create a new sheet +HSSFSheet s = wb.createSheet(); +// declare a row object reference +HSSFRow r = null; +// declare a cell object reference +HSSFCell c = null; +// create 2 cell styles +HSSFCellStyle cs = wb.createCellStyle(); +HSSFCellStyle cs2 = wb.createCellStyle(); +HSSFDataFormat df = wb.createDataFormat(); + +// create 2 fonts objects +HSSFFont f = wb.createFont(); +HSSFFont f2 = wb.createFont(); + +// Set font 1 to 12 point type, blue and bold +f.setFontHeightInPoints((short) 12); +f.setColor( HSSFColor.RED.index ); +f.setBoldweight(HSSFFont.BOLDWEIGHT_BOLD); + +// Set font 2 to 10 point type, red and bold +f2.setFontHeightInPoints((short) 10); +f2.setColor( HSSFFont.RED.index ); +f2.setBoldweight(HSSFFont.BOLDWEIGHT_BOLD); + +// Set cell style and formatting +cs.setFont(f); +cs.setDataFormat(df.getFormat("#,##0.0")); + +// Set the other cell style and formatting +cs2.setBorderBottom(cs2.BORDER_THIN); +cs2.setDataFormat(HSSFDataFormat.getBuiltinFormat("text")); +cs2.setFont(f2); + + +// Define a few rows +for(short rownum = (short)0; rownum < 30; rownum++) { + HSSFRow r = s.createRow(rownum); + for(short cellnum = (short)0; cellnum < 10; cellnum += 2) { + HSSFCell c = r.createCell(cellnum); + HSSFCell c2 = r.createCell(cellnum+1); + + c.setCellValue((double)rownum + (cellnum/10)); + c2.setCellValue(new HSSFRichTextString("Hello! " + cellnum); + } +} + +// Save +FileOutputStream out = new FileOutputStream("workbook.xls"); +wb.write(out); +out.close(); + ]]></source> + </section> + <section><title>New, generic SS Usermodel Code</title> +<source><![CDATA[ +// import org.apache.poi.ss.usermodel.*; + +Workbook[] wbs = new Workbook[] { new HSSFWorkbook(), new XSSFWorkbook() }; +for(int i=0; i<wbs.length; i++) { + Workbook wb = wbs[i]; + CreationHelper createHelper = wb.getCreationHelper(); + + // create a new sheet + Sheet s = wb.createSheet(); + // declare a row object reference + Row r = null; + // declare a cell object reference + Cell c = null; + // create 2 cell styles + CellStyle cs = wb.createCellStyle(); + CellStyle cs2 = wb.createCellStyle(); + DataFormat df = wb.createDataFormat(); + + // create 2 fonts objects + Font f = wb.createFont(); + Font f2 = wb.createFont(); + + // Set font 1 to 12 point type, blue and bold + f.setFontHeightInPoints((short) 12); + f.setColor( IndexedColors.RED.getIndex() ); + f.setBoldweight(Font.BOLDWEIGHT_BOLD); + + // Set font 2 to 10 point type, red and bold + f2.setFontHeightInPoints((short) 10); + f2.setColor( IndexedColors.RED.getIndex() ); + f2.setBoldweight(Font.BOLDWEIGHT_BOLD); + + // Set cell style and formatting + cs.setFont(f); + cs.setDataFormat(df.getFormat("#,##0.0")); + + // Set the other cell style and formatting + cs2.setBorderBottom(cs2.BORDER_THIN); + cs2.setDataFormat(df.getFormat("text")); + cs2.setFont(f2); + + + // Define a few rows + for(int rownum = 0; rownum < 30; rownum++) { + Row r = s.createRow(rownum); + for(int cellnum = 0; cellnum < 10; cellnum += 2) { + Cell c = r.createCell(cellnum); + Cell c2 = r.createCell(cellnum+1); + + c.setCellValue((double)rownum + (cellnum/10)); + c2.setCellValue( + createHelper.createRichTextString("Hello! " + cellnum) + ); + } + } + + // Save + String filename = "workbook.xls"; + if(wb instanceof XSSFWorkbook) { + filename = filename + "x"; + } + + FileOutputStream out = new FileOutputStream(filename); + wb.write(out); + out.close(); +} + ]]></source> + </section> +</section> +</body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/diagram1.xml b/src/documentation/content/xdocs/components/spreadsheet/diagram1.xml new file mode 100644 index 0000000000..438da0e7c8 --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/diagram1.xml @@ -0,0 +1,40 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>HSSF</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Andrew C. Oliver" email="acoliver@apache.org"/> + <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/> + </authors> + </header> + + <body> + <section> + <title>Usermodel Class Diagram by Matthew Young</title> + <p> + <img src="images/usermodel.gif" alt="Usermodel"/> + </p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/diagrams.xml b/src/documentation/content/xdocs/components/spreadsheet/diagrams.xml new file mode 100644 index 0000000000..208cabfa6f --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/diagrams.xml @@ -0,0 +1,56 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>HSSF</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Andrew C. Oliver" email="acoliver@apache.org"/> + <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/> + </authors> + </header> + + <body> + <section><title>Overview</title> + <p> + This section is intended for diagrams (UML/etc) that help + explain HSSF. + </p> + <ul> + <li> + <a href="diagram1.html">HSSF usermodel class diagram</a> - + by Matthew Young (myoung at westernasset dot com) + </li> + </ul> + <p> + Have more? Add a new "bug" to the bug database with [DOCUMENTATION] + prefacing the description and a link to the file on an http server + somewhere. If you don't have your own webserver, then you can email it + to (acoliver at apache dot org) provided its < 5MB. Diagrams should be + in some format that can be read at least on Linux and Windows. Diagrams + that can be edited are preferable, but lets face it, there aren't too + many good affordable UML tools yet! And no they don't HAVE to be UML... + just useful. + </p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/eval-devguide.xml b/src/documentation/content/xdocs/components/spreadsheet/eval-devguide.xml new file mode 100644 index 0000000000..2d49b0aa09 --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/eval-devguide.xml @@ -0,0 +1,591 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Developing Formula Evaluation</title> + <authors> + <person email="amoweb@yahoo.com" name="Amol Deshmukh" id="AD"/> + <person email="yegor@apache.org" name="Yegor Kozlov" id="YK"/> + </authors> + </header> + <body> + <section><title>Introduction</title> + <p> + This document is for developers wishing to contribute to the + FormulaEvaluator API functionality. + </p> + <p> + When evaluating workbooks you may encounter an <code>org.apache.poi.ss.formula.eval.NotImplementedException</code> + which indicates that a function is not (yet) supported by POI. Is there a workaround? + Yes, the POI framework makes it easy to add implementation of new functions. Prior to POI-3.8 + you had to checkout the source code from svn and make a custom build with your function implementation. + Since POI-3.8 you can register new functions in run-time. + </p> + <p> + Currently, contribution is desired for implementing the standard MS + Excel functions. Placeholder classes for these have been created, + contributors only need to insert implementation for the + individual <code>evaluate()</code> methods that do the actual evaluation. + </p> + </section> + <section><title>Overview of FormulaEvaluator </title> + <p> + Briefly, a formula string (along with the sheet and workbook that + form the context in which the formula is evaluated) is first parsed + into Reverse Polish Notation (RPN) tokens using the <code>FormulaParser</code> class. + (If you don't know what RPN tokens are, now is a good time to + read <a href="http://www-stone.ch.cam.ac.uk/documentation/rrf/rpn.html"> + Anthony Stone's description of RPN</a>.) + </p> + <section><title> The big picture</title> + <p> + RPN tokens are mapped to <code>Eval</code> classes. (The class hierarchy for the <code>Eval</code>s + is best understood if you view it in a class diagram + viewer.) Depending on the type of RPN token (also called <code>Ptg</code>s + henceforth since that is what the <code>FormulaParser</code> calls the classes), a + specific type of <code>Eval</code> wrapper is constructed to wrap the RPN token and + is pushed on the stack, unless the <code>Ptg</code> is an <code>OperationPtg</code>. If it is an + <code>OperationPtg</code>, an <code>OperationEval</code> instance is created for the specific + type of <code>OperationPtg</code>. And depending on how many operands it takes, + that many <code>Eval</code>s are popped of the stack and passed in an array to + the <code>OperationEval</code> instance's evaluate method which returns an <code>Eval</code> + of subtype <code>ValueEval</code>. Thus an operation in the formula is evaluated. + </p> + <note> An <code>Eval</code> is of subinterface <code>ValueEval</code> or <code>OperationEval</code>. + Operands are always <code>ValueEval</code>s, and operations are always <code>OperationEval</code>s.</note> + <p> + <code>OperationEval.evaluate(Eval[])</code> returns an <code>Eval</code> which is supposed + to be an instance of one of the implementations of + <code>ValueEval</code>. The <code>ValueEval</code> resulting from <code>evaluate()</code> is pushed on the + stack and the next RPN token is evaluated. This continues until + eventually there are no more RPN tokens, at which point, if the formula + string was correctly parsed, there should be just one <code>Eval</code> on the + stack — which contains the result of evaluating the formula. + </p> + <p> + Two special <code>Ptg</code>s — <code>AreaPtg</code> and <code>ReferencePtg</code> — + are handled a little differently, but the code should be self + explanatory for that. Very briefly, the cells included in <code>AreaPtg</code> and + <code>RefPtg</code> are examined and their values are populated in individual + <code>ValueEval</code> objects which are set into the implementations of + <code>AreaEval</code> and <code>RefEval</code>. + </p> + <p> + <code>OperationEval</code>s for the standard operators have been implemented and tested. + </p> + </section> + </section> + <section><title>What functions are supported?</title> + <p> + As of release 5.2.0, POI implements 202 built-in functions, + see <a href="#appendixA">Appendix A</a> for the list of supported functions with an implementation. + You can programmatically list supported / unsupported functions using the following helper methods: + </p> +<source>import org.apache.poi.ss.formula.ss.formula.WorkbookEvaluator; + +// list of functions that POI can evaluate +Collection<String> supportedFuncs = WorkbookEvaluator.getSupportedFunctionNames(); + +// list of functions that are not supported by POI +Collection<String> unsupportedFuncs = WorkbookEvaluator.getNotSupportedFunctionNames(); +</source> + <section><title>I need a function that isn't supported!</title> + <p> + If you need a function that POI doesn't currently support, you have two options. + You can create the function yourself, and have your program add it to POI at + run-time. Doing this will help you get the function you need as soon as possible. + The other option is to create the function yourself, and build it into the POI library, + possibly contributing the code to the POI project. Doing this will help you get the + function you need, but you'll have to build POI from source yourself. And if you + contribute the code, you'll help others who need the function in the future, because + it will already be supported in the next release of POI. The two options require + almost identical code, but the process of deploying the function is different. + If your function is a User Defined Function, you'll always take the run-time option, + as POI doesn't distribute UDFs. + </p> + <p> + In the sections ahead, we'll implement the Excel <code>SQRTPI()</code> function, first + at run-time, and then we'll show how change it to a library-based implementation. + </p> + </section> + </section> + <section><title>Two base interfaces to start your implementation</title> + <p> + All Excel formula function classes implement either the + <code>org.apache.poi.hssf.record.formula.functions.Function</code> or the + <code>org.apache.poi.hssf.record.formula.functions.FreeRefFunction</code> interface. + <code>Function</code> is a common interface for the functions defined in the Binary Excel File Format (BIFF8): these are "classic" Excel functions like <code>SUM</code>, <code>COUNT</code>, <code>LOOKUP</code>, <em>etc</em>. + <code>FreeRefFunction</code> is a common interface for the functions from the Excel Analysis ToolPak, for User Defined Functions that you create, + and for Excel built-in functions that have been defined since BIFF8 was defined. + In the future these two interfaces are expected be unified into one, but for now you have to start your implementation from two slightly different roots. + </p> + + <section><title>Which interface to start from?</title> + <p> + You are about to implement a function and don't know which interface to start from: <code>Function</code> or <code>FreeRefFunction</code>. + You should use <code>Function</code> if the function is part of the Excel BIFF8 + definition, and <code>FreeRefFunction</code> for a function that is part of the Excel Analysis ToolPak, was added to Excel after BIFF8, or that you are creating yourself. + </p> + <p> + You can check the list of Analysis ToolPak functions defined in <code>org.apache.poi.ss.formula.atp.AnalysisToolPak.createFunctionsMap()</code> + to see if the function is part of the Analysis ToolPak. + The list of BIFF8 functions is defined as a text file, in the + <code>src/resources/main/org/apache/poi/ss/formula/function/functionMetadata.txt</code> file. + </p> + <p> + You can also use the following code to check which base class your function should implement, if it is not a User Defined function (UDFs must implement <code>FreeRefFunction</code>): + </p> +<source>import org.apache.poi.hssf.record.formula.atp.AnalysisToolPak; + +if (!AnalysisToolPak.isATPFunction(functionName)){ + // the function must implement org.apache.poi.hssf.record.formula.functions.Function +} else { + // the function must implement org.apache.poi.hssf.record.formula.functions.FreeRefFunction +} +</source> + </section> + </section> + <section><title>Implementing a function.</title> + <p> + Here is the fun part: let's walk through the implementation of the Excel function <code>SQRTPI()</code>, + which POI doesn not currently support. + </p> + <p> + <code>AnalysisToolPak.isATPFunction("SQRTPI")</code> returns true, so this is an Analysis ToolPak function. + Thus the base interface must be <code>FreeRefFunction</code>. The same would be true if we were implementing + a UDF. + </p> + <p> + Because we're taking the run-time deployment option, we'll create this new function in a source + file in our own program. Our function will return an <code>Eval</code> that is either + it's proper result, or an <code>ErrorEval</code> that describes the error. All that work + is done in the function's <code>evaluate()</code> method: + </p> +<source>package ...; +import org.apache.poi.ss.formula.eval.EvaluationException; +import org.apache.poi.ss.formula.eval.ErrorEval; +import org.apache.poi.ss.formula.eval.NumberEval; +import org.apache.poi.ss.formula.eval.OperandResolver; +import org.apache.poi.ss.formula.eval.ValueEval; +import org.apache.poi.ss.formula.functions.FreeRefFunction; + +public final class SqrtPi implements FreeRefFunction { + + public ValueEval evaluate(ValueEval[] args, OperationEvaluationContext ec) { + ValueEval arg0 = args[0]; + int srcRowIndex = ec.getRowIndex(); + int srcColumnIndex = ec.getColumnIndex(); + try { + // Retrieves a single value from a variety of different argument types according to standard + // Excel rules. Does not perform any type conversion. + ValueEval ve = OperandResolver.getSingleValue(arg0, srcRowIndex, srcColumnIndex); + + // Applies some conversion rules if the supplied value is not already a number. + // Throws EvaluationException(#VALUE!) if the supplied parameter is not a number + double arg = OperandResolver.coerceValueToDouble(ve); + + // this where all the heavy-lifting happens + double result = Math.sqrt(arg*Math.PI); + + // Excel uses the error code #NUM! instead of IEEE NaN and Infinity, + // so when a numeric function evaluates to Double.NaN or Double.Infinity, + // be sure to translate the result to the appropriate error code + if (Double.isNaN(result) || Double.isInfinite(result)) { + throw new EvaluationException(ErrorEval.NUM_ERROR); + } + + return new NumberEval(result); + } catch (EvaluationException e){ + return e.getErrorEval(); + } + } +} +</source> + <p> + If our function had been one of the BIFF8 Excel built-ins, it would have been based on + the <code>Function</code> interface instead. + There are sub-interfaces of <code>Function</code> that make life easier when implementing numeric functions + or functions + with a small, fixed number of arguments: + </p> + <ul> + <li><code>org.apache.poi.hssf.record.formula.functions.NumericFunction</code></li> + <li><code>org.apache.poi.hssf.record.formula.functions.Fixed0ArgFunction</code></li> + <li><code>org.apache.poi.hssf.record.formula.functions.Fixed1ArgFunction</code></li> + <li><code>org.apache.poi.hssf.record.formula.functions.Fixed2ArgFunction</code></li> + <li><code>org.apache.poi.hssf.record.formula.functions.Fixed3ArgFunction</code></li> + <li><code>org.apache.poi.hssf.record.formula.functions.Fixed4ArgFunction</code></li> + </ul> + <p> + Since <code>SQRTPI()</code> takes exactly one argument, we would start our implementation from + <code>Fixed1ArgFunction</code>. The differences for a BIFF8 <code>Fixed1ArgFunction</code> + are pretty small: + </p> +<source>package ...; +import org.apache.poi.ss.formula.eval.EvaluationException; +import org.apache.poi.ss.formula.eval.ErrorEval; +import org.apache.poi.ss.formula.eval.NumberEval; +import org.apache.poi.ss.formula.eval.OperandResolver; +import org.apache.poi.ss.formula.eval.ValueEval; +import org.apache.poi.ss.formula.functions.Fixed1ArgFunction; + +public final class SqrtPi extends Fixed1ArgFunction { + + public ValueEval evaluate(int srcRowIndex, int srcColumnIndex, ValueEval arg0) { + try { + ... + } +} +</source> + <p> + Now when the implementation is ready we need to register it with the formula evaluator. + This is the same no matter which kind of function we're creating. We simply add the + following line to the program that is using POI: + </p> +<source>WorkbookEvaluator.registerFunction("SQRTPI", SqrtPi); +</source> + <p> + Voila! The formula evaluator now recognizes <code>SQRTPI()</code>! + </p> + <section><title>Moving the function into the library</title> + <p> + If we choose instead to implement our function as part of the POI + library, the code is nearly identical. All POI functions + are part of one of two Java packages: <code>org.apache.poi.ss.formula.functions</code> + for BIFF8 Excel built-in functions, and <code>org.apache.poi.ss.formula.atp</code> + for Analysis ToolPak functions. The function still needs to implement the + appropriate base class, just as before. To implement our <code>SQRTPI()</code> + function in the POI library, we need to move the source code to + <code>poi/src/main/java/org/apache/poi/ss/formula/atp/SqrtPi.java</code> in + the POI source code, change the <code>package</code> statement, and add a + singleton instance: + </p> +<source>package org.apache.poi.ss.formula.atp; +... +public final class SqrtPi implements FreeRefFunction { + + public static final FreeRefFunction instance = new SqrtPi(); + + private SqrtPi() { + // Enforce singleton + } + ... +} +</source> + <p> + If our function had been one of the BIFF8 Excel built-ins, we would instead have moved + the source code to + <code>poi/src/main/java/org/apache/poi/ss/formula/functions/SqrtPi.java</code> in + the POI source code, and changed the <code>package</code> statement to: + </p> +<source>package org.apache.poi.ss.formula.functions; +</source> + <p> + POI library functions are registered differently from run-time-deployed functions. + Again, the techniques differ for the two types of library functions (remembering + that POI never releases the third type, UDFs). + For our Analysis ToolPak function, we have to update the list of functions in + <code>org.apache.poi.ss.formula.atp.AnalysisToolPak.createFunctionsMap()</code>: + </p> +<source>... +private Map<String, FreeRefFunction> createFunctionsMap() { + Map<String, FreeRefFunction> m = new HashMap<>(114); + ... + r(m, "SQRTPI", SqrtPi.instance); + ... +} +... +</source> + <p> + If our function had been one of the BIFF8 Excel built-ins, + the registration instead would require updating an entry in the formula-function table, + <code>poi/src/main/resources/org/apache/poi/ss/formula/function/functionMetadata.txt</code>: + </p> +<source>... +#Columns: (index, name, minParams, maxParams, returnClass, paramClasses, isVolatile, hasFootnote ) +... +359 SQRTPI 1 1 V V +... +</source> + <p> + and also updating the list of function implementation list in + <code>org.apache.poi.ss.formula.eval.FunctionEval.produceFunctions()</code>: + </p> +<source>... +private static Function[] produceFunctions() { + ... + retval[359] = new SqrtPi(); + ... +} +... +</source> + </section> + <section><title>Floating Point Arithmetic in Excel</title> + <p> + Excel uses the IEEE Standard for Double Precision Floating Point numbers + except two cases where it does not adhere to IEEE 754: + </p> + <ol> + <li>Positive and Negative Infinities: Infinities occur when you divide by 0. + Excel does not support infinities, rather, it gives a #DIV/0! error in these cases. + </li> + <li>Not-a-Number (NaN): NaN is used to represent invalid operations + (such as infinity/infinity, infinity-infinity, or the square root of -1). + NaNs allow a program to continue past an invalid operation. + Excel instead immediately generates an error such as #NUM! or #DIV/0!. + </li> + </ol> + <p> + Be aware of these two cases when saving results of your scientific calculations in Excel: + “where are my Infinities and NaNs? They are gone!” + </p> + </section> + <section><title>Testing Framework</title> + <p> + Automated testing of the implemented Function is easy. + The source code for this is in the file: <code>org.apache.poi.hssf.record.formula.GenericFormulaTestCase.java</code>. + This class has a reference to the test xls file (not <em>a</em> test xls, <em>the</em> test xls :) ) + which may need to be changed for your environment. Once you do that, in the test xls, + locate the entry for the function that you have implemented and enter different tests + in a cell in the FORMULA row. Then copy the "value of" the formula that you entered in the + cell just below it (this is easily done in excel as: + [copy the formula cell] > [go to cell below] > Edit > Paste Special > Values > "ok"). + You can enter multiple such formulas and paste their values in the cell below and the + test framework will automatically test if the formula evaluation matches the expected + value (Again, hard to put in words, so if you will, please take time to quickly look + at the code and the currently entered tests in the patch attachment "FormulaEvalTestData.xls" + file). + </p> + <note>This style of testing appears to have been abandoned. This section needs to be completely rewritten.</note> + </section> + </section> + <anchor id="appendixA"/> + <section> + <title>Appendix A — Functions supported by POI</title> + <p> + Functions supported by POI (as of v5.2.0 release) + </p> +<source>ABS +ACOS +ACOSH +ADDRESS +AND +AREAS +ASIN +ASINH +ATAN +ATAN2 +ATANH +AVEDEV +AVERAGE +AVERAGEIFS +BIN2DEC +CEILING +CHAR +CHOOSE +CLEAN +CODE +COLUMN +COLUMNS +COMBIN +COMPLEX +CONCAT +CONCATENATE +COS +COSH +COUNT +COUNTA +COUNTBLANK +COUNTIF +COUNTIFS +DATE +DATEVALUE +DAY +DAYS360 +DEC2BIN +DEC2HEX +DEGREES +DELTA +DEVSQ +DGET +DMAX +DMIN +DOLLAR +DSUM +EDATE +EOMONTH +ERROR.TYPE +EVEN +EXACT +EXP +FACT +FACTDOUBLE +FALSE +FIND +FIXED +FLOOR +FREQUENCY +FV +GEOMEAN +HEX2DEC +HLOOKUP +HOUR +HYPERLINK +IF +IFERROR +IFNA +IFS +IMAGINARY +IMREAL +INDEX +INDIRECT +INT +INTERCEPT +IPMT +IRR +ISBLANK +ISERR +ISERROR +ISEVEN +ISLOGICAL +ISNA +ISNONTEXT +ISNUMBER +ISODD +ISREF +ISTEXT +LARGE +LEFT +LEN +LN +LOG +LOG10 +LOOKUP +LOWER +MATCH +MAX +MAXA +MAXIFS +MDETERM +MEDIAN +MID +MIN +MINA +MINIFS +MINUTE +MINVERSE +MIRR +MMULT +MOD +MODE +MONTH +MROUND +NA +NETWORKDAYS +NOT +NOW +NPER +NPV +OCT2DEC +ODD +OFFSET +OR +PERCENTILE +PERCENTRANK +PERCENTRANK.EXC +PERCENTRANK.INC +PI +PMT +POISSON +POWER +PPMT +PRODUCT +PROPER +PV +QUOTIENT +RADIANS +RAND +RANDBETWEEN +RANK +RATE +REPLACE +REPT +RIGHT +ROMAN +ROUND +ROUNDDOWN +ROUNDUP +ROW +ROWS +SEARCH +SECOND +SIGN +SIN +SINGLE +SINH +SLOPE +SMALL +SQRT +STDEV +SUBSTITUTE +SUBTOTAL +SUM +SUMIF +SUMIFS +SUMPRODUCT +SUMSQ +SUMX2MY2 +SUMX2PY2 +SUMXMY2 +SWITCH +T +T.DIST +T.DIST.2T +T.DIST.RT +TAN +TANH +TDIST +TEXT +TEXTJOIN +TIME +TIMEVALUE +TODAY +TRANSPOSE +TREND +TRIM +TRUE +TRUNC +UPPER +VALUE +VAR +VARP +VLOOKUP +WEEKDAY +WEEKNUM +WORKDAY +XLOOKUP +XMATCH +YEAR +YEARFRAC</source> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/eval.xml b/src/documentation/content/xdocs/components/spreadsheet/eval.xml new file mode 100644 index 0000000000..aee0c38008 --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/eval.xml @@ -0,0 +1,410 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Formula Evaluation</title> + </header> + <body> + <section><title>Introduction</title> + <p>The POI formula evaluation code enables you to calculate the result of + formulas in Excels sheets read-in, or created in POI. This document explains + how to use the API to evaluate your formulas. + </p> + </section> + + <anchor id="WhyEvaluate"/> + <section><title>Why do I need to evaluate formulas?</title> + <p>The Excel file format (both .xls and .xlsx) stores a "cached" result for + every formula along with the formula itself. This means that when the file + is opened, it can be quickly displayed, without needing to spend a long + time calculating all of the formula results. It also means that when reading + a file through Apache POI, the result is quickly available to you too! + </p> + <p>After making changes with Apache POI to either Formula Cells themselves, + or those that they depend on, you should normally perform a Formula + Evaluation to have these "cached" results updated. This is normally done + after all changes have been performed, but before you write the file out. + If you don't do this, there's a good chance that when you open the file in + Excel, until you go to the cell and hit enter or F9, you will either see + the old value or '#VALUE!' for the cell. (Sometimes Excel will notice + itself, and trigger a recalculation on load, but unless you know you are + using volatile functions it's generally best to trigger a <a href="#recalculation">Recalulation</a> + through POI) + </p> + </section> + + <anchor id="Status"/> + <section><title>Status</title> + <p>The code currently provides implementations for all the arithmatic operators. + It also provides implementations for approx. 140 built in + functions in Excel. The framework however makes it easy to add + implementation of new functions. See the <a href="eval-devguide.html"> Formula + evaluation development guide</a> and <a href="../../apidocs/dev/org/apache/poi/hssf/record/formula/functions/package-summary.html">javadocs</a> + for details. </p> + <p> Both HSSFWorkbook and XSSFWorkbook are supported, so you can + evaluate formulas on both .xls and .xlsx files.</p> + <p> User-defined functions are <a href="user-defined-functions.html">supported</a>, + but must be rewritten in Java and registered with the macro-enabled workbook in order to be evaluated. + </p> + </section> + <section><title>User API How-TO</title> + <p>The following code demonstrates how to use the FormulaEvaluator + in the context of other POI excel reading code. + </p> + <p>There are several ways in which you can use the FormulaEvalutator API.</p> + + <anchor id="Evaluate"/> + <section><title>Using FormulaEvaluator.<strong>evaluate</strong>(Cell cell)</title> + <p>This evaluates a given cell, and returns the new value, + without affecting the cell</p> + <source> +FileInputStream fis = new FileInputStream("c:/temp/test.xls"); +Workbook wb = new HSSFWorkbook(fis); //or new XSSFWorkbook("c:/temp/test.xls") +Sheet sheet = wb.getSheetAt(0); +FormulaEvaluator evaluator = wb.getCreationHelper().createFormulaEvaluator(); + +// suppose your formula is in B3 +CellReference cellReference = new CellReference("B3"); +Row row = sheet.getRow(cellReference.getRow()); +Cell cell = row.getCell(cellReference.getCol()); + +CellValue cellValue = evaluator.evaluate(cell); + +switch (cellValue.getCellType()) { + case Cell.CELL_TYPE_BOOLEAN: + System.out.println(cellValue.getBooleanValue()); + break; + case Cell.CELL_TYPE_NUMERIC: + System.out.println(cellValue.getNumberValue()); + break; + case Cell.CELL_TYPE_STRING: + System.out.println(cellValue.getStringValue()); + break; + case Cell.CELL_TYPE_BLANK: + break; + case Cell.CELL_TYPE_ERROR: + break; + + // CELL_TYPE_FORMULA will never happen + case Cell.CELL_TYPE_FORMULA: + break; +} + </source> + <p>Thus using the retrieved value (of type + FormulaEvaluator.CellValue - a nested class) returned + by FormulaEvaluator is similar to using a Cell object + containing the value of the formula evaluation. CellValue is + a simple value object and does not maintain reference + to the original cell. + </p> + </section> + + <anchor id="EvaluateFormulaCell"/> + <section><title>Using FormulaEvaluator.<strong>evaluateFormulaCell</strong>(Cell cell)</title> + <p><strong>evaluateFormulaCell</strong>(Cell cell) + will check to see if the supplied cell is a formula cell. + If it isn't, then no changes will be made to it. If it is, + then the formula is evaluated. The value for the formula + is saved alongside it, to be displayed in excel. The + formula remains in the cell, just with a new value</p> + <p>The return of the function is the type of the + formula result, such as Cell.CELL_TYPE_BOOLEAN</p> + <source> +FileInputStream fis = new FileInputStream("/somepath/test.xls"); +Workbook wb = new HSSFWorkbook(fis); //or new XSSFWorkbook("/somepath/test.xls") +Sheet sheet = wb.getSheetAt(0); +FormulaEvaluator evaluator = wb.getCreationHelper().createFormulaEvaluator(); + +// suppose your formula is in B3 +CellReference cellReference = new CellReference("B3"); +Row row = sheet.getRow(cellReference.getRow()); +Cell cell = row.getCell(cellReference.getCol()); + +if (cell!=null) { + switch (evaluator.evaluateFormulaCell(cell)) { + case Cell.CELL_TYPE_BOOLEAN: + System.out.println(cell.getBooleanCellValue()); + break; + case Cell.CELL_TYPE_NUMERIC: + System.out.println(cell.getNumericCellValue()); + break; + case Cell.CELL_TYPE_STRING: + System.out.println(cell.getStringCellValue()); + break; + case Cell.CELL_TYPE_BLANK: + break; + case Cell.CELL_TYPE_ERROR: + System.out.println(cell.getErrorCellValue()); + break; + + // CELL_TYPE_FORMULA will never occur + case Cell.CELL_TYPE_FORMULA: + break; + } +} + </source> + </section> + + <anchor id="EvaluateInCell"/> + <section><title>Using FormulaEvaluator.<strong>evaluateInCell</strong>(Cell cell)</title> + <p><strong>evaluateInCell</strong>(Cell cell) will check to + see if the supplied cell is a formula cell. If it isn't, + then no changes will be made to it. If it is, then the + formula is evaluated, and the new value saved into the cell, + in place of the old formula.</p> + <source> +FileInputStream fis = new FileInputStream("/somepath/test.xls"); +Workbook wb = new HSSFWorkbook(fis); //or new XSSFWorkbook("/somepath/test.xls") +Sheet sheet = wb.getSheetAt(0); +FormulaEvaluator evaluator = wb.getCreationHelper().createFormulaEvaluator(); + +// suppose your formula is in B3 +CellReference cellReference = new CellReference("B3"); +Row row = sheet.getRow(cellReference.getRow()); +Cell cell = row.getCell(cellReference.getCol()); + +if (cell!=null) { + switch (evaluator.<strong>evaluateInCell</strong>(cell).getCellType()) { + case Cell.CELL_TYPE_BOOLEAN: + System.out.println(cell.getBooleanCellValue()); + break; + case Cell.CELL_TYPE_NUMERIC: + System.out.println(cell.getNumericCellValue()); + break; + case Cell.CELL_TYPE_STRING: + System.out.println(cell.getStringCellValue()); + break; + case Cell.CELL_TYPE_BLANK: + break; + case Cell.CELL_TYPE_ERROR: + System.out.println(cell.getErrorCellValue()); + break; + + // CELL_TYPE_FORMULA will never occur + case Cell.CELL_TYPE_FORMULA: + break; + } +} + + </source> + </section> + + <anchor id="EvaluateAll"/> + <section><title>Re-calculating all formulas in a Workbook</title> + <source> +FileInputStream fis = new FileInputStream("/somepath/test.xls"); +Workbook wb = new HSSFWorkbook(fis); //or new XSSFWorkbook("/somepath/test.xls") +FormulaEvaluator evaluator = wb.getCreationHelper().createFormulaEvaluator(); +for (Sheet sheet : wb) { + for (Row r : sheet) { + for (Cell c : r) { + if (c.getCellType() == Cell.CELL_TYPE_FORMULA) { + evaluator.evaluateFormulaCell(c); + } + } + } +} + </source> + + <p>Alternately, if you know which of HSSF or XSSF you're working + with, then you can call the static + <strong>evaluateAllFormulaCells</strong> method on the appropriate + HSSFFormulaEvaluator or XSSFFormulaEvaluator class.</p> + </section> + </section> + + <anchor id="recalculation"/> + <section><title>Recalculation of Formulas</title> + <p> + In certain cases you may want to force Excel to re-calculate formulas when the workbook is opened. + Consider the following example: + </p> + <p> + Open Excel and create a new workbook. On the first sheet set A1=1, B1=1, C1=A1+B1. + Excel automatically calculates formulas and the value in C1 is 2. So far so good. + </p> + <p> + Now modify the workbook with POI: + </p> + <source> + Workbook wb = WorkbookFactory.create(new FileInputStream("workbook.xls")); + + Sheet sh = wb.getSheetAt(0); + sh.getRow(0).getCell(0).setCellValue(2); // set A1=2 + + FileOutputStream out = new FileOutputStream("workbook2.xls"); + wb.write(out); + out.close(); + </source> + <p> + Now open workbook2.xls in Excel and the value in C1 is still 2 while you expected 3. Wrong? No! + The point is that Excel caches previously calculated results and you need to trigger recalculation to updated them. + It is not an issue when you are creating new workbooks from scratch, but important to remember when you are modifing + existing workbooks with formulas. This can be done in two ways: + </p> + <p> + 1. Re-evaluate formulas with POI's FormulaEvaluator: + </p> + <source> + Workbook wb = WorkbookFactory.create(new FileInputStream("workbook.xls")); + + Sheet sh = wb.getSheetAt(0); + sh.getRow(0).getCell(0).setCellValue(2); // set A1=2 + + wb.getCreationHelper().createFormulaEvaluator().evaluateAll(); + </source> + <p> + 2. Delegate re-calculation to Excel. The application will perform a full recalculation when the workbook is opened: + </p> + <source> + Workbook wb = WorkbookFactory.create(new FileInputStream("workbook.xls")); + + Sheet sh = wb.getSheetAt(0); + sh.getRow(0).getCell(0).setCellValue(2); // set A1=2 + + wb.setForceFormulaRecalculation(true); + </source> + </section> + + <anchor id="external"/> + <section><title>External (Cross-Workbook) references</title> + <p>It is possible for a formula in an Excel spreadsheet to + refer to a Named Range or Cell in a different workbook. + These cross-workbook references are normally called <em>External + References</em>. These are formulas which look something like:</p> + <source> + =SUM([Finances.xlsx]Numbers!D10:D25) + =SUM('C:\Data\[Finances.xlsx]Numbers'!D10:D25) + =SUM([Finances.xlsx]Range20) + </source> + <p>If you don't have access to these other workbooks, then you + should call + <a href="../../apidocs/dev/org/apache/poi/ss/usermodel/FormulaEvaluator.html#setIgnoreMissingWorkbooks(boolean)">setIgnoreMissingWorkbooks(true)</a> + to tell the Formula Evaluator to skip evaluating any external + references it can't look up.</p> + <p>In order for POI to be able to evaluate external references, it + needs access to the workbooks in question. As these don't necessarily + have the same names on your system as in the workbook, you need to + give POI a map of external references to open workbooks, through + the + <a href="../../apidocs/dev/org/apache/poi/ss/usermodel/FormulaEvaluator.html#setupReferencedWorkbooks(java.util.Map)">setupReferencedWorkbooks(java.util.Map<java.lang.String,FormulaEvaluator> workbooks)</a> + method. You should normally do something like:</p> + <source> +// Create a FormulaEvaluator to use +FormulaEvaluator mainWorkbookEvaluator = workbook.getCreationHelper().createFormulaEvaluator(); + +// Track the workbook references +Map<String,FormulaEvaluator> workbooks = new HashMap<String, FormulaEvaluator>(); +// Add this workbook +workbooks.put("report.xlsx", mainWorkbookEvaluator); +// Add two others +workbooks.put("input.xls", WorkbookFactory.create("C:\\temp\\input22.xls").getCreationHelper().createFormulaEvaluator()); +workbooks.put("lookups.xlsx", WorkbookFactory.create("/home/poi/data/tmp-lookups.xlsx").getCreationHelper().createFormulaEvaluator()); + +// Attach them +mainWorkbookEvaluator.setupReferencedWorkbooks(workbooks); + +// Evaluate +mainWorkbookEvaluator.evaluateAll(); + </source> + </section> + + <anchor id="Performance"/> + <section><title>Performance Notes</title> + <ul> + <li>Generally you should have to create only one FormulaEvaluator + instance per Workbook. The FormulaEvaluator will cache + evaluations of dependent cells, so if you have multiple + formulas all depending on a cell then subsequent evaluations + will be faster. + </li> + <li>You should normally perform all of your updates to cells, + before triggering the evaluation, rather than doing one + cell at a time. By waiting until all the updates/sets are + performed, you'll be able to take best advantage of the caching + for complex formulas. + </li> + <li>If you do end up making changes to cells part way through + evaluation, you should call <em>notifySetFormula</em> or + <em>notifyUpdateCell</em> to trigger suitable cache clearance. + Alternately, you could instantiate a new FormulaEvaluator, + which will start with empty caches. + </li> + <li>Also note that FormulaEvaluator maintains a reference to + the sheet and workbook, so ensure that the evaluator instance + is available for garbage collection when you are done with it + (in other words don't maintain long lived reference to + FormulaEvaluator if you don't really need to - unless + all references to the sheet and workbook are removed, these + don't get garbage collected and continue to occupy potentially + large amounts of memory). + </li> + <li>CellValue instances however do not maintain reference to the + Cell or the sheet or workbook, so these can be long-lived + objects without any adverse effect on performance. + </li> + </ul> + </section> + <section><title>Formula Evaluation Debugging</title> + <p>POI is not perfect and you may stumble across formula evaluation problems (Java exceptions + or just different results) in your special use case. To support an easy detailed analysis, a special + logging of the full evaluation is provided.</p> + <p>POI 5.1.0 and above uses <a href="https://logging.apache.org/log4j/2.x/">Log4J 2.x</a> as a logging framework. Try to set up a logging + configuration that lets you see the info and other log messages.</p> + <p>Example use:</p> + <source> + // open your file + Workbook wb = new HSSFWorkbook(new FileInputStream("foobar.xls")); + FormulaEvaluator evaluator = wb.getCreationHelper().createFormulaEvaluator(); + + // get your cell + Cell cell = wb.getSheet(0).getRow(0).getCell(0); // just a dummy example + + // perform debug output for the next evaluate-call only + evaluator.setDebugEvaluationOutputForNextEval(true); + evaluator.evaluateFormulaCell(cell); + evaluator.evaluateFormulaCell(cell); // no logging performed for this next evaluate-call + </source> + <p>The special Logger called "POI.FormulaEval" is used (useful if you use the CommonsLogger and a detailed logging configuration). + The used log levels are WARN and INFO (for detailed parameter info and results) - the level are so high to allow this + special logging without being disturbed by the bunch of DEBUG log entries from other classes.</p> + </section> + + <anchor id="sxssf"/> + <section><title>Formula Evaluation and SXSSF</title> + <p>For versions before 3.13 final, no formula evaluation is possible with + SXSSF.</p> + <p>If you are using POI 3.13 final or newer, formula evaluation is possible with SXSSF, + but with some caveats.</p> + <p>The biggest restriction is that, since evaluating a cell needs that cell in memory + and any others it depends on, only pure-function formulas and formulas referencing + nearby cells can be evaluated with SXSSF. If a formula references a cell that hasn't + yet been written, or one which has already been flushed to disk, then it won't be + possible to evaluate it.</p> + <p>Because of this, a call to <em>wb.getCreationHelper().createFormulaEvaluator().evaluateAll();</em> + will very rarely work on SXSSF, as it's very rare that all the cells wil be available + and in memory at any time! Instead, it is suggested to evaluate formula cells just + after writing them, or shortly after when cells they depend on are added. Just make + sure that all cells needing or needed for evaluation are inside the window.</p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/examples.xml b/src/documentation/content/xdocs/components/spreadsheet/examples.xml new file mode 100644 index 0000000000..87feff0b59 --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/examples.xml @@ -0,0 +1,274 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>HSSF and XSSF Examples</title> + <authors> + <person id="YK" name="Yegor Kozlov" email="user@poi.apache.org"/> + </authors> + </header> + <body> + <section><title>HSSF and XSSF common examples</title> + <p>Apache POI comes with a number of examples that demonstrate how you + can use the POI API to create documents from "real life". + The examples below based on common XSSF-HSSF interfaces so that you + can generate either *.xls or *.xlsx output just by setting a + command-line argument: + </p> + <source> + BusinessPlan -xls + or + BusinessPlan -xlsx + </source> + <p>All sample source is available in <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/">SVN</a></p> + <p>In addition, there are a handful of + <a href="#hssf-only">HSSF only</a> and + <a href="#xssf-only">XSSF only</a> examples as well. + </p> + + <section><title>Available Examples</title> + <p> + The following examples are available: + </p> + <ul> + <li><a href="#ss-common">Common HSSF and XSSF</a><ul> + <li><a href="#business-plan">Business Plan</a></li> + <li><a href="#calendar">Calendar</a></li> + <li><a href="#loan-calculator">Loan Calculator</a></li> + <li><a href="#timesheet">Timesheet</a></li> + <li><a href="#conditional-formats">Conditional Formats</a></li> + <li><a href="#common-formulas">Formula Examples</a></li> + <li><a href="#add-dimensioned-image">Add Dimensioned Image</a></li> + <li><a href="#aligned-cells">Aligned Cells</a></li> + <li><a href="#cell-style-details">Cell Style Details</a></li> + <li><a href="#linked-dropdown">Linked Dropdown Lists</a></li> + <li><a href="#performance-test">Common SS Performance Test</a></li> + <li><a href="#to-html">To HTML</a></li> + <li><a href="#to-csv">To CSV</a></li> + </ul></li> + <li><a href="#hssf-only">HSSF-Only</a></li> + <li><a href="#xssf-only">XSSF-Only</a></li> + </ul> + </section> + + <anchor id="ss-common" /> + <anchor id="business-plan" /> + <section><title>Business Plan</title> + <p> The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/BusinessPlan.java">BusinessPlan</a> + application creates a sample business plan with three phases, weekly iterations and time highlighting. Demonstrates advanced cell formatting + (number and date formats, alignments, fills, borders) and various settings for organizing data in a sheet (freezed panes, grouped rows). + </p> + <figure src="images/businessplan.jpg" alt="business plan demo"/> + </section> + + <anchor id="calendar" /> + <section><title>Calendar</title> + <p> The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/CalendarDemo.java">Calendar</a> + demo creates a multi sheet calendar. Each month is on a separate sheet. + </p> + <figure src="images/calendar.jpg" alt="calendar demo"/> + </section> + + <anchor id="loan-calculator" /> + <section><title>Loan Calculator</title> + <p> The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/LoanCalculator.java">LoanCalculator</a> + demo creates a simple loan calculator. Demonstrates advance usage of cell formulas and named ranges. + </p> + <figure src="images/loancalc.jpg" alt="loan calculator demo"/> + </section> + + <anchor id="timesheet" /> + <section><title>Timesheet</title> + <p> The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/TimesheetDemo.java">Timesheet</a> + demo creates a weekly timesheet with automatic calculation of total hours. Demonstrates advance usage of cell formulas. + </p> + <figure src="images/timesheet.jpg" alt="timesheet demo"/> + </section> + + <anchor id="conditional-formats" /> + <section><title>Conditional Formats</title> + <p> The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/ConditionalFormats.java">ConditionalFormats</a> + demo is a collection of short examples showing what you can do with Excel conditional formatting in POI: + </p> + <ul> + <li>Highlight cells based on their values</li> + <li>Highlight a range of cells based on a formula</li> + <li>Hide errors</li> + <li>Hide the duplicate values</li> + <li>Highlight duplicate entries in a column</li> + <li>Highlight items that are in a list on the worksheet</li> + <li>Highlight payments that are due in the next thirty days</li> + <li>Shade alternating rows on the worksheet</li> + <li>Shade bands of rows on the worksheet</li> + </ul> + </section> + + <anchor id="common-formulas" /> + <section><title>Formula Examples</title> + <p>The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/formula/CalculateMortgage.java">CalculateMortgage</a> + example demonstrates a simple user-defined function to calculate + principal and interest.</p> + <p>The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/formula/CheckFunctionsSupported.java">CheckFunctionsSupported</a> + example shows how to test what functions and formulas aren't + supported from a given file.</p> + <p>The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/formula/SettingExternalFunction.java">SettingExternalFunction</a> + example demonstrates how to use externally provided (third-party) + formula add-ins.</p> + <p>The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/formula/UserDefinedFunctionExample.java">UserDefinedFunctionExample</a> + example demonstrates how to invoke a User Defined Function for a + given Workbook instance using POI's UDFFinder implementation.</p> + </section> + + <anchor id="add-dimensioned-image" /> + <section><title>Add Dimensioned Image</title> + <p>The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/AddDimensionedImage.java">AddDimensionedImage</a> + example demonstrates how to add an image to a worksheet and set that + images size to a specific number of millimetres irrespective of the + width of the columns or height of the rows.</p> + </section> + + <anchor id="aligned-cells" /> + <section><title>Aligned Cells</title> + <p>The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/AligningCells.java">AligningCells</a> + example demonstrates how various alignment options work.</p> + </section> + + <anchor id="cell-style-details" /> + <section><title>Cell Style Details</title> + <p>The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/CellStyleDetails.java">CellStyleDetails</a> + example demonstrates how to read excel styles for cells.</p> + </section> + + <anchor id="linked-dropdown" /> + <section><title>Linked Dropdown Lists</title> + <p>The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/LinkedDropDownLists.java">LinkedDropDownLists</a> + example demonstrates one technique that may be used to create linked + or dependent drop down lists.</p> + </section> + + <anchor id="performance-test" /> + <section><title>Common SS Performance Test</title> + <p>The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/SSPerformanceTest.java">SSPerformanceTest</a> + example provides a way to create simple example files of varying + sizes, and to calculate how long they take. Useful for benchmarking + your system, and to also test if slow performance is due to Apache + POI itself or to your own code.</p> + </section> + + <anchor id="to-html" /> + <section><title>ToHtml</title> + <p> The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/html/ToHtml.java">ToHtml</a> + example shows how to display a spreadsheet in HTML using the classes for spreadsheet display. + </p> + </section> + + <anchor id="to-csv" /> + <section><title>ToCSV</title> + <p>The <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/ToCSV.java">ToCSV</a> + example demonstrates <em>one</em> way to convert an Excel spreadsheet into a CSV file. + </p> + </section> + </section> + + <anchor id="hssf-only" /> + <section><title>HSSF-only Examples</title> + <p>All the HSSF-only examples can be found in + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/">SVN</a></p> + <ul> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/CellComments.java">CellComments</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/HyperlinkFormula.java">HyperlinkFormula</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/EventExample.java">EventExample</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/OfficeDrawingWithGraphics.java">OfficeDrawingWithGraphics</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/CreateDateCells.java">CreateDateCells</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/NewWorkbook.java">NewWorkbook</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/EmeddedObjects.java">EmeddedObjects</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/Hyperlinks.java">Hyperlinks</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/OfficeDrawing.java">OfficeDrawing</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/HSSFReadWrite.java">HSSFReadWrite</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/NewSheet.java">NewSheet</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/SplitAndFreezePanes.java">SplitAndFreezePanes</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/InCellLists.java">InCellLists</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/RepeatingRowsAndColumns.java">RepeatingRowsAndColumns</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/MergedCells.java">MergedCells</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/CellTypes.java">CellTypes</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/ZoomSheet.java">ZoomSheet</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/ReadWriteWorkbook.java">ReadWriteWorkbook</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/CreateCells.java">CreateCells</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/Alignment.java">Alignment</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/FrillsAndFills.java">FrillsAndFills</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/AddDimensionedImage.java">AddDimensionedImage</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/Borders.java">Borders</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/NewLinesInCells.java">NewLinesInCells</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/WorkingWithFonts.java">WorkingWithFonts</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/BigExample.java">BigExample</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/Outlines.java">Outlines</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/eventusermodel/XLS2CSVmra.java">XLS2CSVmra</a></li> + </ul> + </section> + + <anchor id="xssf-only" /> + <section><title>XSSF-only Examples</title> + <p>All the XSSF-only examples can be found in + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/">SVN</a></p> + <ul> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/CellComments.java">CellComments</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/HeadersAndFooters.java">HeadersAndFooters</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/CreateUserDefinedDataFormats.java">CreateUserDefinedDataFormats</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/CreatePivotTable.java">CreatePivotTable</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/CreatePivotTable2.java">CreatePivotTable2</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/FillsAndColors.java">FillsAndColors</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/WorkingWithBorders.java">WorkingWithBorders</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/BigGridDemo.java">BigGridDemo</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/CreateTable.java">CreateTable</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/CalendarDemo.java">CalendarDemo</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/AligningCells.java">AligningCells</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/SplitAndFreezePanes.java">SplitAndFreezePanes</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/WorkingWithPageSetup.java">WorkingWithPageSetup</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/WorkingWithPictures.java">WorkingWithPictures</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/MergingCells.java">MergingCells</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/CustomXMLMapping.java">CustomXMLMapping</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/SelectedSheet.java">SelectedSheet</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/EmbeddedObjects.java">EmbeddedObjects</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/WorkbookProperties.java">WorkbookProperties</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/NewLinesInCells.java">NewLinesInCells</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/Outlining.java">Outlining</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/CreateCell.java">CreateCell</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/IterateCells.java">IterateCells</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/BarChart.java">BarChart</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/BarAndLineChart.java">BarAndLineChart</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/LineChart.java">LineChart</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/ScatterChart.java">ScatterChart</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/WorkingWithFonts.java">WorkingWithFonts</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/HyperlinkExample.java">HyperlinkExample</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/ShiftRows.java">ShiftRows</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/WorkingWithRichText.java">WorkingWithRichText</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/usermodel/FitSheetToOnePage.java">FitSheetToOnePage</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/HybridStreaming.java">HybridStreaming</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/Outlining.java">Outlining (SXSSF output)</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/DeferredGeneration.java">DeferredGeneration (SXSSF output)</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/SavePasswordProtectedXlsx.java">SavePasswordProtectedXlsx (SXSSF output)</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/eventusermodel/XLSX2CSV.java">XLSX2CSV (streaming read)</a></li> + <li><a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/eventusermodel/FromHowTo.java">FromHowTo (streaming read)</a></li> + </ul> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/excelant.xml b/src/documentation/content/xdocs/components/spreadsheet/excelant.xml new file mode 100644 index 0000000000..01e03c3213 --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/excelant.xml @@ -0,0 +1,317 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>ExcelAnt - Ant Tasks for Validating Excel Spreadsheets</title> + <authors> + <person email="jon@loquatic.com" name="Jon Svede" id="JDS"/> + <person email="brian.bush@nrel.gov" name="Brian Bush" id="BWB"/> + </authors> + </header> + <body> + <section><title>ExcelAnt - Ant Tasks for Validating Excel Spreadsheets</title> + + <section><title>Introduction</title> + <p>ExcelAnt is a set of Ant tasks that make it possible to verify or test + a workbook without having to write Java code. Of course, the tasks themselves + are written in Java, but to use this framework you only need to know a little + bit about Ant.</p> + <p>This document covers the basic usage and set up of ExcelAnt.</p> + <p>This document will assume basic familiarity with Ant and Ant build files.</p> + </section> + <section><title>Setup</title> + <p>To start with ExcelAnt, you'll need to have the POI 3.8 or higher jar files. If you test only .xls +workbooks then you need to have the following jars in your path:</p> + <ul> + <li>poi-excelant-$version-YYYYDDMM.jar</li> + <li>poi-$version-YYYYDDMM.jar</li> + <li>poi-ooxml-$version-YYYYDDMM.jar</li> + </ul> + <p> If you evaluate .xlsx workbooks then you need to add these: </p> + <ul> + <li>poi-ooxml-lite-$version-YYYYDDMM.jar</li> + <li>xmlbeans.jar</li> + </ul> + <p>For example, if you have these jars in a lib/ dir in your project, your build.xml + might look like this:</p> +<source><![CDATA[ +<property name="lib.dir" value="lib" /> + +<path id="excelant.path"> + <pathelement location="${lib.dir}/poi-excelant-3.8-beta1-20101230.jar" /> + <pathelement location="${lib.dir}/poi-3.8-beta1-20101230.jar" /> + <pathelement location="${lib.dir}/poi-ooxml-3.8-beta1-20101230.jar" /> +</path> +]]></source> + <p>Next, you'll need to define the Ant tasks. There are several ways to use ExcelAnt:</p> + +<ul><li>The traditional way:</li></ul> +<source><![CDATA[ + <typedef resource="org/apache/poi/ss/excelant/antlib.xml" classpathref="excelant.path" /> +]]></source> +<p> + Where excelant.path refers to the classpath with POI jars. + Using this approach the provided extensions will live in the default namespace. Note that the default task/typenames (evaluate, test) may be too generic and should either be explicitly overridden or used with a namespace. +</p> +<ul><li>Similar, but assigning a namespace URI:</li></ul> +<source><![CDATA[ +<project name="excelant-demo" xmlns:poi="antlib:org.apache.poi.ss.excelant"> + + <typedef resource="org/apache/poi/ss/excelant/antlib.xml" + classpathref="excelant.classpath" + uri="antlib:org.apache.poi.ss.excelant"/> + + <target name="test-nofile"> + <poi:excelant> + + </poi:excelant> + </target> +</project> +]]></source> + </section> + + <section><title>A Simple Example</title> + <p>The simplest example of using Excel is the ability to validate that POI is giving you back + the value you expect it to. Does this mean that POI is inaccurate? Hardly. There are cases + where POI is unable to evaluate cells for a variety of reasons. If you need to write code + to integrate a worksheet into an app, you may want to know that it's going to work before + you actually try to write that code. ExcelAnt helps with that.</p> + + <p>Consider the <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/excelant/simple-mortgage-calculation.xls">mortgage-calculation.xls</a> + file found in the Examples (link broken / file is missing). This sheet is shown below:</p> + + <figure src="images/simple-xls-with-function.jpg" alt="mortgage calculation spreadsheet"/> + + <p>This sheet calculates the principal and interest payment for a mortgage based + on the amount of the loan, term and rate. To write a simple ExcelAnt test you + need to tell ExcelAnt about the file like this:</p> +<source><![CDATA[ +<property name="xls.file" value="" /> + +<target name="simpleTest"> + <excelant fileName="${xls.file}"> + <test name="checkValue" showFailureDetail="true"> + <evaluate showDelta="true" cell="'MortgageCalculator'!$B$4" expectedValue="790.7936" precision="1.0e-4" /> + </test> + </excelant> +</target> +]]></source> + + + <p>This code sets up ExcelAnt to access the file defined in the ant property + xls.file. Then it creates a 'test' named 'checkValue'. Finally it tries + to evaluate the B4 on the sheet named 'MortgageCalculator'. There are some assumptions + here that are worth explaining. For starters, ExcelAnt is focused on the testing + numerically oriented sheets. The <evaluate> task is actually evaluating the + cell as a formula using a FormulaEvaluator instance from POI. Therefore it will fail + if you point it to a cell that doesn't contain a formula or a test a plain old number.</p> + + <p>Having said all that, here is what the output looks like:</p> + +<source><![CDATA[ +simpleTest: + [excelant] ExcelAnt version 0.4.0 Copyright 2011 + [excelant] Using input file: resources/excelant.xls + [excelant] 1/1 tests passed. +BUILD SUCCESSFUL +Total time: 391 milliseconds +]]></source> + + </section> + + <section><title>Setting Values into a Cell</title> + <p>So now we know that at a minimum POI can use our sheet to calculate the existing value. + This is an important point: in many cases sheets have dependencies, i.e., cells they reference. + As is often the case, these cells may have dependencies, which may have dependencies, etc. + The point is that sometimes a dependent cell may get adjusted by a macro or a function + and it may be that POI doesn't have the capabilities to do the same thing. This test + verifies that we can rely on POI to retrieve the default value, based on the stored values + of the sheet. Now we want to know if we can manipulate those dependencies and verify + the output.</p> + + <p>To verify that we can manipulate cell values, we need a way in ExcelAnt to set a value. + This is provided by the following task types:</p> + <ul> + <li>setDouble() - sets the specified cell as a double.</li> + <li>setFormula() - sets the specified cell as a formula.</li> + <li>setString() = sets the specified cell as a String.</li> + </ul> + + <p>For the purposes of this example we'll use the <setDouble> task. Let's + start with a $240,000, 30 year loan at 11% (let's pretend it's like 1984). Here + is how we will set that up:</p> + +<source><![CDATA[ + <setDouble cell="'MortgageCalculator'!$B$1" value="240000"/> + <setDouble cell="'MortgageCalculator'!$B$2" value ="0.11"/> + <setDouble cell="'MortgageCalculator'!$B$3" value ="30"/> + <evaluate showDelta="true" cell="'MortgageCalculator'!$B$4" expectedValue="2285.576149" precision="1.0e-4" /> +]]></source> + + <p>Don't forget that we're verifying the behavior so you need to put all this + into the sheet. That is how I got the result of $2,285 and change. So save your + changes and run it; you should get the following: </p> + +<source><![CDATA[ +Buildfile: C:\opt\eclipse\workspaces\excelant\excelant.examples\build.xml +simpleTest: + [excelant] ExcelAnt version 0.4.0 Copyright 2011 + [excelant] Using input file: resources/excelant.xls + [excelant] 1/1 tests passed. +BUILD SUCCESSFUL +Total time: 406 milliseconds +]]></source> + +</section> + + <section><title>Getting More Details</title> + + <p>This is great, it's working! However, suppose you want to see a little more detail. The + ExcelAnt tasks leverage the Ant logging so you can add the -verbose and -debug flags to + the Ant command line to get more detail. Try adding -verbose. Here is what + you should see:</p> + +<source><![CDATA[ +simpleTest: + [excelant] ExcelAnt version 0.4.0 Copyright 2011 + [excelant] Using input file: resources/excelant.xls + [evaluate] test precision = 1.0E-4 global precision = 0.0 + [evaluate] Using evaluate precision of 1.0E-4 + [excelant] 1/1 tests passed. +BUILD SUCCESSFUL +Total time: 406 milliseconds +]]></source> + + + <p>We see a little more detail. Notice that we see that there is a setting for global precision. + Up until now we've been setting the precision on each evaluate that we call. This + is obviously useful but it gets cumbersome. It would be better if there were a way + that we could specify a global precision - and there is. There is a <precision> + tag that you can specify as a child of the <excelant> tag. Let's go back to + our original task we set up earlier and modify it:</p> + +<source><![CDATA[ +<property name="xls.file" value="" /> + +<target name="simpleTest"> + <excelant fileName="${xls.file}"> + <precision value="1.0e-3"/> + <test name="checkValue" showFailureDetail="true"> + <evaluate showDelta="true" cell="'MortgageCalculator'!$B$4" expectedValue="790.7936" /> + </test> + </excelant> +</target> +]]></source> + + <p>In this example we have set the global precision to 1.0e-3. This means that + in the absence of something more stringent, all tests in the task will use + the global precision. We can still override this by specifying the + precision attribute of all of our <evaluate> task. Let's first run + this task with the global precision and the -verbose flag:</p> + +<source><![CDATA[ +simpleTest: +[excelant] ExcelAnt version 0.4.0 Copyright 2011 +[excelant] Using input file: resources/excelant.xls +[excelant] setting precision for the test checkValue + [test] setting globalPrecision to 0.0010 in the evaluator +[evaluate] test precision = 0.0 global precision = 0.0010 +[evaluate] Using global precision of 0.0010 +[excelant] 1/1 tests passed. +]]></source> + + + <p>As the output clearly shows, the test itself has no precision but there is + the global precision. Additionally, it tells us we're going to use that + more stringent global value. Now suppose that for this test we want + to use a more stringent precision, say 1.0e-4. We can do that by adding + the precision attribute back to the <evaluate> task:</p> + +<source><![CDATA[ +<excelant fileName="${xls.file}"> + <precision value="1.0e-3"/> + <test name="checkValue" showFailureDetail="true"> + <setDouble cell="'MortgageCalculator'!$B$1" value="240000"/> + <setDouble cell="'MortgageCalculator'!$B$2" value ="0.11"/> + <setDouble cell="'MortgageCalculator'!$B$3" value ="30"/> + <evaluate showDelta="true" cell="'MortgageCalculator'!$B$4" expectedValue="2285.576149" precision="1.0e-4" /> + </test> +</excelant> +]]></source> + + + <p>Now when you re-run this test with the verbose flag you will see that + your test ran and passed with the higher precision:</p> +<source><![CDATA[ +simpleTest: + [excelant] ExcelAnt version 0.4.0 Copyright 2011 + [excelant] Using input file: resources/excelant.xls + [excelant] setting precision for the test checkValue + [test] setting globalPrecision to 0.0010 in the evaluator + [evaluate] test precision = 1.0E-4 global precision = 0.0010 + [evaluate] Using evaluate precision of 1.0E-4 over the global precision of 0.0010 + [excelant] 1/1 tests passed. +BUILD SUCCESSFUL +Total time: 390 milliseconds +]]></source> + </section> + + <section><title>Leveraging User Defined Functions</title> + <p>POI has an excellent feature (besides ExcelAnt) called <a href="user-defined-functions.html">User Defined Functions</a>, + that allows you to write Java code that will be used in place of custom VB + code or macros is a spreadsheet. If you have read the documentation and written + your own FreeRefFunction implmentations, ExcelAnt can make use of this code. + For each <excelant> task you define you can nest a <udf> tag + which allows you to specify the function alias and the class name.</p> + + <p>Consider the previous example of the mortgage calculator. What if, instead + of being a formula in a cell, it was a function defined in a VB macro? As luck + would have it, we already have an example of this in the examples from the + User Defined Functions example, so let's use that. In the example spreadsheet + there is a tab for MortgageCalculatorFunction, which will use. If you look in + cell B4, you see that rather than a messy cell based formula, there is only the function + call. Let's not get bogged down in the function/Java implementation, as these + are covered in the User Defined Function documentation. Let's just add + a new target and test to our existing build file:</p> +<source><![CDATA[ + <target name="functionTest"> + <excelant fileName="${xls.file}"> + <udf functionAlias="calculatePayment" class="org.apache.poi.ss.examples.formula.CalculateMortgage"/> + <precision value="1.0e-3"/> + <test name="checkValue" showFailureDetail="true"> + <setDouble cell="'MortgageCalculator'!$B$1" value="240000"/> + <setDouble cell="'MortgageCalculator'!$B$2" value ="0.11"/> + <setDouble cell="'MortgageCalculator'!$B$3" value ="30"/> + <evaluate showDelta="true" cell="'MortgageCalculatorFunction'!$B$4" expectedValue="2285.576149" precision="1.0e-4" /> + </test> + </excelant> + </target> +]]></source> + + <p>So if you look at this carefully it looks the same as the previous examples. We + still use the global precision, we're still setting values, and we still want + to evaluate a cell. The only real differences are the sheet name and the + addition of the function.</p> + </section> + </section> +</body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/formula.xml b/src/documentation/content/xdocs/components/spreadsheet/formula.xml new file mode 100644 index 0000000000..3e2ed30647 --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/formula.xml @@ -0,0 +1,120 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Formula Support</title> + <authors> + <person email="avik@apache.org" name="Avik Sengupta" id="AS"/> + </authors> + </header> + <body> + <section><title>Introduction</title> + <p> + This document describes the current state of formula support in POI. + The information in this document currently applies to the 3.13 version of POI. + Since this area is a work in progress, this document will be updated with new + features as and when they are added. + </p> + + </section> + <section><title>The basics</title> + <p> + In org.apache.poi.ss.usermodel.Cell + <strong> setCellFormula("formulaString") </strong> is used to add a + formula to a sheet, and <strong> getCellFormula() </strong> is used to retrieve + the string representation of a formula. + </p> + <p> + We aim to support the complete excel grammar for formulas. Thus, the string that + you pass in to the <em> setCellFormula </em> call should be what you expect to + type into excel. Also, note that you should NOT add a "=" to the front of the string. + </p> + <p> + Please note that localized versions of Excel allow to enter localized + function-names. However internally Excel stores the English names and thus POI + only supports these and not the localized ones. Also note that only commas may be + used to separate arguments, as per the Excel English style, alternate delimeters + used in other localizations are not supported. + </p> + </section> + <section><title>Supported Features</title> + <ul> + <li>References: single cell & area, 2D & 3D, relative & absolute</li> + <li>Literals: number, text, boolean, error and array</li> + <li>Operators: arithmetic and logical, some region operators</li> + <li>Built-in functions: over 350 recognised, 280 evaluatable</li> + <li>Add-in functions: 24 from Analysis Toolpack</li> + <li>Array Formulas: via Sheet.setArrayFormula() and Sheet.removeArrayFormula()</li> + <li>Region operators: union, intersection</li> + </ul> + </section> + <section><title>Not yet supported</title> + <ul> + <li>Manipulating table formulas (In Excel, formulas that look like "{=...}" as opposed to "=...")</li> + <li>Parsing of previously uncalled add-in functions</li> + <li>Preservation of whitespace in formulas (when POI manipulates them)</li> + </ul> + </section> + + <section><title>Supported Functions</title> + <p>To get the list of formula functions that POI supports, you need to + call some code!</p> + <p>The methods you need are available on + <a href="../../apidocs/dev/org/apache/poi/ss/formula/eval/FunctionEval.html">org.apache.poi.ss.formula.eval.FunctionEval</a>. + To find which functions your copy of Apache POI supports, use + <a href="../../apidocs/dev/org/apache/poi/ss/formula/eval/FunctionEval.html#getSupportedFunctionNames()">getSupportedFunctionNames()</a> + to get a list of the implemented function names. For the list of functions that + POI knows the name of, but doesn't currently implement, use + <a href="../../apidocs/dev/org/apache/poi/ss/formula/eval/FunctionEval.html#getNotSupportedFunctionNames()">getNotSupportedFunctionNames()</a> + </p> + </section> + + <section><title>Internals</title> + <p> + Formulas in Excel are stored as sequences of tokens in Reverse Polish Notation order. The + <a href="https://sc.openoffice.org/excelfileformat.pdf">open office XLS spec</a> is the best + documentation you will find for the format. + </p> + + <p> + The tokens used by excel are modeled as individual *Ptg classes in the <strong> + org.apache.poi.hssf.record.formula</strong> package. + </p> + <p> + The task of parsing a formula string into an array of RPN ordered tokens is done by the <strong> + org.apache.poi.ss.formula.FormulaParser</strong> class. This class implements a hand + written recursive descent parser. + </p> + <p> + Formula tokens in Excel are stored in one of three possible <em> operand classes </em>: + Reference, Value and Array. Based on the location of a token, its class can change + in complicated and undocumented ways. While we have support for most cases, we + are not sure if we have covered all bases (since there is no documentation for this area.) + We would therefore like you to report any + occurrence of #VALUE! in a cell upon opening a POI generated workbook in excel. (Check that + typing the formula into Excel directly gives a valid result.) + </p> + <p>Check out the <a href="site:javadocs">javadocs </a> for details. + </p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/hacking-hssf.xml b/src/documentation/content/xdocs/components/spreadsheet/hacking-hssf.xml new file mode 100644 index 0000000000..784aafbf22 --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/hacking-hssf.xml @@ -0,0 +1,89 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Hacking HSSF</title> + <authors> + <person email="user@poi.apache.org" name="Glen Stampoultzis" id="GJS"/> + <person email="acoliver@apache.org" name="Andrew Oliver" id="AO"/> + </authors> + </header> + <body> + <section><title>Where Can I Find Documentation on Feature X</title> + <p> + You might find the + 'Excel 97 Developer's Kit' (out of print, Microsoft Press, no + restrictive covenants, available on Amazon.com) helpful for + understanding the file format. + </p> + <p> + Also useful is the <a href="https://sc.openoffice.org/excelfileformat.pdf">open office XLS spec</a>. We + are collaborating with the maintainer of the spec so if you think you can add something to their + document just send through your changes. + </p> + </section> + <section><title>Help, I Can't Find Feature X Documented Anywhere</title> + <ol> + <li> + Look at OpenOffice.org or Gnumeric sources if its implemented there. + </li> + <li> + Use org.apache.poi.hssf.dev.BiffViewer to view the structure of the + file. Experiment by adding one criteria entry at a time. See what it + does to the structure, infer behavior and structure from it. Using the + unix diff command (or get cygwin from www.cygwin.com for windows) you + can figure out a lot very quickly. Unimplemented records show up as + 'UNKNOWN' and prints a hex dump. + </li> + </ol> + </section> + <section><title>Low-level Record Generation</title> + <p> + Low level records can be time consuming to created. We created a record + generator to help generate some of the simpler tasks. + </p> + <p> + We use XML + descriptors to generate the Java code (which sure beats the heck out of + the PERL scripts originally used ;-) for low level records. The + generator is kinda alpha-ish right now and could use some enhancement, + so you may find that to be about 1/2 of the work. Notice this is in + org.apache.poi.hssf.record.definitions. + </p> + </section> + <section><title>Important Notice</title> + <p>One thing to note: If you are making a large code contribution we need to ensure + any participants in this process have never + signed a "Non Disclosure Agreement" with Microsoft, and have not + received any information covered by such an agreement. If they have + they'll not be able to participate in the POI project. For large contributions we + may ask you to sign an agreement.</p> + </section> + <section><title>What Can I Work On?</title> + <p>Ask in the dev mailing list for advice.</p> + </section> + <section><title>What Else Should I Know?</title> + <p>Make sure you <a href="site:guidelines">read the contributing section</a> + as it contains more generation information about contributing to POI in general.</p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/how-to.xml b/src/documentation/content/xdocs/components/spreadsheet/how-to.xml new file mode 100644 index 0000000000..17582e914c --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/how-to.xml @@ -0,0 +1,884 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>The New Halloween Document</title> + <authors> + <person email="acoliver2@users.sourceforge.net" name="Andrew C. Oliver" id="AO"/> + <person email="user@poi.apache.org" name="Glen Stampoultzis" id="GJS"/> + <person email="nick@apache.org" name="Nick Burch" id="NB"/> + <person email="sergeikozello@mail.ru" name="Sergei Kozello" id="SK"/> + </authors> + </header> + <body> + <section><title>How to use the HSSF API</title> + + <section><title>Capabilities</title> + <p>This release of the how-to outlines functionality for the + current svn trunk. + Those looking for information on previous releases should + look in the documentation distributed with that release.</p> + <p> + HSSF allows numeric, string, date or formula cell values to be written to + or read from an XLS file. Also + in this release is row and column sizing, cell styling (bold, + italics, borders,etc), and support for both built-in and user + defined data formats. Also available is + an event-based API for reading XLS files. + It differs greatly from the read/write API + and is intended for intermediate developers who need a smaller + memory footprint. + </p> + </section> + <section><title>Different APIs</title> + <p>There are a few different ways to access the HSSF API. These + have different characteristics, so you should read up on + all to select the best for you.</p> + <ul> + <li><a href="#user_api">User API (HSSF and XSSF)</a></li> + <li><a href="#event_api">Event API (HSSF Only)</a></li> + <li><a href="#record_aware_event_api">Event API with extensions to be Record Aware (HSSF Only)</a></li> + <li><a href="#xssf_sax_api">XSSF and SAX (Event API)</a></li> + <li><a href="#sxssf">SXSSF (Streaming User API)</a></li> + <li><a href="#low_level_api">Low Level API</a></li> + </ul> + </section> + </section> + <section><title>General Use</title> + <anchor id="user_api" /> + <section><title>User API (HSSF and XSSF)</title> + <section><title>Writing a new file</title> + + <p>The high level API (package: org.apache.poi.ss.usermodel) + is what most people should use. Usage is very simple. + </p> + <p>Workbooks are created by creating an instance of + org.apache.poi.ss.usermodel.Workbook. Either create + a concrete class directly + (org.apache.poi.hssf.usermodel.HSSFWorkbook or + org.apache.poi.xssf.usermodel.XSSFWorkbook), or use + the handy factory class + org.apache.poi.ss.usermodel.WorkbookFactory. + </p> + <p>Sheets are created by calling createSheet() from an existing + instance of Workbook, the created sheet is automatically added in + sequence to the workbook. Sheets do not in themselves have a sheet + name (the tab at the bottom); you set + the name associated with a sheet by calling + Workbook.setSheetName(sheetindex,"SheetName",encoding). + For HSSF, the name may be in 8bit format + (HSSFWorkbook.ENCODING_COMPRESSED_UNICODE) + or Unicode (HSSFWorkbook.ENCODING_UTF_16). Default + encoding for HSSF is 8bit per char. For XSSF, the name + is automatically handled as unicode. + </p> + <p>Rows are created by calling createRow(rowNumber) from an existing + instance of Sheet. Only rows that have cell values should be + added to the sheet. To set the row's height, you just call + setRowHeight(height) on the row object. The height must be given in + twips, or 1/20th of a point. If you prefer, there is also a + setRowHeightInPoints method. + </p> + <p>Cells are created by calling createCell(column, type) from an + existing Row. Only cells that have values should be added to the + row. Cells should have their cell type set to either + Cell.CELL_TYPE_NUMERIC or Cell.CELL_TYPE_STRING depending on + whether they contain a numeric or textual value. Cells must also have + a value set. Set the value by calling setCellValue with either a + String or double as a parameter. Individual cells do not have a + width; you must call setColumnWidth(colindex, width) (use units of + 1/256th of a character) on the Sheet object. (You can't do it on + an individual basis in the GUI either).</p> + <p>Cells are styled with CellStyle objects which in turn contain + a reference to an Font object. These are created via the + Workbook object by calling createCellStyle() and createFont(). + Once you create the object you must set its parameters (colors, + borders, etc). To set a font for an CellStyle call + setFont(fontobj). + </p> + <p>Once you have generated your workbook, you can write it out by + calling write(outputStream) from your instance of Workbook, passing + it an OutputStream (for instance, a FileOutputStream or + ServletOutputStream). You must close the OutputStream yourself. HSSF + does not close it for you. + </p> + <p>Here is some example code (excerpted and adapted from + org.apache.poi.hssf.dev.HSSF test class):</p> +<source><![CDATA[ +short rownum; + +// create a new file +FileOutputStream out = new FileOutputStream("workbook.xls"); +// create a new workbook +Workbook wb = new HSSFWorkbook(); +// create a new sheet +Sheet s = wb.createSheet(); +// declare a row object reference +Row r = null; +// declare a cell object reference +Cell c = null; +// create 3 cell styles +CellStyle cs = wb.createCellStyle(); +CellStyle cs2 = wb.createCellStyle(); +CellStyle cs3 = wb.createCellStyle(); +DataFormat df = wb.createDataFormat(); +// create 2 fonts objects +Font f = wb.createFont(); +Font f2 = wb.createFont(); + +//set font 1 to 12 point type +f.setFontHeightInPoints((short) 12); +//make it blue +f.setColor( (short)0xc ); +// make it bold +//arial is the default font +f.setBoldweight(Font.BOLDWEIGHT_BOLD); + +//set font 2 to 10 point type +f2.setFontHeightInPoints((short) 10); +//make it red +f2.setColor( (short)Font.COLOR_RED ); +//make it bold +f2.setBoldweight(Font.BOLDWEIGHT_BOLD); + +f2.setStrikeout( true ); + +//set cell stlye +cs.setFont(f); +//set the cell format +cs.setDataFormat(df.getFormat("#,##0.0")); + +//set a thin border +cs2.setBorderBottom(cs2.BORDER_THIN); +//fill w fg fill color +cs2.setFillPattern((short) CellStyle.SOLID_FOREGROUND); +//set the cell format to text see DataFormat for a full list +cs2.setDataFormat(HSSFDataFormat.getBuiltinFormat("text")); + +// set the font +cs2.setFont(f2); + +// set the sheet name in Unicode +wb.setSheetName(0, "\u0422\u0435\u0441\u0442\u043E\u0432\u0430\u044F " + + "\u0421\u0442\u0440\u0430\u043D\u0438\u0447\u043A\u0430" ); +// in case of plain ascii +// wb.setSheetName(0, "HSSF Test"); +// create a sheet with 30 rows (0-29) +int rownum; +for (rownum = (short) 0; rownum < 30; rownum++) +{ + // create a row + r = s.createRow(rownum); + // on every other row + if ((rownum % 2) == 0) + { + // make the row height bigger (in twips - 1/20 of a point) + r.setHeight((short) 0x249); + } + + //r.setRowNum(( short ) rownum); + // create 10 cells (0-9) (the += 2 becomes apparent later + for (short cellnum = (short) 0; cellnum < 10; cellnum += 2) + { + // create a numeric cell + c = r.createCell(cellnum); + // do some goofy math to demonstrate decimals + c.setCellValue(rownum * 10000 + cellnum + + (((double) rownum / 1000) + + ((double) cellnum / 10000))); + + String cellValue; + + // create a string cell (see why += 2 in the + c = r.createCell((short) (cellnum + 1)); + + // on every other row + if ((rownum % 2) == 0) + { + // set this cell to the first cell style we defined + c.setCellStyle(cs); + // set the cell's string value to "Test" + c.setCellValue( "Test" ); + } + else + { + c.setCellStyle(cs2); + // set the cell's string value to "\u0422\u0435\u0441\u0442" + c.setCellValue( "\u0422\u0435\u0441\u0442" ); + } + + + // make this column a bit wider + s.setColumnWidth((short) (cellnum + 1), (short) ((50 * 8) / ((double) 1 / 20))); + } +} + +//draw a thick black border on the row at the bottom using BLANKS +// advance 2 rows +rownum++; +rownum++; + +r = s.createRow(rownum); + +// define the third style to be the default +// except with a thick black border at the bottom +cs3.setBorderBottom(cs3.BORDER_THICK); + +//create 50 cells +for (short cellnum = (short) 0; cellnum < 50; cellnum++) +{ + //create a blank type cell (no value) + c = r.createCell(cellnum); + // set it to the thick black border style + c.setCellStyle(cs3); +} + +//end draw thick black border + + +// demonstrate adding/naming and deleting a sheet +// create a sheet, set its title then delete it +s = wb.createSheet(); +wb.setSheetName(1, "DeletedSheet"); +wb.removeSheetAt(1); +//end deleted sheet + +// write the workbook to the output stream +// close our file (don't blow out our file handles +wb.write(out); +out.close(); + ]]></source> + </section> + <section><title>Reading or modifying an existing file</title> + +<p>Reading in a file is equally simple. To read in a file, create a +new instance of org.apache.poi.poifs.Filesystem, passing in an open InputStream, such as a FileInputStream +for your XLS, to the constructor. Construct a new instance of +org.apache.poi.hssf.usermodel.HSSFWorkbook passing the +Filesystem instance to the constructor. From there you have access to +all of the high level model objects through their assessor methods +(workbook.getSheet(sheetNum), sheet.getRow(rownum), etc). +</p> +<p>Modifying the file you have read in is simple. You retrieve the +object via an assessor method, remove it via a parent object's remove +method (sheet.removeRow(hssfrow)) and create objects just as you +would if creating a new xls. When you are done modifying cells just +call workbook.write(outputstream) just as you did above.</p> +<p>An example of this can be seen in +<a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/usermodel/HSSFReadWrite.java">org.apache.poi.hssf.usermodel.examples.HSSFReadWrite</a>.</p> + </section> + </section> + + <anchor id="event_api" /> + <section><title>Event API (HSSF Only)</title> + + <p>The event API is newer than the User API. It is intended for intermediate + developers who are willing to learn a little bit of the low level API + structures. Its relatively simple to use, but requires a basic + understanding of the parts of an Excel file (or willingness to + learn). The advantage provided is that you can read an XLS with a + relatively small memory footprint. + </p> + <p>One important thing to note with the basic Event API is that it + triggers events only for things actually stored within the file. + With the XLS file format, it is quite common for things that + have yet to be edited to simply not exist in the file. This means + there may well be apparent "gaps" in the record stream, which + you either need to work around, or use the + <a href="#record_aware_event_api">Record Aware</a> extension + to the Event API.</p> + <p>To use this API you construct an instance of + org.apache.poi.hssf.eventmodel.HSSFRequest. Register a class you + create that supports the + org.apache.poi.hssf.eventmodel.HSSFListener interface using the + HSSFRequest.addListener(yourlistener, recordsid). The recordsid + should be a static reference number (such as BOFRecord.sid) contained + in the classes in org.apache.poi.hssf.record. The trick is you + have to know what these records are. Alternatively you can call + HSSFRequest.addListenerForAllRecords(mylistener). In order to learn + about these records you can either read all of the javadoc in the + org.apache.poi.hssf.record package or you can just hack up a + copy of org.apache.poi.hssf.dev.EFHSSF and adapt it to your + needs. TODO: better documentation on records.</p> + <p>Once you've registered your listeners in the HSSFRequest object + you can construct an instance of + org.apache.poi.poifs.filesystem.FileSystem (see POIFS howto) and + pass it your XLS file inputstream. You can either pass this, along + with the request you constructed, to an instance of HSSFEventFactory + via the HSSFEventFactory.processWorkbookEvents(request, Filesystem) + method, or you can get an instance of DocumentInputStream from + Filesystem.createDocumentInputStream("Workbook") and pass + it to HSSFEventFactory.processEvents(request, inputStream). Once you + make this call, the listeners that you constructed receive calls to + their processRecord(Record) methods with each Record they are + registered to listen for until the file has been completely read. + </p> + <p>A code excerpt from org.apache.poi.hssf.dev.EFHSSF (which is + in CVS or the source distribution) is reprinted below with excessive + comments:</p> +<source><![CDATA[ +/** + * This example shows how to use the event API for reading a file. + */ +public class EventExample + implements HSSFListener +{ + private SSTRecord sstrec; + + /** + * This method listens for incoming records and handles them as required. + * @param record The record that was found while reading. + */ + public void processRecord(Record record) + { + switch (record.getSid()) + { + // the BOFRecord can represent either the beginning of a sheet or the workbook + case BOFRecord.sid: + BOFRecord bof = (BOFRecord) record; + if (bof.getType() == bof.TYPE_WORKBOOK) + { + System.out.println("Encountered workbook"); + // assigned to the class level member + } else if (bof.getType() == bof.TYPE_WORKSHEET) + { + System.out.println("Encountered sheet reference"); + } + break; + case BoundSheetRecord.sid: + BoundSheetRecord bsr = (BoundSheetRecord) record; + System.out.println("New sheet named: " + bsr.getSheetname()); + break; + case RowRecord.sid: + RowRecord rowrec = (RowRecord) record; + System.out.println("Row found, first column at " + + rowrec.getFirstCol() + " last column at " + rowrec.getLastCol()); + break; + case NumberRecord.sid: + NumberRecord numrec = (NumberRecord) record; + System.out.println("Cell found with value " + numrec.getValue() + + " at row " + numrec.getRow() + " and column " + numrec.getColumn()); + break; + // SSTRecords store an array of unique strings used in Excel. + case SSTRecord.sid: + sstrec = (SSTRecord) record; + for (int k = 0; k < sstrec.getNumUniqueStrings(); k++) + { + System.out.println("String table value " + k + " = " + sstrec.getString(k)); + } + break; + case LabelSSTRecord.sid: + LabelSSTRecord lrec = (LabelSSTRecord) record; + System.out.println("String cell found with value " + + sstrec.getString(lrec.getSSTIndex())); + break; + } + } + + /** + * Read an excel file and spit out what we find. + * + * @param args Expect one argument that is the file to read. + * @throws IOException When there is an error processing the file. + */ + public static void main(String[] args) throws IOException + { + // create a new file input stream with the input file specified + // at the command line + FileInputStream fin = new FileInputStream(args[0]); + // create a new org.apache.poi.poifs.filesystem.Filesystem + POIFSFileSystem poifs = new POIFSFileSystem(fin); + // get the Workbook (excel part) stream in a InputStream + InputStream din = poifs.createDocumentInputStream("Workbook"); + // construct out HSSFRequest object + HSSFRequest req = new HSSFRequest(); + // lazy listen for ALL records with the listener shown above + req.addListenerForAllRecords(new EventExample()); + // create our event factory + HSSFEventFactory factory = new HSSFEventFactory(); + // process our events based on the document input stream + factory.processEvents(req, din); + // once all the events are processed close our file input stream + fin.close(); + // and our document input stream (don't want to leak these!) + din.close(); + System.out.println("done."); + } +} +]]></source> + </section> + + <anchor id="record_aware_event_api" /> + <section><title>Record Aware Event API (HSSF Only)</title> +<p> +This is an extension to the normal +<a href="#event_api">Event API</a>. With this, your listener +will be called with extra, dummy records. These dummy records should +alert you to records which aren't present in the file (eg cells that have +yet to be edited), and allow you to handle these. +</p> +<p> +There are three dummy records that your HSSFListener will be called with: +</p> +<ul> + <li>org.apache.poi.hssf.eventusermodel.dummyrecord.MissingRowDummyRecord + <br /> + This is called during the row record phase (which typically occurs before + the cell records), and indicates that the row record for the given + row is not present in the file.</li> + <li>org.apache.poi.hssf.eventusermodel.dummyrecord.MissingCellDummyRecord + <br /> + This is called during the cell record phase. It is called when a cell + record is encountered which leaves a gap between it an the previous one. + You can get multiple of these, before the real cell record.</li> + <li>org.apache.poi.hssf.eventusermodel.dummyrecord.LastCellOfRowDummyRecord + <br /> + This is called after the last cell of a given row. It indicates that there + are no more cells for the row, and also tells you how many cells you have + had. For a row with no cells, this will be the only record you get.</li> +</ul> +<p> +To use the Record Aware Event API, you should create an +org.apache.poi.hssf.eventusermodel.MissingRecordAwareHSSFListener, and pass +it your HSSFListener. Then, register the MissingRecordAwareHSSFListener +to the event model, and start that as normal. +</p> +<p> +One example use for this API is to write a CSV outputter, which always +outputs a minimum number of columns, even where the file doesn't contain +some of the rows or cells. It can be found at +<code>/poi-examples/src/main/java/org/apache/poi/examples/hssf/eventusermodel/XLS2CSVmra.java</code>, +and may be called on the command line, or from within your own code. +The latest version is always available from +<a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/hssf/eventusermodel/">git</a>. +</p> +<p> +<em>In POI versions before 3.0.3, this code lived in the scratchpad section. + If you're using one of these older versions of POI, you will either + need to include the scratchpad jar on your classpath, or build from a</em> + <a href="site:git">git checkout</a>. +</p> + </section> + + <anchor id="xssf_sax_api"/> + <section><title>XSSF and SAX (Event API)</title> + + <p>If memory footprint is an issue, then for XSSF, you can get at + the underlying XML data, and process it yourself. This is intended + for intermediate developers who are willing to learn a little bit of + low level structure of .xlsx files, and who are happy processing + XML in java. Its relatively simple to use, but requires a basic + understanding of the file structure. The advantage provided is that + you can read a XLSX file with a relatively small memory footprint. + </p> + <p>One important thing to note with the basic Event API is that it + triggers events only for things actually stored within the file. + With the XLSX file format, it is quite common for things that + have yet to be edited to simply not exist in the file. This means + there may well be apparent "gaps" in the record stream, which + you need to work around.</p> + <p>To use this API you construct an instance of + org.apache.poi.xssf.eventmodel.XSSFReader. This will optionally + provide a nice interface on the shared strings table, and the styles. + It provides methods to get the raw xml data from the rest of the + file, which you will then pass to SAX.</p> + <p>This example shows how to get at a single known sheet, or at + all sheets in the file. It is based on the example in + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/eventusermodel/FromHowTo.java">svn + poi-examples/src/main/java/org/apache/poi/examples/xssf/eventusermodel/FromHowTo.java</a></p> +<source><![CDATA[ +import java.io.InputStream; +import java.util.Iterator; + +import org.apache.poi.util.XMLHelper; +import org.apache.poi.openxml4j.opc.OPCPackage; +import org.apache.poi.xssf.eventusermodel.XSSFReader; +import org.apache.poi.xssf.model.SharedStringsTable; +import org.xml.sax.Attributes; +import org.xml.sax.ContentHandler; +import org.xml.sax.InputSource; +import org.xml.sax.SAXException; +import org.xml.sax.XMLReader; +import org.xml.sax.helpers.DefaultHandler; + +import javax.xml.parsers.ParserConfigurationException; + +public class ExampleEventUserModel { + public void processOneSheet(String filename) throws Exception { + OPCPackage pkg = OPCPackage.open(filename); + XSSFReader r = new XSSFReader( pkg ); + SharedStringsTable sst = r.getSharedStringsTable(); + + XMLReader parser = fetchSheetParser(sst); + + // To look up the Sheet Name / Sheet Order / rID, + // you need to process the core Workbook stream. + // Normally it's of the form rId# or rSheet# + InputStream sheet2 = r.getSheet("rId2"); + InputSource sheetSource = new InputSource(sheet2); + parser.parse(sheetSource); + sheet2.close(); + } + + public void processAllSheets(String filename) throws Exception { + OPCPackage pkg = OPCPackage.open(filename); + XSSFReader r = new XSSFReader( pkg ); + SharedStringsTable sst = r.getSharedStringsTable(); + + XMLReader parser = fetchSheetParser(sst); + + Iterator<InputStream> sheets = r.getSheetsData(); + while(sheets.hasNext()) { + System.out.println("Processing new sheet:\n"); + InputStream sheet = sheets.next(); + InputSource sheetSource = new InputSource(sheet); + parser.parse(sheetSource); + sheet.close(); + System.out.println(""); + } + } + + public XMLReader fetchSheetParser(SharedStringsTable sst) throws SAXException, ParserConfigurationException { + XMLReader parser = XMLHelper.newXMLReader(); + ContentHandler handler = new SheetHandler(sst); + parser.setContentHandler(handler); + return parser; + } + + /** + * See org.xml.sax.helpers.DefaultHandler javadocs + */ + private static class SheetHandler extends DefaultHandler { + private SharedStringsTable sst; + private String lastContents; + private boolean nextIsString; + + private SheetHandler(SharedStringsTable sst) { + this.sst = sst; + } + + public void startElement(String uri, String localName, String name, + Attributes attributes) throws SAXException { + // c => cell + if(name.equals("c")) { + // Print the cell reference + System.out.print(attributes.getValue("r") + " - "); + // Figure out if the value is an index in the SST + String cellType = attributes.getValue("t"); + if(cellType != null && cellType.equals("s")) { + nextIsString = true; + } else { + nextIsString = false; + } + } + // Clear contents cache + lastContents = ""; + } + + public void endElement(String uri, String localName, String name) + throws SAXException { + // Process the last contents as required. + // Do now, as characters() may be called more than once + if(nextIsString) { + int idx = Integer.parseInt(lastContents); + lastContents = sst.getItemAt(idx).getString(); + nextIsString = false; + } + + // v => contents of a cell + // Output after we've seen the string contents + if(name.equals("v")) { + System.out.println(lastContents); + } + } + + public void characters(char[] ch, int start, int length) { + lastContents += new String(ch, start, length); + } + } + + public static void main(String[] args) throws Exception { + ExampleEventUserModel example = new ExampleEventUserModel(); + example.processOneSheet(args[0]); + example.processAllSheets(args[0]); + } +} +]]></source> + <p> + For a fuller example, including support for fetching number formatting + information and applying it to numeric cells (eg to format dates or + percentages), please see + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/eventusermodel/XLSX2CSV.java">the XLSX2CSV example in svn</a> + </p> + <p>An example is also <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/streaming/HybridStreaming.java">provided</a> + showing how to combine the user API and the SAX API by doing a streaming parse + of larger worksheets and a traditional user-model parse of the rest of a workbook.</p> + </section> + <anchor id="sxssf"/> + <section><title>SXSSF (Streaming Usermodel API)</title> + <p> + SXSSF (package: org.apache.poi.xssf.streaming) is an API-compatible streaming extension of XSSF to be used when + very large spreadsheets have to be produced, and heap space is limited. + SXSSF achieves its low memory footprint by limiting access to the rows that + are within a sliding window, while XSSF gives access to all rows in the + document. Older rows that are no longer in the window become inaccessible, + as they are written to the disk. + </p> + <p> + You can specify the window size at workbook construction time via <em>new SXSSFWorkbook(int windowSize)</em> + or you can set it per-sheet via <em>SXSSFSheet#setRandomAccessWindowSize(int windowSize)</em> + </p> + <p> + When a new row is created via createRow() and the total number + of unflushed records would exceed the specified window size, then the + row with the lowest index value is flushed and cannot be accessed + via getRow() anymore. + </p> + <p> + The default window size is <em>100</em> and defined by SXSSFWorkbook.DEFAULT_WINDOW_SIZE. + </p> + <p> + A windowSize of -1 indicates unlimited access. In this case all + records that have not been flushed by a call to flushRows() are available + for random access. + </p> + <p> + Note that SXSSF allocates temporary files that you <strong>must</strong> always clean up explicitly, by calling the dispose method. + </p> + <p> + SXSSFWorkbook defaults to using inline strings instead of a shared strings + table. This is very efficient, since no document content needs to be kept in + memory, but is also known to produce documents that are incompatible with + some clients. With shared strings enabled all unique strings in the document + has to be kept in memory. Depending on your document content this could use + a lot more resources than with shared strings disabled. + </p> + <p> + Please note that there are still things that still may consume a large + amount of memory based on which features you are using, e.g. merged regions, + hyperlinks, comments, ... are still only stored in memory and thus may require a lot of + memory if used extensively. + </p> + <p> + Carefully review your memory budget and compatibility needs before deciding + whether to enable shared strings or not. + </p> + <p> The example below writes a sheet with a window of 100 rows. When the row count reaches 101, + the row with rownum=0 is flushed to disk and removed from memory, when rownum reaches 102 then the row with rownum=1 is flushed, etc. + </p> + + +<source><![CDATA[ +import junit.framework.Assert; +import org.apache.poi.ss.usermodel.Cell; +import org.apache.poi.ss.usermodel.Row; +import org.apache.poi.ss.usermodel.Sheet; +import org.apache.poi.ss.usermodel.Workbook; +import org.apache.poi.ss.util.CellReference; +import org.apache.poi.xssf.streaming.SXSSFWorkbook; + + public static void main(String[] args) throws Throwable { + SXSSFWorkbook wb = new SXSSFWorkbook(100); // keep 100 rows in memory, exceeding rows will be flushed to disk + Sheet sh = wb.createSheet(); + for(int rownum = 0; rownum < 1000; rownum++){ + Row row = sh.createRow(rownum); + for(int cellnum = 0; cellnum < 10; cellnum++){ + Cell cell = row.createCell(cellnum); + String address = new CellReference(cell).formatAsString(); + cell.setCellValue(address); + } + + } + + // Rows with rownum < 900 are flushed and not accessible + for(int rownum = 0; rownum < 900; rownum++){ + Assert.assertNull(sh.getRow(rownum)); + } + + // ther last 100 rows are still in memory + for(int rownum = 900; rownum < 1000; rownum++){ + Assert.assertNotNull(sh.getRow(rownum)); + } + + FileOutputStream out = new FileOutputStream("/temp/sxssf.xlsx"); + wb.write(out); + out.close(); + + // dispose of temporary files backing this workbook on disk + wb.dispose(); + } + + +]]></source> +<p>The next example turns off auto-flushing (windowSize=-1) and the code manually controls how portions of data are written to disk</p> +<source><![CDATA[ +import org.apache.poi.ss.usermodel.Cell; +import org.apache.poi.ss.usermodel.Row; +import org.apache.poi.ss.usermodel.Sheet; +import org.apache.poi.ss.usermodel.Workbook; +import org.apache.poi.ss.util.CellReference; +import org.apache.poi.xssf.streaming.SXSSFWorkbook; + + public static void main(String[] args) throws Throwable { + SXSSFWorkbook wb = new SXSSFWorkbook(-1); // turn off auto-flushing and accumulate all rows in memory + Sheet sh = wb.createSheet(); + for(int rownum = 0; rownum < 1000; rownum++){ + Row row = sh.createRow(rownum); + for(int cellnum = 0; cellnum < 10; cellnum++){ + Cell cell = row.createCell(cellnum); + String address = new CellReference(cell).formatAsString(); + cell.setCellValue(address); + } + + // manually control how rows are flushed to disk + if(rownum % 100 == 0) { + ((SXSSFSheet)sh).flushRows(100); // retain 100 last rows and flush all others + + // ((SXSSFSheet)sh).flushRows() is a shortcut for ((SXSSFSheet)sh).flushRows(0), + // this method flushes all rows + } + + } + + FileOutputStream out = new FileOutputStream("/temp/sxssf.xlsx"); + wb.write(out); + out.close(); + + // dispose of temporary files backing this workbook on disk + wb.dispose(); + } + + +]]></source> +<p>SXSSF flushes sheet data in temporary files (a temp file per sheet) and the size of these temporary files +can grow to a very large value. For example, for a 20 MB csv data the size of the temp xml becomes more than a gigabyte. +If the size of the temp files is an issue, you can tell SXSSF to use gzip compression: +</p> +<source><![CDATA[ + SXSSFWorkbook wb = new SXSSFWorkbook(); + wb.setCompressTempFiles(true); // temp files will be gzipped + +]]></source> + </section> + + <anchor id="low_level_api" /> + <section><title>Low Level APIs</title> + +<p>The low level API is not much to look at. It consists of lots of +"Records" in the org.apache.poi.hssf.record.* package, +and set of helper classes in org.apache.poi.hssf.model.*. The +record classes are consistent with the low level binary structures +inside a BIFF8 file (which is embedded in a POIFS file system). You +probably need the book: "Microsoft Excel 97 Developer's Kit" +from Microsoft Press in order to understand how these fit together +(out of print but easily obtainable from Amazon's used books). In +order to gain a good understanding of how to use the low level APIs +should view the source in org.apache.poi.hssf.usermodel.* and +the classes in org.apache.poi.hssf.model.*. You should read the +documentation for the POIFS libraries as well.</p> + </section> + <section><title>Generating XLS from XML</title> +<p>If you wish to generate an XLS file from some XML, it is possible to +write your own XML processing code, then use the User API to write out +the document.</p> +<p>The other option is to use <a href="https://cocoon.apache.org/">Cocoon</a>. +In Cocoon, there is the <a href="https://cocoon.apache.org/2.1/userdocs/xls-serializer.html">HSSF Serializer</a>, +which takes in XML (in the gnumeric format), and outputs an XLS file for you.</p> + </section> + <section><title>HSSF Class/Test Application</title> + +<p>The HSSF application is nothing more than a test for the high +level API (and indirectly the low level support). The main body of +its code is repeated above. To run it: +</p> +<ul> + <li>download the poi-alpha build and untar it (tar xvzf + tarball.tar.gz) + </li> + <li>set up your classpath as follows: + <code>export HSSFDIR={wherever you put HSSF's jar files} +export LOG4JDIR={wherever you put LOG4J's jar files} +export CLASSPATH=$CLASSPATH:$HSSFDIR/hssf.jar:$HSSFDIR/poi-poifs.jar:$HSSFDIR/poi-util.jar:$LOG4JDIR/log4j.jar</code> + </li><li>type: + <code>java org.apache.poi.hssf.dev.HSSF ~/myxls.xls write</code></li> +</ul> +<p></p> +<p>This should generate a test sheet in your home directory called <code>"myxls.xls"</code>. </p> +<ul> + <li>Type: + <code>java org.apache.poi.hssf.dev.HSSF ~/input.xls output.xls</code> + <br/> + <br/> +This is the read/write/modify test. It reads in the spreadsheet, modifies a cell, and writes it back out. +Failing this test is not necessarily a bad thing. If HSSF tries to modify a non-existant sheet then this will +most likely fail. No big deal. </li> +</ul> + </section> + <section><title>HSSF Developer's Tools</title> + +<p>HSSF has a number of tools useful for developers to debug/develop +stuff using HSSF (and more generally XLS files). We've already +discussed the app for testing HSSF read/write/modify capabilities; +now we'll talk a bit about BiffViewer. Early on in the development of +HSSF, it was decided that knowing what was in a record, what was +wrong with it, etc. was virtually impossible with the available +tools. So we developed BiffViewer. You can find it at +org.apache.poi.hssf.dev.BiffViewer. It performs two basic +functions and a derivative. +</p> +<p>The first is "biffview". To do this you run it (assumes +you have everything setup in your classpath and that you know what +you're doing enough to be thinking about this) with an xls file as a +parameter. It will give you a listing of all understood records with +their data and a list of not-yet-understood records with no data +(because it doesn't know how to interpret them). This listing is +useful for several things. First, you can look at the values and SEE +what is wrong in quasi-English. Second, you can send the output to a +file and compare it. +</p> +<p>The second function is "big freakin dump", just pass a +file and a second argument matching "bfd" exactly. This +will just make a big hexdump of the file. +</p> +<p>Lastly, there is "mixed" mode which does the same as +regular biffview, only it includes hex dumps of certain records +intertwined. To use that just pass a file with a second argument +matching "on" exactly.</p> +<p>In the next release cycle we'll also have something called a +FormulaViewer. The class is already there, but its not very useful +yet. When it does something, we'll document it.</p> + + </section> + <section><title>What's Next?</title> + +<p>Further effort on HSSF is going to focus on the following major areas: </p> +<ul> +<li>Performance: POI currently uses a lot of memory for large sheets.</li> +<li>Charts: This is a hard problem, with very little documentation.</li> +</ul> +<p><a href="site:guidelines"> So jump in! </a> </p> + + </section> + +</section> +</body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/index.xml b/src/documentation/content/xdocs/components/spreadsheet/index.xml new file mode 100644 index 0000000000..ec262b554c --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/index.xml @@ -0,0 +1,119 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>POI-HSSF and POI-XSSF/SXSSF - Java API To Access Microsoft Excel Format Files</title> + <subtitle>Overview</subtitle> + <authors> + <person name="Andrew C. Oliver" email="acoliver@apache.org"/> + <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/> + </authors> + </header> + + <body> + <section> + <title>Overview</title> + + <p>HSSF is the POI Project's pure Java implementation of the + Excel '97(-2007) file format. XSSF is the POI Project's pure + Java implementation of the Excel 2007 OOXML (.xlsx) file + format.</p> + <p>HSSF and XSSF provides ways to read spreadsheets create, + modify, read and write XLS spreadsheets. They provide: + </p> + <ul> + <li>low level structures for those with special needs</li> + <li>an eventmodel api for efficient read-only access</li> + <li>a full usermodel api for creating, reading and modifying XLS files</li> + </ul> + <p>For people converting from pure HSSF usermodel, who wish + to use the joint SS Usermodel for HSSF and XSSF support, then + see the <a href="converting.html">ss usermodel converting + guide</a>. + </p> + <p> + An alternate way of generating a spreadsheet is via the <a href="https://cocoon.apache.org">Cocoon</a> serializer (yet you'll still be using HSSF indirectly). + With Cocoon you can serialize any XML datasource (which might be a ESQL page outputting in SQL for instance) by simply + applying the stylesheet and designating the serializer. + </p> + <p> + If you're merely reading spreadsheet data, then use the + eventmodel api in either the org.apache.poi.hssf.eventusermodel + package, or the org.apache.poi.xssf.eventusermodel package, depending + on your file format. + </p> + <p> + If you're modifying spreadsheet data then use the usermodel api. You + can also generate spreadsheets this way. + </p> + <p> + Note that the usermodel system has a higher memory footprint than + the low level eventusermodel, but has the major advantage of being + much simpler to work with. Also please be aware that as the new + XSSF supported Excel 2007 OOXML (.xlsx) files are XML based, + the memory footprint for processing them is higher than for the + older HSSF supported (.xls) binary files. + </p> + + + + </section> + +<section> +<title>SXSSF (Since POI 3.8 beta3)</title> +<p>Since 3.8-beta3, POI provides a low-memory footprint SXSSF API built on top of XSSF.</p> +<p> +SXSSF is an API-compatible streaming extension of XSSF to be used when +very large spreadsheets have to be produced, and heap space is limited. +SXSSF achieves its low memory footprint by limiting access to the rows that +are within a sliding window, while XSSF gives access to all rows in the +document. Older rows that are no longer in the window become inaccessible, +as they are written to the disk. +</p> +<p> +In auto-flush mode the size of the access window can be specified, to hold a certain number of rows in memory. +When that value is reached, the creation of an additional row causes the row with the lowest index to to be +removed from the access window and written to disk. Or, the window size can be set to grow dynamically; +it can be trimmed periodically by an explicit call to flushRows(int keepRows) as needed. +</p> +<p> +Due to the streaming nature of the implementation, there are the following +limitations when compared to XSSF: +</p> + <ul> + <li>Only a limited number of rows are accessible at a point in time.</li> + <li>Sheet.clone() is not supported.</li> + <li>Formula evaluation is not supported</li> + </ul> + + <p> See more details at <a href="how-to.html#sxssf">SXSSF How-To</a></p> + +<p>The table below synopsizes the comparative features of POI's Spreadsheet API:</p> + <p><em>Spreadsheet API Feature Summary</em></p> + + <p> + <img src="images/ss-features.png" alt="Spreadsheet API Feature Summary"/> + </p> +</section> + + </body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/limitations.xml b/src/documentation/content/xdocs/components/spreadsheet/limitations.xml new file mode 100644 index 0000000000..ce9f8afc56 --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/limitations.xml @@ -0,0 +1,99 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - HSSF and XSSF Limitations</title> + <authors> + <person email="user@poi.apache.org" name="Glen Stampoultzis" id="GJS"/> + </authors> + </header> + <body> + <section><title>Current HSSF / XSSF main limitations</title> + <p> + The intent of this document is to outline some of the known limitations of the + POI HSSF and XSSF APIs. It is not intended to be complete list of every bug + or missing feature of HSSF or XSSF, rather it's purpose is to provide a broad + feel for some of the functionality that is missing or broken. + </p> + <ul> + <li> + File sizes/Memory usage<br/><br/> + <ul> + <li> + There are some inherent limits in the Excel file formats. These are defined in class + <a href="../../apidocs/dev/org/apache/poi/ss/SpreadsheetVersion.html">SpreadsheetVersion</a>. + As long as you have enough main-memory, you should be able to handle files up to these limits. For huge files + using the default POI classes you will likely need a very large amount of memory. + <br/> + <br/> + There are ways to overcome the main-memory limitations if needed: + <br/> + <ul> + <li> + For writing very huge files, there is <a href="site:spreadsheet">SXSSFWorkbook</a> + which allows to do a streaming write of data out to files (with certain limitations on what you can do as only + parts of the file are held in memory). + </li> + <li> + For reading very huge files, take a look at the sample + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/eventusermodel/XLSX2CSV.java">XLSX2CSV</a> + which shows how you can read a file in streaming fashion (again with some limitations on what information you + can read out of the file, but there are ways to get at most of it if necessary). + </li> + </ul> + </li> + </ul> + </li> + <li> + Charts<br/><br/> + <ul> + <li> + HSSF has some limited support for creating a handful of very simple Chart types, + but largely this isn't supported. HSSF (largely) doesn't support changing Charts. + You can however create a chart in Excel using Named ranges, modify the chart data + values using HSSF and write a new spreadsheet out. This is possible because POI + attempts to keep existing records intact as far as possible.<br/> + </li> + <li> + XSSF has only limited chart support including making some simple changes + and adding at least some line and scatter charts, see the examples <em>LineChart</em> + and <em>ScatterChart</em>.<br/><br/> + </li> + </ul> + </li> + <li> + Macros<br/><br/> + Macros can not be created. The are currently no plans to support macros. + However, reading and re-writing files containing macros will safely preserve + the macros. Recent versions of Apache POI support extracting the macro data + via <a href="../../apidocs/dev/org/apache/poi/poifs/macros/VBAMacroExtractor.html">VBAMacroExtractor</a> + and <a href="../../apidocs/dev/org/apache/poi/poifs/macros/VBAMacroReader.html">VBAMacroReader</a><br/><br/> + </li> + <li> + Pivot Tables<br/><br/> + HSSF doesn't have support for reading or creating Pivot tables. XSSF has limited + support for creating Pivot Tables, and very limited read/change support. + </li> + </ul> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/quick-guide.xml b/src/documentation/content/xdocs/components/spreadsheet/quick-guide.xml new file mode 100644 index 0000000000..3ef09310b7 --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/quick-guide.xml @@ -0,0 +1,2455 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Busy Developers' Guide to HSSF and XSSF Features</title> + </header> + <body> + <section><title>Busy Developers' Guide to Features</title> + <p> + Want to use HSSF and XSSF read and write spreadsheets in a hurry? This + guide is for you. If you're after more in-depth coverage of the HSSF and + XSSF user-APIs, please consult the <a href="how-to.html">HOWTO</a> + guide as it contains actual descriptions of how to use this stuff. + </p> + <section><title>Index of Features</title> + <ul> + <li><a href="#NewWorkbook">How to create a new workbook</a></li> + <li><a href="#NewSheet">How to create a sheet</a></li> + <li><a href="#CreateCells">How to create cells</a></li> + <li><a href="#CreateDateCells">How to create date cells</a></li> + <li><a href="#CellTypes">Working with different types of cells</a></li> + <li><a href="#Iterator">Iterate over rows and cells</a></li> + <li><a href="#CellContents">Getting the cell contents</a></li> + <li><a href="#TextExtraction">Text Extraction</a></li> + <li><a href="#FileInputStream">Files vs InputStreams</a></li> + <li><a href="#Alignment">Aligning cells</a></li> + <li><a href="#Borders">Working with borders</a></li> + <li><a href="#FillsAndFrills">Fills and color</a></li> + <li><a href="#MergedCells">Merging cells</a></li> + <li><a href="#WorkingWithFonts">Working with fonts</a></li> + <li><a href="#CustomColors">Custom colors</a></li> + <li><a href="#ReadWriteWorkbook">Reading and writing</a></li> + <li><a href="#NewLinesInCells">Use newlines in cells.</a></li> + <li><a href="#DataFormats">Create user defined data formats</a></li> + <li><a href="#FitTo">Fit Sheet to One Page</a></li> + <li><a href="#PrintArea2">Set print area for a sheet</a></li> + <li><a href="#FooterPageNumbers">Set page numbers on the footer of a sheet</a></li> + <li><a href="#ShiftRows">Shift rows</a></li> + <li><a href="#SelectSheet">Set a sheet as selected</a></li> + <li><a href="#Zoom">Set the zoom magnification for a sheet</a></li> + <li><a href="#Splits">Create split and freeze panes</a></li> + <li><a href="#Repeating">Repeating rows and columns</a></li> + <li><a href="#HeaderFooter">Headers and Footers</a></li> + <li><a href="#XSSFHeaderFooter">XSSF enhancement for Headers and Footers</a></li> + <li><a href="#DrawingShapes">Drawing Shapes</a></li> + <li><a href="#StylingShapes">Styling Shapes</a></li> + <li><a href="#Graphics2d">Shapes and Graphics2d</a></li> + <li><a href="#Outlining">Outlining</a></li> + <li><a href="#Images">Images</a></li> + <li><a href="#NamedRanges">Named Ranges and Named Cells</a></li> + <li><a href="#CellComments">How to set cell comments</a></li> + <li><a href="#Autofit">How to adjust column width to fit the contents</a></li> + <li><a href="#Hyperlinks">Hyperlinks</a></li> + <li><a href="#Validation">Data Validations</a></li> + <li><a href="#Embedded">Embedded Objects</a></li> + <li><a href="#Autofilter">Autofilters</a></li> + <li><a href="#ConditionalFormatting">Conditional Formatting</a></li> + <li><a href="#Hiding">Hiding and Un-Hiding Rows</a></li> + <li><a href="#CellProperties">Setting Cell Properties</a></li> + <li><a href="#DrawingBorders">Drawing Borders</a></li> + <li><a href="#PivotTable">Create a Pivot Table</a></li> + <li><a href="#RichText">Cells with multiple styles</a></li> + </ul> + </section> + <section><title>Features</title> + <anchor id="NewWorkbook"/> + <section><title>New Workbook</title> + <source> + Workbook wb = new HSSFWorkbook(); + ... + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + + Workbook wb = new XSSFWorkbook(); + ... + try (OutputStream fileOut = new FileOutputStream("workbook.xlsx")) { + wb.write(fileOut); + } + </source> + </section> + <anchor id="NewSheet"/> + <section><title>New Sheet</title> + <source> + Workbook wb = new HSSFWorkbook(); // or new XSSFWorkbook(); + Sheet sheet1 = wb.createSheet("new sheet"); + Sheet sheet2 = wb.createSheet("second sheet"); + + // Note that sheet name is Excel must not exceed 31 characters + // and must not contain any of the any of the following characters: + // 0x0000 + // 0x0003 + // colon (:) + // backslash (\) + // asterisk (*) + // question mark (?) + // forward slash (/) + // opening square bracket ([) + // closing square bracket (]) + + // You can use org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)} + // for a safe way to create valid names, this utility replaces invalid characters with a space (' ') + String safeName = WorkbookUtil.createSafeSheetName("[O'Brien's sales*?]"); // returns " O'Brien's sales " + Sheet sheet3 = wb.createSheet(safeName); + + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + </source> + </section> + <anchor id="CreateCells"/> + <section><title>Creating Cells</title> + <source> + Workbook wb = new HSSFWorkbook(); + //Workbook wb = new XSSFWorkbook(); + CreationHelper createHelper = wb.getCreationHelper(); + Sheet sheet = wb.createSheet("new sheet"); + + // Create a row and put some cells in it. Rows are 0 based. + Row row = sheet.createRow(0); + // Create a cell and put a value in it. + Cell cell = row.createCell(0); + cell.setCellValue(1); + + // Or do it on one line. + row.createCell(1).setCellValue(1.2); + row.createCell(2).setCellValue( + createHelper.createRichTextString("This is a string")); + row.createCell(3).setCellValue(true); + + // Write the output to a file + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + </source> + </section> + <anchor id="CreateDateCells"/> + <section><title>Creating Date Cells</title> + <source> + Workbook wb = new HSSFWorkbook(); + //Workbook wb = new XSSFWorkbook(); + CreationHelper createHelper = wb.getCreationHelper(); + Sheet sheet = wb.createSheet("new sheet"); + + // Create a row and put some cells in it. Rows are 0 based. + Row row = sheet.createRow(0); + + // Create a cell and put a date value in it. The first cell is not styled + // as a date. + Cell cell = row.createCell(0); + cell.setCellValue(new Date()); + + // we style the second cell as a date (and time). It is important to + // create a new cell style from the workbook otherwise you can end up + // modifying the built in style and effecting not only this cell but other cells. + CellStyle cellStyle = wb.createCellStyle(); + cellStyle.setDataFormat( + createHelper.createDataFormat().getFormat("m/d/yy h:mm")); + cell = row.createCell(1); + cell.setCellValue(new Date()); + cell.setCellStyle(cellStyle); + + //you can also set date as java.util.Calendar + cell = row.createCell(2); + cell.setCellValue(Calendar.getInstance()); + cell.setCellStyle(cellStyle); + + // Write the output to a file + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + </source> + </section> + <anchor id="CellTypes"/> + <section><title>Working with different types of cells</title> + <source> + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("new sheet"); + Row row = sheet.createRow(2); + row.createCell(0).setCellValue(1.1); + row.createCell(1).setCellValue(new Date()); + row.createCell(2).setCellValue(Calendar.getInstance()); + row.createCell(3).setCellValue("a string"); + row.createCell(4).setCellValue(true); + row.createCell(5).setCellType(CellType.ERROR); + + // Write the output to a file + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + </source> + </section> + + <anchor id="FileInputStream"/> + <section><title>Files vs InputStreams</title> + <p>When opening a workbook, either a .xls HSSFWorkbook, or a .xlsx + XSSFWorkbook, the Workbook can be loaded from either a <em>File</em> + or an <em>InputStream</em>. Using a <em>File</em> object allows for + lower memory consumption, while an <em>InputStream</em> requires more + memory as it has to buffer the whole file.</p> + <p>If using <em>WorkbookFactory</em>, it's very easy to use one or + the other:</p> + <source> + // Use a file + Workbook wb = WorkbookFactory.create(new File("MyExcel.xls")); + + // Use an InputStream, needs more memory + Workbook wb = WorkbookFactory.create(new FileInputStream("MyExcel.xlsx")); + </source> + <p>If using <em>HSSFWorkbook</em> or <em>XSSFWorkbook</em> directly, + you should generally go through <em>POIFSFileSystem</em> or + <em>OPCPackage</em>, to have full control of the lifecycle (including + closing the file when done):</p> + <source> + // HSSFWorkbook, File + POIFSFileSystem fs = new POIFSFileSystem(new File("file.xls")); + HSSFWorkbook wb = new HSSFWorkbook(fs.getRoot(), true); + .... + fs.close(); + + // HSSFWorkbook, InputStream, needs more memory + POIFSFileSystem fs = new POIFSFileSystem(myInputStream); + HSSFWorkbook wb = new HSSFWorkbook(fs.getRoot(), true); + + // XSSFWorkbook, File + OPCPackage pkg = OPCPackage.open(new File("file.xlsx")); + XSSFWorkbook wb = new XSSFWorkbook(pkg); + .... + pkg.close(); + + // XSSFWorkbook, InputStream, needs more memory + OPCPackage pkg = OPCPackage.open(myInputStream); + XSSFWorkbook wb = new XSSFWorkbook(pkg); + .... + pkg.close(); + </source> + </section> + + <anchor id="Alignment"/> + <section><title>Demonstrates various alignment options</title> + <source> + public static void main(String[] args) throws Exception { + Workbook wb = new XSSFWorkbook(); //or new HSSFWorkbook(); + + Sheet sheet = wb.createSheet(); + Row row = sheet.createRow(2); + row.setHeightInPoints(30); + + createCell(wb, row, 0, HorizontalAlignment.CENTER, VerticalAlignment.BOTTOM); + createCell(wb, row, 1, HorizontalAlignment.CENTER_SELECTION, VerticalAlignment.BOTTOM); + createCell(wb, row, 2, HorizontalAlignment.FILL, VerticalAlignment.CENTER); + createCell(wb, row, 3, HorizontalAlignment.GENERAL, VerticalAlignment.CENTER); + createCell(wb, row, 4, HorizontalAlignment.JUSTIFY, VerticalAlignment.JUSTIFY); + createCell(wb, row, 5, HorizontalAlignment.LEFT, VerticalAlignment.TOP); + createCell(wb, row, 6, HorizontalAlignment.RIGHT, VerticalAlignment.TOP); + + // Write the output to a file + try (OutputStream fileOut = new FileOutputStream("xssf-align.xlsx")) { + wb.write(fileOut); + } + + wb.close(); + } + + /** + * Creates a cell and aligns it a certain way. + * + * @param wb the workbook + * @param row the row to create the cell in + * @param column the column number to create the cell in + * @param halign the horizontal alignment for the cell. + * @param valign the vertical alignment for the cell. + */ + private static void createCell(Workbook wb, Row row, int column, HorizontalAlignment halign, VerticalAlignment valign) { + Cell cell = row.createCell(column); + cell.setCellValue("Align It"); + CellStyle cellStyle = wb.createCellStyle(); + cellStyle.setAlignment(halign); + cellStyle.setVerticalAlignment(valign); + cell.setCellStyle(cellStyle); + } + </source> + </section> + <anchor id="Borders"/> + <section><title>Working with borders</title> + <source> + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("new sheet"); + + // Create a row and put some cells in it. Rows are 0 based. + Row row = sheet.createRow(1); + + // Create a cell and put a value in it. + Cell cell = row.createCell(1); + cell.setCellValue(4); + + // Style the cell with borders all around. + CellStyle style = wb.createCellStyle(); + style.setBorderBottom(BorderStyle.THIN); + style.setBottomBorderColor(IndexedColors.BLACK.getIndex()); + style.setBorderLeft(BorderStyle.THIN); + style.setLeftBorderColor(IndexedColors.GREEN.getIndex()); + style.setBorderRight(BorderStyle.THIN); + style.setRightBorderColor(IndexedColors.BLUE.getIndex()); + style.setBorderTop(BorderStyle.MEDIUM_DASHED); + style.setTopBorderColor(IndexedColors.BLACK.getIndex()); + cell.setCellStyle(style); + + // Write the output to a file + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + + wb.close(); + </source> + </section> + <anchor id="Iterator"/> + <section><title>Iterate over rows and cells</title> + <p>Sometimes, you'd like to just iterate over all the sheets in + a workbook, all the rows in a sheet, or all the cells in a row. + This is possible with a simple for loop.</p> + <p>These iterators are available by calling <em>workbook.sheetIterator()</em>, + <em>sheet.rowIterator()</em>, and <em>row.cellIterator()</em>, or + implicitly using a for-each loop. + Note that a rowIterator and cellIterator iterate over rows or + cells that have been created, skipping empty rows and cells.</p> + + <source> + for (Sheet sheet : wb ) { + for (Row row : sheet) { + for (Cell cell : row) { + // Do something here + } + } + } + </source> + </section> + <section><title>Iterate over cells, with control of missing / blank cells</title> + <p>In some cases, when iterating, you need full control over how + missing or blank rows and cells are treated, and you need to ensure + you visit every cell and not just those defined in the file. (The + CellIterator will only return the cells defined in the file, which + is largely those with values or stylings, but it depends on Excel).</p> + <p>In cases such as these, you should fetch the first and last column + information for a row, then call <em>getCell(int, MissingCellPolicy)</em> + to fetch the cell. Use a + <a href="../../apidocs/dev/org/apache/poi/ss/usermodel/Row.MissingCellPolicy.html">MissingCellPolicy</a> + to control how blank or null cells are handled.</p> + <source> + // Decide which rows to process + int rowStart = Math.min(15, sheet.getFirstRowNum()); + int rowEnd = Math.max(1400, sheet.getLastRowNum()); + + for (int rowNum = rowStart; rowNum < rowEnd; rowNum++) { + Row r = sheet.getRow(rowNum); + if (r == null) { + // This whole row is empty + // Handle it as needed + continue; + } + + int lastColumn = Math.max(r.getLastCellNum(), MY_MINIMUM_COLUMN_COUNT); + + for (int cn = 0; cn < lastColumn; cn++) { + Cell c = r.getCell(cn, Row.RETURN_BLANK_AS_NULL); + if (c == null) { + // The spreadsheet is empty in this cell + } else { + // Do something useful with the cell's contents + } + } + } + </source> + </section> + + <anchor id="CellContents"/> + <section><title>Getting the cell contents</title> + <p>To get the contents of a cell, you first need to + know what kind of cell it is (asking a string cell + for its numeric contents will get you a + NumberFormatException for example). So, you will + want to switch on the cell's type, and then call + the appropriate getter for that cell.</p> + <p>In the code below, we loop over every cell + in one sheet, print out the cell's reference + (eg A3), and then the cell's contents.</p> + <source> + // import org.apache.poi.ss.usermodel.*; + + DataFormatter formatter = new DataFormatter(); + Sheet sheet1 = wb.getSheetAt(0); + for (Row row : sheet1) { + for (Cell cell : row) { + CellReference cellRef = new CellReference(row.getRowNum(), cell.getColumnIndex()); + System.out.print(cellRef.formatAsString()); + System.out.print(" - "); + + // get the text that appears in the cell by getting the cell value and applying any data formats (Date, 0.00, 1.23e9, $1.23, etc) + String text = formatter.formatCellValue(cell); + System.out.println(text); + + // Alternatively, get the value and format it yourself + switch (cell.getCellType()) { + case CellType.STRING: + System.out.println(cell.getRichStringCellValue().getString()); + break; + case CellType.NUMERIC: + if (DateUtil.isCellDateFormatted(cell)) { + System.out.println(cell.getDateCellValue()); + } else { + System.out.println(cell.getNumericCellValue()); + } + break; + case CellType.BOOLEAN: + System.out.println(cell.getBooleanCellValue()); + break; + case CellType.FORMULA: + System.out.println(cell.getCellFormula()); + break; + case CellType.BLANK: + System.out.println(); + break; + default: + System.out.println(); + } + } + } + </source> + </section> + + <anchor id="TextExtraction"/> + <section><title>Text Extraction</title> + <p>For most text extraction requirements, the standard + ExcelExtractor class should provide all you need.</p> + <source> + try (InputStream inp = new FileInputStream("workbook.xls")) { + HSSFWorkbook wb = new HSSFWorkbook(new POIFSFileSystem(inp)); + ExcelExtractor extractor = new ExcelExtractor(wb); + + extractor.setFormulasNotResults(true); + extractor.setIncludeSheetNames(false); + String text = extractor.getText(); + wb.close(); + } + </source> + <p>For very fancy text extraction, XLS to CSV etc, + take a look at + <em>/poi-examples/src/main/java/org/apache/poi/examples/hssf/eventusermodel/XLS2CSVmra.java</em> + </p> + </section> + <anchor id="FillsAndFrills"/> + <section><title>Fills and colors</title> + <source> + Workbook wb = new XSSFWorkbook(); + Sheet sheet = wb.createSheet("new sheet"); + + // Create a row and put some cells in it. Rows are 0 based. + Row row = sheet.createRow(1); + + // Aqua background + CellStyle style = wb.createCellStyle(); + style.setFillBackgroundColor(IndexedColors.AQUA.getIndex()); + style.setFillPattern(FillPatternType.BIG_SPOTS); + Cell cell = row.createCell(1); + cell.setCellValue("X"); + cell.setCellStyle(style); + + // Orange "foreground", foreground being the fill foreground not the font color. + style = wb.createCellStyle(); + style.setFillForegroundColor(IndexedColors.ORANGE.getIndex()); + style.setFillPattern(FillPatternType.SOLID_FOREGROUND); + cell = row.createCell(2); + cell.setCellValue("X"); + cell.setCellStyle(style); + + // Write the output to a file + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + + wb.close(); + </source> + </section> + <anchor id="MergedCells"/> + <section><title>Merging cells</title> + <source> + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("new sheet"); + + Row row = sheet.createRow(1); + Cell cell = row.createCell(1); + cell.setCellValue("This is a test of merging"); + + sheet.addMergedRegion(new CellRangeAddress( + 1, //first row (0-based) + 1, //last row (0-based) + 1, //first column (0-based) + 2 //last column (0-based) + )); + + // Write the output to a file + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + + wb.close(); + </source> + </section> + <anchor id="WorkingWithFonts"/> + <section><title>Working with fonts</title> + <source> + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("new sheet"); + + // Create a row and put some cells in it. Rows are 0 based. + Row row = sheet.createRow(1); + + // Create a new font and alter it. + Font font = wb.createFont(); + font.setFontHeightInPoints((short)24); + font.setFontName("Courier New"); + font.setItalic(true); + font.setStrikeout(true); + + // Fonts are set into a style so create a new one to use. + CellStyle style = wb.createCellStyle(); + style.setFont(font); + + // Create a cell and put a value in it. + Cell cell = row.createCell(1); + cell.setCellValue("This is a test of fonts"); + cell.setCellStyle(style); + + // Write the output to a file + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + + wb.close(); + </source> +<p> + Note, the maximum number of unique fonts in a workbook is limited to 32767. You should re-use fonts in your applications instead of + creating a font for each cell. +Examples: +</p> +<p><strong>Wrong:</strong></p> +<source> + for (int i = 0; i < 10000; i++) { + Row row = sheet.createRow(i); + Cell cell = row.createCell(0); + + CellStyle style = workbook.createCellStyle(); + Font font = workbook.createFont(); + font.setBoldweight(Font.BOLDWEIGHT_BOLD); + style.setFont(font); + cell.setCellStyle(style); + } +</source> +<p><strong>Correct:</strong></p> +<source> + CellStyle style = workbook.createCellStyle(); + Font font = workbook.createFont(); + font.setBoldweight(Font.BOLDWEIGHT_BOLD); + style.setFont(font); + for (int i = 0; i < 10000; i++) { + Row row = sheet.createRow(i); + Cell cell = row.createCell(0); + cell.setCellStyle(style); + } +</source> + + </section> + <anchor id="CustomColors"/> + <section><title>Custom colors</title> + <p><strong>HSSF:</strong></p> + <source> + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet(); + HSSFRow row = sheet.createRow(0); + HSSFCell cell = row.createCell(0); + cell.setCellValue("Default Palette"); + + //apply some colors from the standard palette, + // as in the previous examples. + //we'll use red text on a lime background + + HSSFCellStyle style = wb.createCellStyle(); + style.setFillForegroundColor(HSSFColor.LIME.index); + style.setFillPattern(FillPatternType.SOLID_FOREGROUND); + + HSSFFont font = wb.createFont(); + font.setColor(HSSFColor.RED.index); + style.setFont(font); + + cell.setCellStyle(style); + + //save with the default palette + try (OutputStream out = new FileOutputStream("default_palette.xls")) { + wb.write(out); + } + + //now, let's replace RED and LIME in the palette + // with a more attractive combination + // (lovingly borrowed from freebsd.org) + + cell.setCellValue("Modified Palette"); + + //creating a custom palette for the workbook + HSSFPalette palette = wb.getCustomPalette(); + + //replacing the standard red with freebsd.org red + palette.setColorAtIndex(HSSFColor.RED.index, + (byte) 153, //RGB red (0-255) + (byte) 0, //RGB green + (byte) 0 //RGB blue + ); + //replacing lime with freebsd.org gold + palette.setColorAtIndex(HSSFColor.LIME.index, (byte) 255, (byte) 204, (byte) 102); + + //save with the modified palette + // note that wherever we have previously used RED or LIME, the + // new colors magically appear + try (out = new FileOutputStream("modified_palette.xls")) { + wb.write(out); + } + </source> + <p><strong>XSSF:</strong></p> + <source> + XSSFWorkbook wb = new XSSFWorkbook(); + XSSFSheet sheet = wb.createSheet(); + XSSFRow row = sheet.createRow(0); + XSSFCell cell = row.createCell( 0); + cell.setCellValue("custom XSSF colors"); + + XSSFCellStyle style1 = wb.createCellStyle(); + style1.setFillForegroundColor(new XSSFColor(new java.awt.Color(128, 0, 128), new DefaultIndexedColorMap())); + style1.setFillPattern(FillPatternType.SOLID_FOREGROUND); + </source> + </section> + <anchor id="ReadWriteWorkbook"/> + <section><title>Reading and Rewriting Workbooks</title> + <source> + try (InputStream inp = new FileInputStream("workbook.xls")) { + //InputStream inp = new FileInputStream("workbook.xlsx"); + + Workbook wb = WorkbookFactory.create(inp); + Sheet sheet = wb.getSheetAt(0); + Row row = sheet.getRow(2); + Cell cell = row.getCell(3); + if (cell == null) + cell = row.createCell(3); + cell.setCellType(CellType.STRING); + cell.setCellValue("a test"); + + // Write the output to a file + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + } + </source> + </section> + <anchor id="NewLinesInCells"/> + <section><title>Using newlines in cells</title> + <source> + Workbook wb = new XSSFWorkbook(); //or new HSSFWorkbook(); + Sheet sheet = wb.createSheet(); + + Row row = sheet.createRow(2); + Cell cell = row.createCell(2); + cell.setCellValue("Use \n with word wrap on to create a new line"); + + //to enable newlines you need set a cell styles with wrap=true + CellStyle cs = wb.createCellStyle(); + cs.setWrapText(true); + cell.setCellStyle(cs); + + //increase row height to accommodate two lines of text + row.setHeightInPoints((2*sheet.getDefaultRowHeightInPoints())); + + //adjust column width to fit the content + sheet.autoSizeColumn(2); + + try (OutputStream fileOut = new FileOutputStream("ooxml-newlines.xlsx")) { + wb.write(fileOut); + } + + wb.close(); + </source> + </section> + <anchor id="DataFormats"/> + <section><title>Data Formats</title> + <source> + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("format sheet"); + CellStyle style; + DataFormat format = wb.createDataFormat(); + Row row; + Cell cell; + int rowNum = 0; + int colNum = 0; + + row = sheet.createRow(rowNum++); + cell = row.createCell(colNum); + cell.setCellValue(11111.25); + style = wb.createCellStyle(); + style.setDataFormat(format.getFormat("0.0")); + cell.setCellStyle(style); + + row = sheet.createRow(rowNum++); + cell = row.createCell(colNum); + cell.setCellValue(11111.25); + style = wb.createCellStyle(); + style.setDataFormat(format.getFormat("#,##0.0000")); + cell.setCellStyle(style); + + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + + wb.close(); + </source> + </section> + <anchor id="FitTo"/> + <section><title>Fit Sheet to One Page</title> + <source> + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("format sheet"); + PrintSetup ps = sheet.getPrintSetup(); + + sheet.setAutobreaks(true); + + ps.setFitHeight((short)1); + ps.setFitWidth((short)1); + + + // Create various cells and rows for spreadsheet. + + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + + wb.close(); + </source> + </section> + <anchor id="PrintArea2"/> + <section><title>Set Print Area</title> + <source> + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("Sheet1"); + //sets the print area for the first sheet + wb.setPrintArea(0, "$A$1:$C$2"); + + //Alternatively: + wb.setPrintArea( + 0, //sheet index + 0, //start column + 1, //end column + 0, //start row + 0 //end row + ); + + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + + wb.close(); + </source> + </section> + + <anchor id="FooterPageNumbers"/> + <section><title>Set Page Numbers on Footer</title> + <source> + Workbook wb = new HSSFWorkbook(); // or new XSSFWorkbook(); + Sheet sheet = wb.createSheet("format sheet"); + Footer footer = sheet.getFooter(); + + footer.setRight( "Page " + HeaderFooter.page() + " of " + HeaderFooter.numPages() ); + + + + // Create various cells and rows for spreadsheet. + + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + + wb.close(); + </source> + </section> + + <anchor id="ConvenienceFunctions"/> + <section><title>Using the Convenience Functions</title> + <p> + The convenience functions provide + utility features such as setting borders around merged + regions and changing style attributes without explicitly + creating new styles. + </p> + <source> + Workbook wb = new HSSFWorkbook(); // or new XSSFWorkbook() + Sheet sheet1 = wb.createSheet( "new sheet" ); + + // Create a merged region + Row row = sheet1.createRow( 1 ); + Row row2 = sheet1.createRow( 2 ); + Cell cell = row.createCell( 1 ); + cell.setCellValue( "This is a test of merging" ); + CellRangeAddress region = CellRangeAddress.valueOf("B2:E5"); + sheet1.addMergedRegion( region ); + + // Set the border and border colors. + RegionUtil.setBorderBottom( BorderStyle.MEDIUM_DASHED, region, sheet1, wb ); + RegionUtil.setBorderTop( BorderStyle.MEDIUM_DASHED, region, sheet1, wb ); + RegionUtil.setBorderLeft( BorderStyle.MEDIUM_DASHED, region, sheet1, wb ); + RegionUtil.setBorderRight( BorderStyle.MEDIUM_DASHED, region, sheet1, wb ); + RegionUtil.setBottomBorderColor(IndexedColors.AQUA.getIndex(), region, sheet1, wb); + RegionUtil.setTopBorderColor( IndexedColors.AQUA.getIndex(), region, sheet1, wb); + RegionUtil.setLeftBorderColor( IndexedColors.AQUA.getIndex(), region, sheet1, wb); + RegionUtil.setRightBorderColor( IndexedColors.AQUA.getIndex(), region, sheet1, wb); + + // Shows some usages of HSSFCellUtil + CellStyle style = wb.createCellStyle(); + style.setIndention((short)4); + CellUtil.createCell(row, 8, "This is the value of the cell", style); + Cell cell2 = CellUtil.createCell( row2, 8, "This is the value of the cell"); + CellUtil.setAlignment(cell2, HorizontalAlignment.CENTER); + + // Write out the workbook + try (OutputStream fileOut = new FileOutputStream( "workbook.xls" )) { + wb.write( fileOut ); + } + + wb.close(); + </source> + </section> + + <anchor id="ShiftRows"/> + <section><title>Shift rows up or down on a sheet</title> + <source> + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("row sheet"); + + // Create various cells and rows for spreadsheet. + + // Shift rows 6 - 11 on the spreadsheet to the top (rows 0 - 5) + sheet.shiftRows(5, 10, -5); + + </source> + </section> + + <anchor id="SelectSheet"/> + <section><title>Set a sheet as selected</title> + <source> + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("row sheet"); + sheet.setSelected(true); + + </source> + </section> + + <anchor id="Zoom"/> + <section><title>Set the zoom magnification</title> + <p> + The zoom is expressed as a fraction. For example to + express a zoom of 75% use 3 for the numerator and + 4 for the denominator. + </p> + <source> + Workbook wb = new HSSFWorkbook(); + Sheet sheet1 = wb.createSheet("new sheet"); + sheet1.setZoom(75); // 75 percent magnification + </source> + </section> + + <anchor id="Splits"/> + <section><title>Splits and freeze panes</title> + <p> + There are two types of panes you can create; freeze panes and split panes. + </p> + <p> + A freeze pane is split by columns and rows. You create + a freeze pane using the following mechanism: + </p> + <p> + sheet1.createFreezePane( 3, 2, 3, 2 ); + </p> + <p> + The first two parameters are the columns and rows you + wish to split by. The second two parameters indicate + the cells that are visible in the bottom right quadrant. + </p> + <p> + + Split panes appear differently. The split area is + divided into four separate work area's. The split + occurs at the pixel level and the user is able to + adjust the split by dragging it to a new position. + </p> + <p> + + Split panes are created with the following call: + </p> + <p> + sheet2.createSplitPane( 2000, 2000, 0, 0, Sheet.PANE_LOWER_LEFT ); + </p> + <p> + + The first parameter is the x position of the split. + This is in 1/20th of a point. A point in this case + seems to equate to a pixel. The second parameter is + the y position of the split. Again in 1/20th of a point. + </p> + <p> + The last parameter indicates which pane currently has + the focus. This will be one of Sheet.PANE_LOWER_LEFT, + PANE_LOWER_RIGHT, PANE_UPPER_RIGHT or PANE_UPPER_LEFT. + </p> + <source> + Workbook wb = new HSSFWorkbook(); + Sheet sheet1 = wb.createSheet("new sheet"); + Sheet sheet2 = wb.createSheet("second sheet"); + Sheet sheet3 = wb.createSheet("third sheet"); + Sheet sheet4 = wb.createSheet("fourth sheet"); + + // Freeze just one row + sheet1.createFreezePane( 0, 1, 0, 1 ); + // Freeze just one column + sheet2.createFreezePane( 1, 0, 1, 0 ); + // Freeze the columns and rows (forget about scrolling position of the lower right quadrant). + sheet3.createFreezePane( 2, 2 ); + // Create a split with the lower left side being the active quadrant + sheet4.createSplitPane( 2000, 2000, 0, 0, Sheet.PANE_LOWER_LEFT ); + + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + </source> + </section> + + <anchor id="Repeating"/> + <section><title>Repeating rows and columns</title> + <p> + It's possible to set up repeating rows and columns in + your printouts by using the setRepeatingRows() and + setRepeatingColumns() methods in the Sheet class. + </p> + <p> + These methods expect a CellRangeAddress parameter + which specifies the range for the rows or columns to + repeat. + For setRepeatingRows(), it should specify a range of + rows to repeat, with the column part spanning all + columns. + For setRepeatingColumns(), it should specify a range of + columns to repeat, with the row part spanning all + rows. + If the parameter is null, the repeating rows or columns + will be removed. + </p> + <source> + Workbook wb = new HSSFWorkbook(); // or new XSSFWorkbook(); + Sheet sheet1 = wb.createSheet("Sheet1"); + Sheet sheet2 = wb.createSheet("Sheet2"); + + // Set the rows to repeat from row 4 to 5 on the first sheet. + sheet1.setRepeatingRows(CellRangeAddress.valueOf("4:5")); + // Set the columns to repeat from column A to C on the second sheet + sheet2.setRepeatingColumns(CellRangeAddress.valueOf("A:C")); + + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + </source> + </section> + <anchor id="HeaderFooter"/> + <section><title>Headers and Footers</title> + <p> + Example is for headers but applies directly to footers. + </p> + <source> + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("new sheet"); + + Header header = sheet.getHeader(); + header.setCenter("Center Header"); + header.setLeft("Left Header"); + header.setRight(HSSFHeader.font("Stencil-Normal", "Italic") + + HSSFHeader.fontSize((short) 16) + "Right w/ Stencil-Normal Italic font and size 16"); + + try (OutputStream fileOut = new FileOutputStream("workbook.xls")) { + wb.write(fileOut); + } + </source> + </section> + <anchor id="XSSFHeaderFooter"/> + <section><title>XSSF Enhancement for Headers and Footers</title> + <p> + Example is for headers but applies directly to footers. Note, the above example for + basic headers and footers applies to XSSF Workbooks as well as HSSF Workbooks. The HSSFHeader + stuff does not work for XSSF Workbooks. + </p> + <p> + XSSF has the ability to handle First page headers and footers, as well as Even/Odd + headers and footers. All Header/Footer Property flags can be handled in XSSF as well. + The odd header and footer is the default header and footer. It is displayed on all + pages that do not display either a first page header or an even page header. That is, + if the Even header/footer does not exist, then the odd header/footer is displayed on + even pages. If the first page header/footer does not exist, then the odd header/footer + is displayed on the first page. If the even/odd property is not set, that is the same as + the even header/footer not existing. If the first page property does not exist, that is + the same as the first page header/footer not existing. + </p> + <source> + Workbook wb = new XSSFWorkbook(); + XSSFSheet sheet = (XSSFSheet) wb.createSheet("new sheet"); + + // Create a first page header + Header header = sheet.getFirstHeader(); + header.setCenter("Center First Page Header"); + header.setLeft("Left First Page Header"); + header.setRight("Right First Page Header"); + + // Create an even page header + Header header2 = sheet.getEvenHeader(); + header2.setCenter("Center Even Page Header"); + header2.setLeft("Left Even Page Header"); + header2.setRight("Right Even Page Header"); + + // Create an odd page header + Header header3 = sheet.getOddHeader(); + header3.setCenter("Center Odd Page Header"); + header3.setLeft("Left Odd Page Header"); + header3.setRight("Right Odd Page Header"); + + // Set/Remove Header properties + XSSFHeaderProperties prop = sheet.getHeaderFooterProperties(); + prop.setAlignWithMargins(); + prop.scaleWithDoc(); + prop.removeDifferentFirstPage(); // This does not remove first page headers or footers + prop.removeDifferentEvenOdd(); // This does not remove even headers or footers + + try (OutputStream fileOut = new FileOutputStream("workbook.xlsx")) { + wb.write(fileOut); + } + </source> + </section> + + <anchor id="DrawingShapes"/> + <section><title>Drawing Shapes</title> + <p> + POI supports drawing shapes using the Microsoft Office + drawing tools. Shapes on a sheet are organized in a + hierarchy of groups and and shapes. The top-most shape + is the patriarch. This is not visible on the sheet + at all. To start drawing you need to call <code>createPatriarch</code> + on the <code>HSSFSheet</code> class. This has the + effect erasing any other shape information stored + in that sheet. By default POI will leave shape + records alone in the sheet unless you make a call to + this method. + </p> + <p> + To create a shape you have to go through the following + steps: + </p> + <ol> + <li>Create the patriarch.</li> + <li>Create an anchor to position the shape on the sheet.</li> + <li>Ask the patriarch to create the shape.</li> + <li>Set the shape type (line, oval, rectangle etc...)</li> + <li>Set any other style details concerning the shape. (eg: + line thickness, etc...)</li> + </ol> + <source> + HSSFPatriarch patriarch = sheet.createDrawingPatriarch(); + a = new HSSFClientAnchor( 0, 0, 1023, 255, (short) 1, 0, (short) 1, 0 ); + HSSFSimpleShape shape1 = patriarch.createSimpleShape(a1); + shape1.setShapeType(HSSFSimpleShape.OBJECT_TYPE_LINE); + </source> + <p> + Text boxes are created using a different call: + </p> + <source> + HSSFTextbox textbox1 = patriarch.createTextbox( + new HSSFClientAnchor(0,0,0,0,(short)1,1,(short)2,2)); + textbox1.setString(new HSSFRichTextString("This is a test") ); + </source> + <p> + It's possible to use different fonts to style parts of + the text in the textbox. Here's how: + </p> + <source> + HSSFFont font = wb.createFont(); + font.setItalic(true); + font.setUnderline(HSSFFont.U_DOUBLE); + HSSFRichTextString string = new HSSFRichTextString("Woo!!!"); + string.applyFont(2,5,font); + textbox.setString(string ); + </source> + <p> + Just as can be done manually using Excel, it is possible + to group shapes together. This is done by calling + <code>createGroup()</code> and then creating the shapes + using those groups. + </p> + <p> + It's also possible to create groups within groups. + </p> + <warning>Any group you create should contain at least two + other shapes or subgroups.</warning> + <p> + Here's how to create a shape group: + </p> + <source> + // Create a shape group. + HSSFShapeGroup group = patriarch.createGroup( + new HSSFClientAnchor(0,0,900,200,(short)2,2,(short)2,2)); + + // Create a couple of lines in the group. + HSSFSimpleShape shape1 = group.createShape(new HSSFChildAnchor(3,3,500,500)); + shape1.setShapeType(HSSFSimpleShape.OBJECT_TYPE_LINE); + ( (HSSFChildAnchor) shape1.getAnchor() ).setAnchor(3,3,500,500); + HSSFSimpleShape shape2 = group.createShape(new HSSFChildAnchor(1,200,400,600)); + shape2.setShapeType(HSSFSimpleShape.OBJECT_TYPE_LINE); + </source> + <p> + If you're being observant you'll noticed that the shapes + that are added to the group use a new type of anchor: + the <code>HSSFChildAnchor</code>. What happens is that + the created group has its own coordinate space for + shapes that are placed into it. POI defaults this to + (0,0,1023,255) but you are able to change it as desired. + Here's how: + </p> + <source> + myGroup.setCoordinates(10,10,20,20); // top-left, bottom-right + </source> + <p> + If you create a group within a group it's also going + to have its own coordinate space. + </p> + </section> + + <anchor id="StylingShapes"/> + <section><title>Styling Shapes</title> + <p> + By default shapes can look a little plain. It's possible + to apply different styles to the shapes however. The + sorts of things that can currently be done are: + </p> + <ul> + <li>Change the fill color.</li> + <li>Make a shape with no fill color.</li> + <li>Change the thickness of the lines.</li> + <li>Change the style of the lines. Eg: dashed, dotted.</li> + <li>Change the line color.</li> + </ul> + <p> + Here's an examples of how this is done: + </p> + <source> + HSSFSimpleShape s = patriarch.createSimpleShape(a); + s.setShapeType(HSSFSimpleShape.OBJECT_TYPE_OVAL); + s.setLineStyleColor(10,10,10); + s.setFillColor(90,10,200); + s.setLineWidth(HSSFShape.LINEWIDTH_ONE_PT * 3); + s.setLineStyle(HSSFShape.LINESTYLE_DOTSYS); + </source> + </section> + <anchor id="Graphics2d"/> + <section><title>Shapes and Graphics2d</title> + <p> + While the native POI shape drawing commands are the + recommended way to draw shapes in a shape it's sometimes + desirable to use a standard API for compatibility with + external libraries. With this in mind we created some + wrappers for <code>Graphics</code> and <code>Graphics2d</code>. + </p> + <warning> + It's important to not however before continuing that + <code>Graphics2d</code> is a poor match to the capabilities + of the Microsoft Office drawing commands. The older + <code>Graphics</code> class offers a closer match but is + still a square peg in a round hole. + </warning> + <p> + All Graphics commands are issued into an <code>HSSFShapeGroup</code>. + Here's how it's done: + </p> + <source> + a = new HSSFClientAnchor( 0, 0, 1023, 255, (short) 1, 0, (short) 1, 0 ); + group = patriarch.createGroup( a ); + group.setCoordinates( 0, 0, 80 * 4 , 12 * 23 ); + float verticalPointsPerPixel = a.getAnchorHeightInPoints(sheet) / (float)Math.abs(group.getY2() - group.getY1()); + g = new EscherGraphics( group, wb, Color.black, verticalPointsPerPixel ); + g2d = new EscherGraphics2d( g ); + drawChemicalStructure( g2d ); + </source> + <p> + The first thing we do is create the group and set its coordinates + to match what we plan to draw. Next we calculate a reasonable + fontSizeMultiplier then create the EscherGraphics object. + Since what we really want is a <code>Graphics2d</code> + object we create an EscherGraphics2d object and pass in + the graphics object we created. Finally we call a routine + that draws into the EscherGraphics2d object. + </p> + <p> + The vertical points per pixel deserves some more explanation. + One of the difficulties in converting Graphics calls + into escher drawing calls is that Excel does not have + the concept of absolute pixel positions. It measures + its cell widths in 'characters' and the cell heights in points. + Unfortunately it's not defined exactly what type of character it's + measuring. Presumably this is due to the fact that the Excel will be + using different fonts on different platforms or even within the same + platform. + </p> + <p> + Because of this constraint we've had to implement the concept of a + verticalPointsPerPixel. This the amount the font should be scaled by when + you issue commands such as drawString(). To calculate this value + use the follow formula: + </p> + <source> + multipler = groupHeightInPoints / heightOfGroup + </source> + <p> + The height of the group is calculated fairly simply by calculating the + difference between the y coordinates of the bounding box of the shape. The + height of the group can be calculated by using a convenience called + <code>HSSFClientAnchor.getAnchorHeightInPoints()</code>. + </p> + <p> + Many of the functions supported by the graphics classes + are not complete. Here's some of the functions that are known + to work. + </p> + <ul> + <li>fillRect()</li> + <li>fillOval()</li> + <li>drawString()</li> + <li>drawOval()</li> + <li>drawLine()</li> + <li>clearRect()</li> + </ul> + <p> + Functions that are not supported will return and log a message + using the POI logging infrastructure (disabled by default). + </p> + </section> + <anchor id="Outlining"/> + <section> + <title>Outlining</title> + <p> + Outlines are great for grouping sections of information + together and can be added easily to columns and rows + using the POI API. Here's how: + </p> + <source> + Workbook wb = new HSSFWorkbook(); + Sheet sheet1 = wb.createSheet("new sheet"); + + sheet1.groupRow( 5, 14 ); + sheet1.groupRow( 7, 14 ); + sheet1.groupRow( 16, 19 ); + + sheet1.groupColumn( 4, 7 ); + sheet1.groupColumn( 9, 12 ); + sheet1.groupColumn( 10, 11 ); + + try (OutputStream fileOut = new FileOutputStream(filename)) { + wb.write(fileOut); + } + </source> + <p> + To collapse (or expand) an outline use the following calls: + </p> + <source> + sheet1.setRowGroupCollapsed( 7, true ); + sheet1.setColumnGroupCollapsed( 4, true ); + </source> + <p> + The row/column you choose should contain an already + created group. It can be anywhere within the group. + </p> + </section> + </section> + </section> + <anchor id="Images"/> + <section> + <title>Images</title> + <p> + Images are part of the drawing support. To add an image just + call <code>createPicture()</code> on the drawing patriarch. + At the time of writing the following types are supported: + </p> + <ul> + <li>PNG</li> + <li>JPG</li> + <li>DIB</li> + </ul> + <p> + It should be noted that any existing drawings may be erased + once you add an image to a sheet. + </p> + <source> + //create a new workbook + Workbook wb = new XSSFWorkbook(); //or new HSSFWorkbook(); + + //add picture data to this workbook. + InputStream is = new FileInputStream("image1.jpeg"); + byte[] bytes = IOUtils.toByteArray(is); + int pictureIdx = wb.addPicture(bytes, Workbook.PICTURE_TYPE_JPEG); + is.close(); + + CreationHelper helper = wb.getCreationHelper(); + + //create sheet + Sheet sheet = wb.createSheet(); + + // Create the drawing patriarch. This is the top level container for all shapes. + Drawing drawing = sheet.createDrawingPatriarch(); + + //add a picture shape + ClientAnchor anchor = helper.createClientAnchor(); + //set top-left corner of the picture, + //subsequent call of Picture#resize() will operate relative to it + anchor.setCol1(3); + anchor.setRow1(2); + Picture pict = drawing.createPicture(anchor, pictureIdx); + + //auto-size picture relative to its top-left corner + pict.resize(); + + //save workbook + String file = "picture.xls"; + if(wb instanceof XSSFWorkbook) file += "x"; + try (OutputStream fileOut = new FileOutputStream(file)) { + wb.write(fileOut); + } + </source> + <warning> + Picture.resize() works only for JPEG and PNG. Other formats are not yet supported. + </warning> + <p>Reading images from a workbook:</p> + <source> + + List lst = workbook.getAllPictures(); + for (Iterator it = lst.iterator(); it.hasNext(); ) { + PictureData pict = (PictureData)it.next(); + String ext = pict.suggestFileExtension(); + byte[] data = pict.getData(); + if (ext.equals("jpeg")){ + try (OutputStream out = new FileOutputStream("pict.jpg")) { + out.write(data); + } + } + } + </source> + </section> + <anchor id="NamedRanges"/> + <section> + <title>Named Ranges and Named Cells</title> + <p> + Named Range is a way to refer to a group of cells by a name. Named Cell is a + degenerate case of Named Range in that the 'group of cells' contains exactly one + cell. You can create as well as refer to cells in a workbook by their named range. + When working with Named Ranges, the classes <code>org.apache.poi.ss.util.CellReference</code> + and <code>org.apache.poi.ss.util.AreaReference</code> are used. + </p> + <p> + Note: Using relative values like 'A1:B1' can lead to unexpected moving of + the cell that the name points to when working with the workbook in Microsoft Excel, + usually using absolute references like '$A$1:$B$1' avoids this, see also + <a href="https://superuser.com/a/1031047/126954">this discussion</a>. + </p> + <p> + Creating Named Range / Named Cell + </p> + <source> + // setup code + String sname = "TestSheet", cname = "TestName", cvalue = "TestVal"; + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet(sname); + sheet.createRow(0).createCell(0).setCellValue(cvalue); + + // 1. create named range for a single cell using areareference + Name namedCell = wb.createName(); + namedCell.setNameName(cname + "1"); + String reference = sname+"!$A$1:$A$1"; // area reference + namedCell.setRefersToFormula(reference); + + // 2. create named range for a single cell using cellreference + Name namedCel2 = wb.createName(); + namedCel2.setNameName(cname + "2"); + reference = sname+"!$A$1"; // cell reference + namedCel2.setRefersToFormula(reference); + + // 3. create named range for an area using AreaReference + Name namedCel3 = wb.createName(); + namedCel3.setNameName(cname + "3"); + reference = sname+"!$A$1:$C$5"; // area reference + namedCel3.setRefersToFormula(reference); + + // 4. create named formula + Name namedCel4 = wb.createName(); + namedCel4.setNameName("my_sum"); + namedCel4.setRefersToFormula("SUM(" + sname + "!$I$2:$I$6)"); + </source> + <p> + Reading from Named Range / Named Cell + </p> + <source> + // setup code + String cname = "TestName"; + Workbook wb = getMyWorkbook(); // retrieve workbook + + // retrieve the named range + int namedCellIdx = wb.getNameIndex(cellName); + Name aNamedCell = wb.getNameAt(namedCellIdx); + + // retrieve the cell at the named range and test its contents + AreaReference aref = new AreaReference(aNamedCell.getRefersToFormula()); + CellReference[] crefs = aref.getAllReferencedCells(); + for (int i=0; i<crefs.length; i++) { + Sheet s = wb.getSheet(crefs[i].getSheetName()); + Row r = sheet.getRow(crefs[i].getRow()); + Cell c = r.getCell(crefs[i].getCol()); + // extract the cell contents based on cell type etc. + } + </source> + <p> + Reading from non-contiguous Named Ranges + </p> + <source> + // Setup code + String cname = "TestName"; + Workbook wb = getMyWorkbook(); // retrieve workbook + + // Retrieve the named range + // Will be something like "$C$10,$D$12:$D$14"; + int namedCellIdx = wb.getNameIndex(cellName); + Name aNamedCell = wb.getNameAt(namedCellIdx); + + // Retrieve the cell at the named range and test its contents + // Will get back one AreaReference for C10, and + // another for D12 to D14 + AreaReference[] arefs = AreaReference.generateContiguous(aNamedCell.getRefersToFormula()); + for (int i=0; i<arefs.length; i++) { + // Only get the corners of the Area + // (use arefs[i].getAllReferencedCells() to get all cells) + CellReference[] crefs = arefs[i].getCells(); + for (int j=0; j<crefs.length; j++) { + // Check it turns into real stuff + Sheet s = wb.getSheet(crefs[j].getSheetName()); + Row r = s.getRow(crefs[j].getRow()); + Cell c = r.getCell(crefs[j].getCol()); + // Do something with this corner cell + } + } + </source> + <p> + Note, when a cell is deleted, Excel does not delete the + attached named range. As result, workbook can contain + named ranges that point to cells that no longer exist. + You should check the validity of a reference before + constructing AreaReference + </p> + <source> + if(name.isDeleted()){ + //named range points to a deleted cell. + } else { + AreaReference ref = new AreaReference(name.getRefersToFormula()); + } + </source> + </section> + <anchor id="CellComments"/> + <section><title>Cell Comments - HSSF and XSSF</title> + <p> + A comment is a rich text note that is attached to & + associated with a cell, separate from other cell content. + Comment content is stored separate from the cell, and is displayed in a drawing object (like a text box) + that is separate from, but associated with, a cell + </p> + <source> + Workbook wb = new XSSFWorkbook(); //or new HSSFWorkbook(); + + CreationHelper factory = wb.getCreationHelper(); + + Sheet sheet = wb.createSheet(); + + Row row = sheet.createRow(3); + Cell cell = row.createCell(5); + cell.setCellValue("F4"); + + Drawing drawing = sheet.createDrawingPatriarch(); + + // When the comment box is visible, have it show in a 1x3 space + ClientAnchor anchor = factory.createClientAnchor(); + anchor.setCol1(cell.getColumnIndex()); + anchor.setCol2(cell.getColumnIndex()+1); + anchor.setRow1(row.getRowNum()); + anchor.setRow2(row.getRowNum()+3); + + // Create the comment and set the text+author + Comment comment = drawing.createCellComment(anchor); + RichTextString str = factory.createRichTextString("Hello, World!"); + comment.setString(str); + comment.setAuthor("Apache POI"); + + // Assign the comment to the cell + cell.setCellComment(comment); + + String fname = "comment-xssf.xls"; + if(wb instanceof XSSFWorkbook) fname += "x"; + try (OutputStream out = new FileOutputStream(fname)) { + wb.write(out); + } + + wb.close(); + </source> + <p> + Reading cell comments + </p> + <source> + Cell cell = sheet.get(3).getColumn(1); + Comment comment = cell.getCellComment(); + if (comment != null) { + RichTextString str = comment.getString(); + String author = comment.getAuthor(); + } + // alternatively you can retrieve cell comments by (row, column) + comment = sheet.getCellComment(3, 1); + </source> + + <p>To get all the comments on a sheet:</p> + <source> + Map<CellAddress, Comment> comments = sheet.getCellComments(); + Comment commentA1 = comments.get(new CellAddress(0, 0)); + Comment commentB1 = comments.get(new CellAddress(0, 1)); + for (Entry<CellAddress, ? extends Comment> e : comments.entrySet()) { + CellAddress loc = e.getKey(); + Comment comment = e.getValue(); + System.out.println("Comment at " + loc + ": " + + "[" + comment.getAuthor() + "] " + comment.getString().getString()); + } + </source> + </section> + + <anchor id="Autofit"/> + <section><title>Adjust column width to fit the contents</title> + <source> + Sheet sheet = workbook.getSheetAt(0); + sheet.autoSizeColumn(0); //adjust width of the first column + sheet.autoSizeColumn(1); //adjust width of the second column + </source> + <p> + For SXSSFWorkbooks only, because the random access window is likely to exclude most of the rows + in the worksheet, which are needed for computing the best-fit width of a column, the columns must + be tracked for auto-sizing prior to flushing any rows. + </p> + <source> + SXSSFWorkbook workbook = new SXSSFWorkbook(); + SXSSFSheet sheet = workbook.createSheet(); + sheet.trackColumnForAutoSizing(0); + sheet.trackColumnForAutoSizing(1); + // If you have a Collection of column indices, see SXSSFSheet#trackColumnForAutoSizing(Collection<Integer>) + // or roll your own for-loop. + // Alternatively, use SXSSFSheet#trackAllColumnsForAutoSizing() if the columns that will be auto-sized aren't + // known in advance or you are upgrading existing code and are trying to minimize changes. Keep in mind + // that tracking all columns will require more memory and CPU cycles, as the best-fit width is calculated + // on all tracked columns on every row that is flushed. + + // create some cells + for (int r=0; r < 10; r++) { + Row row = sheet.createRow(r); + for (int c; c < 10; c++) { + Cell cell = row.createCell(c); + cell.setCellValue("Cell " + c.getAddress().formatAsString()); + } + } + + // Auto-size the columns. + sheet.autoSizeColumn(0); + sheet.autoSizeColumn(1); + </source> + <p> + Note, that Sheet#autoSizeColumn() does not evaluate formula cells, + the width of formula cells is calculated based on the cached formula result. + If your workbook has many formulas then it is a good idea to evaluate them before auto-sizing. + </p> + <warning> + To calculate column width Sheet.autoSizeColumn uses Java2D classes + that throw exception if graphical environment is not available. In case if graphical environment + is not available, you must tell Java that you are running in headless mode and + set the following system property: <code> java.awt.headless=true </code>. + You should also ensure that the fonts you use in your workbook are + available to Java. + </warning> + </section> + <anchor id="Hyperlinks"/> + <section><title>How to read hyperlinks</title> + <source> + Sheet sheet = workbook.getSheetAt(0); + + Cell cell = sheet.getRow(0).getCell(0); + Hyperlink link = cell.getHyperlink(); + if(link != null){ + System.out.println(link.getAddress()); + } + </source> + </section> + <section><title>How to create hyperlinks</title> + <source> + Workbook wb = new XSSFWorkbook(); //or new HSSFWorkbook(); + CreationHelper createHelper = wb.getCreationHelper(); + + //cell style for hyperlinks + //by default hyperlinks are blue and underlined + CellStyle hlink_style = wb.createCellStyle(); + Font hlink_font = wb.createFont(); + hlink_font.setUnderline(Font.U_SINGLE); + hlink_font.setColor(IndexedColors.BLUE.getIndex()); + hlink_style.setFont(hlink_font); + + Cell cell; + Sheet sheet = wb.createSheet("Hyperlinks"); + //URL + cell = sheet.createRow(0).createCell(0); + cell.setCellValue("URL Link"); + + Hyperlink link = createHelper.createHyperlink(HyperlinkType.URL); + link.setAddress("https://poi.apache.org/"); + cell.setHyperlink(link); + cell.setCellStyle(hlink_style); + + //link to a file in the current directory + cell = sheet.createRow(1).createCell(0); + cell.setCellValue("File Link"); + link = createHelper.createHyperlink(HyperlinkType.FILE); + link.setAddress("link1.xls"); + cell.setHyperlink(link); + cell.setCellStyle(hlink_style); + + //e-mail link + cell = sheet.createRow(2).createCell(0); + cell.setCellValue("Email Link"); + link = createHelper.createHyperlink(HyperlinkType.EMAIL); + //note, if subject contains white spaces, make sure they are url-encoded + link.setAddress("mailto:poi@apache.org?subject=Hyperlinks"); + cell.setHyperlink(link); + cell.setCellStyle(hlink_style); + + //link to a place in this workbook + + //create a target sheet and cell + Sheet sheet2 = wb.createSheet("Target Sheet"); + sheet2.createRow(0).createCell(0).setCellValue("Target Cell"); + + cell = sheet.createRow(3).createCell(0); + cell.setCellValue("Worksheet Link"); + Hyperlink link2 = createHelper.createHyperlink(HyperlinkType.DOCUMENT); + link2.setAddress("'Target Sheet'!A1"); + cell.setHyperlink(link2); + cell.setCellStyle(hlink_style); + + try (OutputStream out = new FileOutputStream("hyperinks.xlsx")) { + wb.write(out); + } + + wb.close(); + </source> + </section> + <anchor id="Validation"/> + <section><title>Data Validations</title> + <p> + As of version 3.8, POI has slightly different syntax to work with data validations with .xls and .xlsx formats. + </p> + <section> + <title>hssf.usermodel (binary .xls format)</title> + <p><strong>Check the value a user enters into a cell against one or more predefined value(s).</strong></p> + <p>The following code will limit the value the user can enter into cell A1 to one of three integer values, 10, 20 or 30.</p> + <source> + HSSFWorkbook workbook = new HSSFWorkbook(); + HSSFSheet sheet = workbook.createSheet("Data Validation"); + CellRangeAddressList addressList = new CellRangeAddressList( + 0, 0, 0, 0); + DVConstraint dvConstraint = DVConstraint.createExplicitListConstraint( + new String[]{"10", "20", "30"}); + DataValidation dataValidation = new HSSFDataValidation + (addressList, dvConstraint); + dataValidation.setSuppressDropDownArrow(true); + sheet.addValidationData(dataValidation); + </source> + <p><strong> Drop Down Lists:</strong></p> + <p>This code will do the same but offer the user a drop down list to select a value from.</p> + <source> + HSSFWorkbook workbook = new HSSFWorkbook(); + HSSFSheet sheet = workbook.createSheet("Data Validation"); + CellRangeAddressList addressList = new CellRangeAddressList( + 0, 0, 0, 0); + DVConstraint dvConstraint = DVConstraint.createExplicitListConstraint( + new String[]{"10", "20", "30"}); + DataValidation dataValidation = new HSSFDataValidation + (addressList, dvConstraint); + dataValidation.setSuppressDropDownArrow(false); + sheet.addValidationData(dataValidation); + </source> + <p><strong>Messages On Error:</strong></p> + <p>To create a message box that will be shown to the user if the value they enter is invalid.</p> + <source> + dataValidation.setErrorStyle(DataValidation.ErrorStyle.STOP); + dataValidation.createErrorBox("Box Title", "Message Text"); + </source> + <p>Replace 'Box Title' with the text you wish to display in the message box's title bar + and 'Message Text' with the text of your error message.</p> + <p><strong>Prompts:</strong></p> + <p>To create a prompt that the user will see when the cell containing the data validation receives focus</p> + <source> + dataValidation.createPromptBox("Title", "Message Text"); + dataValidation.setShowPromptBox(true); + </source> + <p>The text encapsulated in the first parameter passed to the createPromptBox() method will appear emboldened + and as a title to the prompt whilst the second will be displayed as the text of the message. + The createExplicitListConstraint() method can be passed and array of String(s) containing interger, floating point, dates or text values.</p> + + <p><strong>Further Data Validations:</strong></p> + <p>To obtain a validation that would check the value entered was, for example, an integer between 10 and 100, + use the DVConstraint.createNumericConstraint(int, int, String, String) factory method.</p> + <source> + dvConstraint = DVConstraint.createNumericConstraint( + DVConstraint.ValidationType.INTEGER, + DVConstraint.OperatorType.BETWEEN, "10", "100"); + </source> + <p>Look at the javadoc for the other validation and operator types; also note that not all validation + types are supported for this method. The values passed to the two String parameters can be formulas; the '=' symbol is used to denote a formula</p> + <source> + dvConstraint = DVConstraint.createNumericConstraint( + DVConstraint.ValidationType.INTEGER, + DVConstraint.OperatorType.BETWEEN, "=SUM(A1:A3)", "100"); + </source> + <p>It is not possible to create a drop down list if the createNumericConstraint() method is called, + the setSuppressDropDownArrow(false) method call will simply be ignored.</p> + <p>Date and time constraints can be created by calling the createDateConstraint(int, String, String, String) + or the createTimeConstraint(int, String, String). Both are very similar to the above and are explained in the javadoc. </p> + <p><strong>Creating Data Validations From Spreadsheet Cells.</strong></p> + <p>The contents of specific cells can be used to provide the values for the data validation + and the DVConstraint.createFormulaListConstraint(String) method supports this. + To specify that the values come from a contiguous range of cells do either of the following:</p> + <source> + dvConstraint = DVConstraint.createFormulaListConstraint("$A$1:$A$3"); + </source> + <p>or</p> + <source> + Name namedRange = workbook.createName(); + namedRange.setNameName("list1"); + namedRange.setRefersToFormula("$A$1:$A$3"); + dvConstraint = DVConstraint.createFormulaListConstraint("list1"); + </source> + <p>and in both cases the user will be able to select from a drop down list containing the values from cells A1, A2 and A3.</p> + <p>The data does not have to be as the data validation. To select the data from a different sheet however, the sheet + must be given a name when created and that name should be used in the formula. So assuming the existence of a sheet named 'Data Sheet' this will work:</p> + <source> + Name namedRange = workbook.createName(); + namedRange.setNameName("list1"); + namedRange.setRefersToFormula("'Data Sheet'!$A$1:$A$3"); + dvConstraint = DVConstraint.createFormulaListConstraint("list1"); + </source> + <p>as will this:</p> + <source> + dvConstraint = DVConstraint.createFormulaListConstraint("'Data Sheet'!$A$1:$A$3"); + </source> + <p>whilst this will not:</p> + <source> + Name namedRange = workbook.createName(); + namedRange.setNameName("list1"); + namedRange.setRefersToFormula("'Sheet1'!$A$1:$A$3"); + dvConstraint = DVConstraint.createFormulaListConstraint("list1"); + </source><p>and nor will this:</p><source> + dvConstraint = DVConstraint.createFormulaListConstraint("'Sheet1'!$A$1:$A$3"); + </source> + </section> + <section> + <title>xssf.usermodel (.xlsx format)</title> +<p> +Data validations work similarly when you are creating an xml based, SpreadsheetML, +workbook file; but there are differences. Explicit casts are required, for example, +in a few places as much of the support for data validations in the xssf stream was +built into the unifying ss stream, of which more later. Other differences are +noted with comments in the code. +</p> + +<p><strong>Check the value the user enters into a cell against one or more predefined value(s).</strong></p> +<source> + XSSFWorkbook workbook = new XSSFWorkbook(); + XSSFSheet sheet = workbook.createSheet("Data Validation"); + XSSFDataValidationHelper dvHelper = new XSSFDataValidationHelper(sheet); + XSSFDataValidationConstraint dvConstraint = (XSSFDataValidationConstraint) + dvHelper.createExplicitListConstraint(new String[]{"11", "21", "31"}); + CellRangeAddressList addressList = new CellRangeAddressList(0, 0, 0, 0); + XSSFDataValidation validation =(XSSFDataValidation)dvHelper.createValidation( + dvConstraint, addressList); + + // Here the boolean value false is passed to the setSuppressDropDownArrow() + // method. In the hssf.usermodel examples above, the value passed to this + // method is true. + validation.setSuppressDropDownArrow(false); + + // Note this extra method call. If this method call is omitted, or if the + // boolean value false is passed, then Excel will not validate the value the + // user enters into the cell. + validation.setShowErrorBox(true); + sheet.addValidationData(validation); +</source> + +<p><strong>Drop Down Lists:</strong></p> +<p>This code will do the same but offer the user a drop down list to select a value from.</p> +<source> + XSSFWorkbook workbook = new XSSFWorkbook(); + XSSFSheet sheet = workbook.createSheet("Data Validation"); + XSSFDataValidationHelper dvHelper = new XSSFDataValidationHelper(sheet); + XSSFDataValidationConstraint dvConstraint = (XSSFDataValidationConstraint) + dvHelper.createExplicitListConstraint(new String[]{"11", "21", "31"}); + CellRangeAddressList addressList = new CellRangeAddressList(0, 0, 0, 0); + XSSFDataValidation validation = (XSSFDataValidation)dvHelper.createValidation( + dvConstraint, addressList); + validation.setShowErrorBox(true); + sheet.addValidationData(validation); +</source> +<p>Note that the call to the setSuppressDropDowmArrow() method can either be simply excluded or replaced with:</p> +<source> + validation.setSuppressDropDownArrow(true); +</source> + +<p><strong>Prompts and Error Messages:</strong></p> +<p> +These both exactly mirror the hssf.usermodel so please refer to the 'Messages On Error:' and 'Prompts:' sections above. +</p> + +<p><strong>Further Data Validations:</strong></p> +<p> +To obtain a validation that would check the value entered was, for example, +an integer between 10 and 100, use the XSSFDataValidationHelper(s) createNumericConstraint(int, int, String, String) factory method. +</p> +<source> + + XSSFDataValidationConstraint dvConstraint = (XSSFDataValidationConstraint) + dvHelper.createNumericConstraint( + XSSFDataValidationConstraint.ValidationType.INTEGER, + XSSFDataValidationConstraint.OperatorType.BETWEEN, + "10", "100"); +</source> +<p> +The values passed to the final two String parameters can be formulas; the '=' symbol is used to denote a formula. +Thus, the following would create a validation the allows values only if they fall between the results of summing two cell ranges +</p> +<source> + XSSFDataValidationConstraint dvConstraint = (XSSFDataValidationConstraint) + dvHelper.createNumericConstraint( + XSSFDataValidationConstraint.ValidationType.INTEGER, + XSSFDataValidationConstraint.OperatorType.BETWEEN, + "=SUM(A1:A10)", "=SUM(B24:B27)"); +</source> +<p> +It is not possible to create a drop down list if the createNumericConstraint() method is called, +the setSuppressDropDownArrow(true) method call will simply be ignored. +</p> +<p> +Please check the javadoc for other constraint types as examples for those will not be included here. +There are, for example, methods defined on the XSSFDataValidationHelper class allowing you to create +the following types of constraint; date, time, decimal, integer, numeric, formula, text length and custom constraints. +</p> +<p><strong>Creating Data Validations From Spread Sheet Cells:</strong></p> +<p> +One other type of constraint not mentioned above is the formula list constraint. +It allows you to create a validation that takes it value(s) from a range of cells. This code +</p> +<source> +XSSFDataValidationConstraint dvConstraint = (XSSFDataValidationConstraint) + dvHelper.createFormulaListConstraint("$A$1:$F$1"); +</source> + +<p> +would create a validation that took it's values from cells in the range A1 to F1. +</p> +<p> +The usefulness of this technique can be extended if you use named ranges like this; +</p> + +<source> + XSSFName name = workbook.createName(); + name.setNameName("data"); + name.setRefersToFormula("$B$1:$F$1"); + XSSFDataValidationHelper dvHelper = new XSSFDataValidationHelper(sheet); + XSSFDataValidationConstraint dvConstraint = (XSSFDataValidationConstraint) + dvHelper.createFormulaListConstraint("data"); + CellRangeAddressList addressList = new CellRangeAddressList( + 0, 0, 0, 0); + XSSFDataValidation validation = (XSSFDataValidation) + dvHelper.createValidation(dvConstraint, addressList); + validation.setSuppressDropDownArrow(true); + validation.setShowErrorBox(true); + sheet.addValidationData(validation); +</source> +<p> +OpenOffice Calc has slightly different rules with regard to the scope of names. +Excel supports both Workbook and Sheet scope for a name but Calc does not, it seems only to support Sheet scope for a name. +Thus it is often best to fully qualify the name for the region or area something like this; +</p> +<source> + XSSFName name = workbook.createName(); + name.setNameName("data"); + name.setRefersToFormula("'Data Validation'!$B$1:$F$1"); + .... +</source> +<p> +This does open a further, interesting opportunity however and that is to place all of the data for the validation(s) into named ranges of cells on a hidden sheet within the workbook. These ranges can then be explicitly identified in the setRefersToFormula() method argument. +</p> + </section> + <section><title>ss.usermodel</title> +<p> +The classes within the ss.usermodel package allow developers to create code that can be used +to generate both binary (.xls) and SpreadsheetML (.xlsx) workbooks. +</p> +<p> +The techniques used to create data validations share much in common with the xssf.usermodel examples above. +As a result just one or two examples will be presented here. +</p> +<p><strong>Check the value the user enters into a cell against one or more predefined value(s).</strong></p> +<source> + Workbook workbook = new XSSFWorkbook(); // or new HSSFWorkbook + Sheet sheet = workbook.createSheet("Data Validation"); + DataValidationHelper dvHelper = sheet.getDataValidationHelper(); + DataValidationConstraint dvConstraint = dvHelper.createExplicitListConstraint( + new String[]{"13", "23", "33"}); + CellRangeAddressList addressList = new CellRangeAddressList(0, 0, 0, 0); + DataValidation validation = dvHelper.createValidation( + dvConstraint, addressList); + // Note the check on the actual type of the DataValidation object. + // If it is an instance of the XSSFDataValidation class then the + // boolean value 'false' must be passed to the setSuppressDropDownArrow() + // method and an explicit call made to the setShowErrorBox() method. + if(validation instanceof XSSFDataValidation) { + validation.setSuppressDropDownArrow(false); + validation.setShowErrorBox(true); + } + else { + // If the Datavalidation contains an instance of the HSSFDataValidation + // class then 'true' should be passed to the setSuppressDropDownArrow() + // method and the call to setShowErrorBox() is not necessary. + validation.setSuppressDropDownArrow(true); + } + sheet.addValidationData(validation); +</source> + +<p><strong>Drop Down Lists:</strong></p> + +<p>This code will do the same but offer the user a drop down list to select a value from.</p> + +<source> + Workbook workbook = new XSSFWorkbook(); // or new HSSFWorkbook + Sheet sheet = workbook.createSheet("Data Validation"); + DataValidationHelper dvHelper = sheet.getDataValidationHelper(); + DataValidationConstraint dvConstraint = dvHelper.createExplicitListConstraint( + new String[]{"13", "23", "33"}); + CellRangeAddressList addressList = new CellRangeAddressList(0, 0, 0, 0); + DataValidation validation = dvHelper.createValidation( + dvConstraint, addressList); + // Note the check on the actual type of the DataValidation object. + // If it is an instance of the XSSFDataValidation class then the + // boolean value 'false' must be passed to the setSuppressDropDownArrow() + // method and an explicit call made to the setShowErrorBox() method. + if(validation instanceof XSSFDataValidation) { + validation.setSuppressDropDownArrow(true); + validation.setShowErrorBox(true); + } + else { + // If the Datavalidation contains an instance of the HSSFDataValidation + // class then 'true' should be passed to the setSuppressDropDownArrow() + // method and the call to setShowErrorBox() is not necessary. + validation.setSuppressDropDownArrow(false); + } + sheet.addValidationData(validation); +</source> + +<p><strong>Prompts and Error Messages:</strong></p> +<p> +These both exactly mirror the hssf.usermodel so please refer to the 'Messages On Error:' and 'Prompts:' sections above. +</p> +<p> +As the differences between the ss.usermodel and xssf.usermodel examples are small - +restricted largely to the way the DataValidationHelper is obtained, the lack of any +need to explicitly cast data types and the small difference in behaviour between +the hssf and xssf interpretation of the setSuppressDropDowmArrow() method, +no further examples will be included in this section. +</p> +<p><strong>Advanced Data Validations.</strong></p> +<p><strong>Dependent Drop Down Lists.</strong></p> +<p> +In some cases, it may be necessary to present to the user a sheet which contains more than one drop down list. +Further, the choice the user makes in one drop down list may affect the options that are presented to them in +the second or subsequent drop down lists. One technique that may be used to implement this behaviour will now be explained. +</p> +<p> +There are two keys to the technique; one is to use named areas or regions of cells to hold the data for the drop down lists, +the second is to use the INDIRECT() function to convert between the name and the actual addresses of the cells. +In the example section there is a complete working example- called LinkedDropDownLists.java - +that demonstrates how to create linked or dependent drop down lists. Only the more relevant points are explained here. +</p> +<p> +To create two drop down lists where the options shown in the second depend upon the selection made in the first, +begin by creating a named region of cells to hold all of the data for populating the first drop down list. +Next, create a data validation that will look to this named area for its data, something like this; +</p> +<source> + CellRangeAddressList addressList = new CellRangeAddressList(0, 0, 0, 0); + DataValidationHelper dvHelper = sheet.getDataValidationHelper(); + DataValidationConstraint dvConstraint = dvHelper.createFormulaListConstraint( + "CHOICES"); + DataValidation validation = dvHelper.createValidation( + dvConstraint, addressList); + sheet.addValidationData(validation); +</source> +<p> +Note that the name of the area - in the example above it is 'CHOICES' - +is simply passed to the createFormulaListConstraint() method. This is sufficient +to cause Excel to populate the drop down list with data from that named region. +</p> +<p> +Next, for each of the options the user could select in the first drop down list, +create a matching named region of cells. The name of that region should match the +text the user could select in the first drop down list. Note, in the example, +all upper case letters are used in the names of the regions of cells. +</p> + +<p> +Now, very similar code can be used to create a second, linked, drop down list; +</p> + +<source> + CellRangeAddressList addressList = new CellRangeAddressList(0, 0, 1, 1); + DataValidationConstraint dvConstraint = dvHelper.createFormulaListConstraint( + "INDIRECT(UPPER($A$1))"); + DataValidation validation = dvHelper.createValidation( + dvConstraint, addressList); + sheet.addValidationData(validation); +</source> + +<p> +The key here is in the following Excel function - INDIRECT(UPPER($A$1)) - which is used to populate the second, +linked, drop down list. Working from the inner-most pair of brackets, it instructs Excel to look +at the contents of cell A1, to convert what it reads there into upper case – as upper case letters are used +in the names of each region - and then convert this name into the addresses of those cells that contain +the data to populate another drop down list. +</p> + </section> + </section> + <anchor id="Embedded"/> + <section><title>Embedded Objects</title> + <p>It is possible to perform more detailed processing of an embedded Excel, Word or PowerPoint document, + or to work with any other type of embedded object.</p> + <p><strong>HSSF:</strong></p> + <source> + POIFSFileSystem fs = new POIFSFileSystem(new File("excel_with_embedded.xls")); + HSSFWorkbook workbook = new HSSFWorkbook(fs); + for (HSSFObjectData obj : workbook.getAllEmbeddedObjects()) { + //the OLE2 Class Name of the object + String oleName = obj.getOLE2ClassName(); + if (oleName.equals("Worksheet")) { + DirectoryNode dn = (DirectoryNode) obj.getDirectory(); + HSSFWorkbook embeddedWorkbook = new HSSFWorkbook(dn, false); + //System.out.println(entry.getName() + ": " + embeddedWorkbook.getNumberOfSheets()); + } else if (oleName.equals("Document")) { + DirectoryNode dn = (DirectoryNode) obj.getDirectory(); + HWPFDocument embeddedWordDocument = new HWPFDocument(dn); + //System.out.println(entry.getName() + ": " + embeddedWordDocument.getRange().text()); + } else if (oleName.equals("Presentation")) { + DirectoryNode dn = (DirectoryNode) obj.getDirectory(); + SlideShow<?,?> embeddedPowerPointDocument = new HSLFSlideShow(dn); + //System.out.println(entry.getName() + ": " + embeddedPowerPointDocument.getSlides().length); + } else { + if(obj.hasDirectoryEntry()){ + // The DirectoryEntry is a DocumentNode. Examine its entries to find out what it is + DirectoryNode dn = (DirectoryNode) obj.getDirectory(); + for (Entry entry : dn) { + //System.out.println(oleName + "." + entry.getName()); + } + } else { + // There is no DirectoryEntry + // Recover the object's data from the HSSFObjectData instance. + byte[] objectData = obj.getObjectData(); + } + } + } + </source> + <p><strong>XSSF:</strong></p> + <source> + XSSFWorkbook workbook = new XSSFWorkbook("excel_with_embeded.xlsx"); + for (PackagePart pPart : workbook.getAllEmbeddedParts()) { + String contentType = pPart.getContentType(); + // Excel Workbook - either binary or OpenXML + if (contentType.equals("application/vnd.ms-excel")) { + HSSFWorkbook embeddedWorkbook = new HSSFWorkbook(pPart.getInputStream()); + } + // Excel Workbook - OpenXML file format + else if (contentType.equals("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")) { + OPCPackage docPackage = OPCPackage.open(pPart.getInputStream()); + XSSFWorkbook embeddedWorkbook = new XSSFWorkbook(docPackage); + } + // Word Document - binary (OLE2CDF) file format + else if (contentType.equals("application/msword")) { + HWPFDocument document = new HWPFDocument(pPart.getInputStream()); + } + // Word Document - OpenXML file format + else if (contentType.equals("application/vnd.openxmlformats-officedocument.wordprocessingml.document")) { + OPCPackage docPackage = OPCPackage.open(pPart.getInputStream()); + XWPFDocument document = new XWPFDocument(docPackage); + } + // PowerPoint Document - binary file format + else if (contentType.equals("application/vnd.ms-powerpoint")) { + HSLFSlideShow slideShow = new HSLFSlideShow(pPart.getInputStream()); + } + // PowerPoint Document - OpenXML file format + else if (contentType.equals("application/vnd.openxmlformats-officedocument.presentationml.presentation")) { + OPCPackage docPackage = OPCPackage.open(pPart.getInputStream()); + XSLFSlideShow slideShow = new XSLFSlideShow(docPackage); + } + // Any other type of embedded object. + else { + System.out.println("Unknown Embedded Document: " + contentType); + InputStream inputStream = pPart.getInputStream(); + } + } + </source> + </section> + <anchor id="Autofilter"/> + <p>(Since POI-3.7)</p> + <section><title>Autofilters</title> + <source> + Workbook wb = new HSSFWorkbook(); //or new XSSFWorkbook(); + Sheet sheet = wb.createSheet(); + sheet.setAutoFilter(CellRangeAddress.valueOf("C5:F200")); + </source> + </section> + <anchor id="ConditionalFormatting"/> + <section><title>Conditional Formatting</title> + <source> + Workbook workbook = new HSSFWorkbook(); // or new XSSFWorkbook(); + Sheet sheet = workbook.createSheet(); + + SheetConditionalFormatting sheetCF = sheet.getSheetConditionalFormatting(); + + ConditionalFormattingRule rule1 = sheetCF.createConditionalFormattingRule(ComparisonOperator.EQUAL, "0"); + FontFormatting fontFmt = rule1.createFontFormatting(); + fontFmt.setFontStyle(true, false); + fontFmt.setFontColorIndex(IndexedColors.DARK_RED.index); + + BorderFormatting bordFmt = rule1.createBorderFormatting(); + bordFmt.setBorderBottom(BorderStyle.THIN); + bordFmt.setBorderTop(BorderStyle.THICK); + bordFmt.setBorderLeft(BorderStyle.DASHED); + bordFmt.setBorderRight(BorderStyle.DOTTED); + + PatternFormatting patternFmt = rule1.createPatternFormatting(); + patternFmt.setFillBackgroundColor(IndexedColors.YELLOW.index); + + ConditionalFormattingRule rule2 = sheetCF.createConditionalFormattingRule(ComparisonOperator.BETWEEN, "-10", "10"); + ConditionalFormattingRule [] cfRules = + { + rule1, rule2 + }; + + CellRangeAddress[] regions = { + CellRangeAddress.valueOf("A3:A5") + }; + + sheetCF.addConditionalFormatting(regions, cfRules); + </source> + <p> See more examples on Excel conditional formatting in + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/ConditionalFormats.java">ConditionalFormats.java</a> + </p> + + </section> + <anchor id="Hiding"/> + <section><title>Hiding and Un-Hiding Rows</title> + <p> + Using Excel, it is possible to hide a row on a worksheet by selecting that row (or rows), + right clicking once on the right hand mouse button and selecting 'Hide' from the pop-up menu that appears. + </p> + <p> + To emulate this using POI, simply call the setZeroHeight() method on an instance of either + XSSFRow or HSSFRow (the method is defined on the ss.usermodel.Row interface that both classes implement), like this: + </p> + <source> + Workbook workbook = new XSSFWorkbook(); // OR new HSSFWorkbook() + Sheet sheet = workbook.createSheet(0); + Row row = workbook.createRow(0); + row.setZeroHeight(); + </source> + <p> + If the file were saved away to disc now, then the first row on the first sheet would not be visible. + </p> + <p> + Using Excel, it is possible to unhide previously hidden rows by selecting the row above and the row below + the one that is hidden and then pressing and holding down the Ctrl key, the Shift and the pressing + the number 9 before releasing them all. + </p> + <p> + To emulate this behaviour using POI do something like this: + </p> + <source> + Workbook workbook = WorkbookFactory.create(new File(.......)); + Sheet = workbook.getSheetAt(0); + Iterator<Row> row Iter = sheet.iterator(); + while(rowIter.hasNext()) { + Row row = rowIter.next(); + if(row.getZeroHeight()) { + row.setZeroHeight(false); + } + } + </source> + <p> + If the file were saved away to disc now, any previously hidden rows on the first sheet of the workbook would now be visible. + </p> + <p> + The example illustrates two features. Firstly, that it is possible to unhide a row simply by calling the setZeroHeight() + method and passing the boolean value 'false'. Secondly, it illustrates how to test whether a row is hidden or not. + Simply call the getZeroHeight() method and it will return 'true' if the row is hidden, 'false' otherwise. + </p> + </section> + <anchor id="CellProperties"/> + <section><title>Setting Cell Properties</title> + <p> + Sometimes it is easier or more efficient to create a spreadsheet with basic styles and then apply special styles to certain cells + such as drawing borders around a range of cells or setting fills for a region. CellUtil.setCellProperties lets you do that without creating + a bunch of unnecessary intermediate styles in your spreadsheet. + </p> + <p> + Properties are created as a Map and applied to a cell in the following manner. + </p> + <source> + Workbook workbook = new XSSFWorkbook(); // OR new HSSFWorkbook() + Sheet sheet = workbook.createSheet("Sheet1"); + Map<String, Object> properties = new HashMap<String, Object>(); + + // border around a cell + properties.put(CellUtil.BORDER_TOP, BorderStyle.MEDIUM); + properties.put(CellUtil.BORDER_BOTTOM, BorderStyle.MEDIUM); + properties.put(CellUtil.BORDER_LEFT, BorderStyle.MEDIUM); + properties.put(CellUtil.BORDER_RIGHT, BorderStyle.MEDIUM); + + // Give it a color (RED) + properties.put(CellUtil.TOP_BORDER_COLOR, IndexedColors.RED.getIndex()); + properties.put(CellUtil.BOTTOM_BORDER_COLOR, IndexedColors.RED.getIndex()); + properties.put(CellUtil.LEFT_BORDER_COLOR, IndexedColors.RED.getIndex()); + properties.put(CellUtil.RIGHT_BORDER_COLOR, IndexedColors.RED.getIndex()); + + // Apply the borders to the cell at B2 + Row row = sheet.createRow(1); + Cell cell = row.createCell(1); + CellUtil.setCellStyleProperties(cell, properties); + + // Apply the borders to a 3x3 region starting at D4 + for (int ix=3; ix <= 5; ix++) { + row = sheet.createRow(ix); + for (int iy = 3; iy <= 5; iy++) { + cell = row.createCell(iy); + CellUtil.setCellStyleProperties(cell, properties); + } + } + </source> + + <p> + NOTE: This does not replace the properties of the cell, it merges the properties you have put into the Map with the + cell's existing style properties. If a property already exists, it is replaced with the new property. If a property does not + exist, it is added. This method will not remove CellStyle properties. + </p> + </section> + <anchor id="DrawingBorders"/> + <section> + <title>Drawing Borders</title> + <p> + In Excel, you can apply a set of borders on an entire workbook region at the press of a button. The PropertyTemplate + object simulates this with methods and constants defined to allow drawing top, bottom, left, right, horizontal, + vertical, inside, outside, or all borders around a range of cells. Additional methods allow for applying colors + to the borders. + </p> + <p> + It works like this: you create a PropertyTemplate object which is a container for the borders you wish to apply to a + sheet. Then you add borders and colors to the PropertyTemplate, and finally apply it to whichever sheets you need + that set of borders on. You can create multiple PropertyTemplate objects and apply them to a single sheet, or you can + apply the same PropertyTemplate object to multiple sheets. It is just like a preprinted form. + </p> + <p> + Enums: + </p> + <dl> + <dt>BorderStyle</dt> + <dd> + Defines the look of the border, is it thick or thin, solid or dashed, single or double. + This enum replaces the CellStyle.BORDER_XXXXX constants which have been deprecated. The PropertyTemplate will not + support the older style BORDER_XXXXX constants. A special value of BorderStyle.NONE will remove the border from + a Cell once it is applied. + </dd> + <dt>BorderExtent</dt> + <dd> + Describes the portion of the region that the BorderStyle will apply to. For example, TOP, BOTTOM, INSIDE, or OUTSIDE. + A special value of BorderExtent.NONE will remove the border from the PropertyTemplate. When the template is applied, + no change will be made to a cell border where no border properties exist in the PropertyTemplate. + </dd> + </dl> + <source> + // draw borders (three 3x3 grids) + PropertyTemplate pt = new PropertyTemplate(); + // #1) these borders will all be medium in default color + pt.drawBorders(new CellRangeAddress(1, 3, 1, 3), + BorderStyle.MEDIUM, BorderExtent.ALL); + // #2) these cells will have medium outside borders and thin inside borders + pt.drawBorders(new CellRangeAddress(5, 7, 1, 3), + BorderStyle.MEDIUM, BorderExtent.OUTSIDE); + pt.drawBorders(new CellRangeAddress(5, 7, 1, 3), BorderStyle.THIN, + BorderExtent.INSIDE); + // #3) these cells will all be medium weight with different colors for the + // outside, inside horizontal, and inside vertical borders. The center + // cell will have no borders. + pt.drawBorders(new CellRangeAddress(9, 11, 1, 3), + BorderStyle.MEDIUM, IndexedColors.RED.getIndex(), + BorderExtent.OUTSIDE); + pt.drawBorders(new CellRangeAddress(9, 11, 1, 3), + BorderStyle.MEDIUM, IndexedColors.BLUE.getIndex(), + BorderExtent.INSIDE_VERTICAL); + pt.drawBorders(new CellRangeAddress(9, 11, 1, 3), + BorderStyle.MEDIUM, IndexedColors.GREEN.getIndex(), + BorderExtent.INSIDE_HORIZONTAL); + pt.drawBorders(new CellRangeAddress(10, 10, 2, 2), + BorderStyle.NONE, + BorderExtent.ALL); + + // apply borders to sheet + Workbook wb = new XSSFWorkbook(); + Sheet sh = wb.createSheet("Sheet1"); + pt.applyBorders(sh); + </source> + <p> + NOTE: The last pt.drawBorders() call removes the borders from the range by using BorderStyle.NONE. Like + setCellStyleProperties, the applyBorders method merges the properties of a cell style, so existing borders + are changed only if they are replaced by something else, or removed only if they are replaced by + BorderStyle.NONE. To remove a color from a border, use IndexedColor.AUTOMATIC.getIndex(). + </p> + <p>Additionally, to remove a border or color from the PropertyTemplate object, use BorderExtent.NONE.</p> + <p> + This does not work with diagonal borders yet. + </p> + </section> + <anchor id="PivotTable"/> + <section><title>Creating a Pivot Table</title> + <p> + Pivot Tables are a powerful feature of spreadsheet files. You can create a pivot table with the following piece of code. + </p> + <source> + XSSFWorkbook wb = new XSSFWorkbook(); + XSSFSheet sheet = wb.createSheet(); + + //Create some data to build the pivot table on + setCellData(sheet); + + XSSFPivotTable pivotTable = sheet.createPivotTable(new AreaReference("A1:D4"), new CellReference("H5")); + //Configure the pivot table + //Use first column as row label + pivotTable.addRowLabel(0); + //Sum up the second column + pivotTable.addColumnLabel(DataConsolidateFunction.SUM, 1); + //Set the third column as filter + pivotTable.addColumnLabel(DataConsolidateFunction.AVERAGE, 2); + //Add filter on forth column + pivotTable.addReportFilter(3); + </source> + </section> + <anchor id="RichText"/> + <section><title>Cells with multiple styles (Rich Text Strings)</title> + <p> + To apply a single set of text formatting (colour, style, font etc) + to a cell, you should create a + <a href="/../apidocs/dev/org/apache/poi/ss/usermodel/CellStyle.html">CellStyle</a> + for the workbook, then apply to the cells. + </p> + <source> + // HSSF Example + HSSFCell hssfCell = row.createCell(idx); + //rich text consists of two runs + HSSFRichTextString richString = new HSSFRichTextString( "Hello, World!" ); + richString.applyFont( 0, 6, font1 ); + richString.applyFont( 6, 13, font2 ); + hssfCell.setCellValue( richString ); + + + // XSSF Example + XSSFCell cell = row.createCell(1); + XSSFRichTextString rt = new XSSFRichTextString("The quick brown fox"); + + XSSFFont font1 = wb.createFont(); + font1.setBold(true); + font1.setColor(new XSSFColor(new java.awt.Color(255, 0, 0))); + rt.applyFont(0, 10, font1); + + XSSFFont font2 = wb.createFont(); + font2.setItalic(true); + font2.setUnderline(XSSFFont.U_DOUBLE); + font2.setColor(new XSSFColor(new java.awt.Color(0, 255, 0))); + rt.applyFont(10, 19, font2); + + XSSFFont font3 = wb.createFont(); + font3.setColor(new XSSFColor(new java.awt.Color(0, 0, 255))); + rt.append(" Jumped over the lazy dog", font3); + + cell.setCellValue(rt); + </source> + <p> + To apply different formatting to different parts of a cell, you + need to use + <a href="../../apidocs/dev/org/apache/poi/ss/usermodel/RichTextString.html">RichTextString</a>, + which permits styling of parts of the text within the cell. + </p> + <p> + There are some slight differences between HSSF and XSSF, especially + around font colours (the two formats store colours quite differently + internally), refer to the + <a href="../../apidocs/dev/org/apache/poi/hssf/usermodel/HSSFRichTextString.html">HSSF Rich Text String</a> + and + <a href="../../apidocs/dev/org/apache/poi/xssf/usermodel/XSSFRichTextString.html">XSSF Rich Text String</a> + javadocs for more details. + </p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/record-generator.xml b/src/documentation/content/xdocs/components/spreadsheet/record-generator.xml new file mode 100644 index 0000000000..39f328bc78 --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/record-generator.xml @@ -0,0 +1,212 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Record Generator HOWTO</title> + <authors> + <person email="user@poi.apache.org" name="Glen Stampoultzis" id="glens"/> + <person email="acoliver@apache.org" name="Andrew C. Oliver" id="acoliver"/> + </authors> + </header> + <body> + <section><title>How to Use the Record Generator</title> + + <section><title>History</title> + <p> + The record generator was born from frustration with translating + the Excel records to Java classes. Doing this manually is a time + consuming process. It's also very easy to make mistakes. + </p> + <p> + A utility was needed to take the definition of what a + record looked like and do all the boring and repetitive work. + </p> + </section> + + <section><title>Capabilities</title> + <p> + The record generator takes XML as input and produces the following + output: + </p> + <ul> + <li>A Java file capable of decoding and encoding the record.</li> + <li>A test class that provides a fill-in-the-blanks implementation + of a test case for ensuring the record operates as + designed.</li> + </ul> + </section> + <section><title>Usage</title> + <p> + The record generator is invoked as an Ant target + (generate-records). It goes through looking for all files in + <code>src/records/definitions</code> ending with _record.xml. + It then creates two files; the Java record definition and the + Java test case template. + </p> + <p> + The records themselves have the following general layout: + </p> + <source><![CDATA[ +<record id="0x1032" name="Frame" package="org.apache.poi.hssf.record" + excel-record-id="FRAME"> + <description>The frame record indicates whether there is a border + around the displayed text of a chart.</description> + <author>Glen Stampoultzis (glens at apache.org)</author> + <fields> + <field type="int" size="2" name="border type"> + <const name="regular" value="0" description="regular rectangle or no border"/> + <const name="shadow" value="1" description="rectangle with shadow"/> + </field> + <field type="int" size="2" name="options"> + <bit number="0" name="auto size" + description="excel calculates the size automatically if true"/> + <bit number="1" name="auto position" + description="excel calculates the position automatically"/> + </field> + </fields> +</record> + ]]></source> + <p> + The following table details the allowable types and sizes for + the fields. + </p> + <table> + <tr> + <th>Type</th> + <th>Size</th> + <th>Java Type</th> + </tr> + <tr> + <td>int</td> + <td>1</td> + <td>byte</td> + </tr> + <tr> + <td>int</td> + <td>2</td> + <td>short</td> + </tr> + <tr> + <td>int</td> + <td>4</td> + <td>int</td> + </tr> + <tr> + <td>int</td> + <td>8</td> + <td>long</td> + </tr> + <tr> + <td>int</td> + <td>varword</td> + <td>array of shorts</td> + </tr> + <tr> + <td>bits</td> + <td>1</td> + <td>A byte comprising of a bits (defined by the bit element) + </td> + </tr> + <tr> + <td>bits</td> + <td>2</td> + <td>An short comprising of a bits</td> + </tr> + <tr> + <td>bits</td> + <td>4</td> + <td>A int comprising of a bits</td> + </tr> + <tr> + <td>float</td> + <td>8</td> + <td>double</td> + </tr> + <tr> + <td>hbstring</td> + <td>java expression</td> + <td>String</td> + </tr> + </table> + <p> + The Java records are regenerated each time the record generator is + run, however the test stubs are only created if the test stub does + not already exist. What this means is that you may change test + stubs but not the generated records. + </p> + </section> + <section><title>Custom Field Types</title> + <p> + Occasionally the builtin types are not enough. More control + over the encoding and decoding of the streams is required. This + can be achieved using a custom type. + </p> + <p> + A custom type lets you escape to java to define the way in which + the field encodes and decodes. To code a custom type you + declare your field like this: + </p> + <source><![CDATA[ + <field type="custom:org.apache.poi.hssf.record.LinkedDataFormulaField" + size="var" name="formula of link" description="formula"/> + ]]></source> + <p> + Where the class name specified after <code>custom:</code> is a + class implementing the interface <code>CustomField</code>. + </p> + <p> + You can then implement the encoding yourself. + </p> + </section> + <section><title>How it Works</title> + <p> + The record generation works by taking an XML file and styling it + using XSLT. Given that XSLT is a little limited in some ways it was + necessary to add a little Java code to the mix. + </p> + <p> + See record.xsl, record_test.xsl, FieldIterator.java, + RecordUtil.java, RecordGenerator.java + </p> + <p> + There is a corresponding "type" generator for HWPF. + See the HWPF documentation for details. + </p> + </section> + <section><title>Limitations</title> + <p> + The record generator does not handle all possible record types and + goes not intend to perform this function. When dealing with a + non-standard record sometimes the cost-benefit of coding the + record by hand will be greater than attempting modify the + generator. The main point of the record generator is to save + time, so keep that in mind. + </p> + <p> + Currently the XSL file that generates the record calls out to + Java objects. The Java code for the record generation is + currently quite messy with minimal comments. + </p> + </section> +</section> +</body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/use-case.xml b/src/documentation/content/xdocs/components/spreadsheet/use-case.xml new file mode 100644 index 0000000000..6c8ed246e7 --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/use-case.xml @@ -0,0 +1,200 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>HSSF Use Cases</title> + <authors> + <person email="marc.johnson@yahoo.com" name="Marc Johnson" id="MJ"/> + </authors> + </header> + <body> + <section><title>HSSF Use Cases</title> + <section><title>Use Case 1: Read existing HSSF</title> + +<p><strong>Primary Actor:</strong> HSSF client</p> +<p><strong>Scope:</strong> HSSF</p> +<p><strong>Level:</strong> Summary</p> +<p><strong>Stakeholders and Interests:</strong></p> +<ul> + <li>HSSF client- wants to read content + of HSSF file</li> + <li>HSSF - understands HSSF file</li> + <li>POIFS - understands underlying POI + file system</li> +</ul> +<p><strong>Precondition:</strong> None</p> +<p><strong>Minimal Guarantee:</strong> None</p> +<p><strong>Main Success Guarantee:</strong></p> +<ol> + <li>HSSF client requests HSSF to read + a HSSF file, providing an InputStream + containing HSSF file in question.</li> + <li>HSSF requests POIFS to read the HSSF + file, passing the InputStream + object to POIFS (POIFS use case 1, read existing file system)</li> + <li>HSSF reads the "Workbook" + file (use case 4, read workbook entry)</li> +</ol> +<p><strong>Extensions:</strong></p> +<p>2a. Exceptions +thrown by POIFS will be passed on to the HSSF client.</p> +</section> + <section><title>Use Case 2: Write HSSF file</title> + +<p><strong>Primary Actor:</strong> HSSF client</p> +<p><strong>Scope:</strong> HSSF</p> +<p><strong>Level:</strong> Summary</p> +<p><strong>Stakeholders and Interests:</strong></p> +<ul> + <li>HSSF client- wants to write file + out.</li> + <li>HSSF - knows how to write file + out.</li> + <li>POIFS - knows how to write file + system out.</li> +</ul> +<p><strong>Precondition:</strong></p> +<ul> + <li>File has been + read (use case 1, read existing HSSF file) and subsequently modified + or file has been created (use case 3, create HSSF file)</li> +</ul> +<p><strong>Minimal Guarantee:</strong> None</p> +<p><strong>Main Success Guarantee:</strong></p> +<ol> + <li>HSSF client + provides an OutputStream to + write the file to.</li> + <li>HSSF writes + the "Workbook" to its associated POIFS file system (use case + 5, write workbook entry)</li> + <li>HSSF + requests POIFS to write its file system out, using the OutputStream + obtained from the HSSF client (POIFS use case 2, write file system).</li> +</ol> +<p><strong>Extensions:</strong></p> +<p>3a. Exceptions +from POIFS are passed to the HSSF client.</p> + +</section> + <section><title>Use Case 3:Create HSSF file</title> + +<p><strong>Primary Actor:</strong> HSSF client</p> +<p><strong>Scope:</strong> HSSF</p> +<p> +<strong>Level:</strong> Summary</p> +<p><strong>Stakeholders and Interests:</strong></p> +<ul> + <li>HSSF client- wants to create a new + file.</li> + <li>HSSF - knows how to create a new + file.</li> + <li>POIFS - knows how to create a new + file system.</li> +</ul> +<p><strong>Precondition:</strong></p> +<p><strong>Minimal Guarantee:</strong> None</p> +<p><strong>Main Success Guarantee:</strong></p> +<ol> + <li>HSSF requests + POIFS to create a new file system (POIFS use case 3, create new file + system)</li> +</ol> +<p><strong>Extensions:</strong> +None</p> + +</section> + <section><title>Use Case 4: Read workbook entry</title> +<p><strong>Primary Actor:</strong> HSSF</p> +<p><strong>Scope:</strong> HSSF</p> +<p> +<strong>Level:</strong> Summary</p> +<p><strong>Stakeholders and Interests:</strong></p> +<ul> + <li>HSSF - knows how to read the + workbook entry</li> + <li>POIFS - knows how to manage the file + system.</li> +</ul> +<p><strong>Precondition:</strong></p> +<ul> + <li>The file + system has been read (use case 1, read existing HSSF file) or has + been created and written to (use case 3, create HSSF file system; + use case 5, write workbook entry).</li> +</ul> +<p><strong>Minimal +Guarantee:</strong> None</p> +<p><strong>Main Success Guarantee:</strong></p> +<ol> + <li> + HSSF requests POIFS for the "Workbook" file</li> + <li>POIFS returns + an InputStream for the file.</li> + <li>HSSF reads + from the InputStream provided by POIFS</li> + <li>HSSF closes + the InputStream provided by POIFS</li> +</ol> +<p><strong>Extensions:</strong></p> +<p>3a. Exceptions +thrown by POIFS will be passed on</p> +</section> + <section><title>Use Case 5: Write workbook entry</title> + + +<p><strong>Primary Actor:</strong> HSSF</p> +<p><strong>Scope:</strong> HSSF</p> +<p> +<strong>Level:</strong> Summary</p> +<p><strong>Stakeholders and Interests:</strong></p> +<ul> + <li>HSSF - knows how to manage the + write the workbook entry.</li> + <li>POIFS - knows how to manage the file + system.</li> +</ul> +<p><strong>Precondition:</strong> +</p> +<ul> + <li>Either an existing HSSF file has + been read (use case 1, read existing HSSF file) or an HSSF file has + been created (use case 3, create HSSF file).</li> +</ul> +<p><strong>Minimal Guarantee:</strong> None</p> +<p><strong>Main Success Guarantee:</strong></p> +<ol> + <li>HSSF + checks the POIFS file system directory for the "Workbook" + file (POIFS use case 8, read file system directory)</li> + <li>If "Workbook" is in the directory, HSSF requests POIFS to + replace it with the new workbook entry (POIFS use case 4, replace file + in file system). Otherwise, HSSF requests POIFS to write the new + workbook file, with the name "Workbook" (POIFS use case 6, + write new file to file system)</li> +</ol> +<p><strong>Extensions:</strong>None</p> +</section> + +</section> +</body> +</document> diff --git a/src/documentation/content/xdocs/components/spreadsheet/user-defined-functions.xml b/src/documentation/content/xdocs/components/spreadsheet/user-defined-functions.xml new file mode 100644 index 0000000000..1d5819b88b --- /dev/null +++ b/src/documentation/content/xdocs/components/spreadsheet/user-defined-functions.xml @@ -0,0 +1,414 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>User Defined Functions</title> + <authors> + <person email="jon@loquatic.com" name="Jon Svede" id="JDS"/> + <person email="brian.bush@nrel.gov" name="Brian Bush" id="BWB"/> + </authors> + </header> + <body> + <section><title>How to Create and Use User Defined Functions</title> + + <section><title>Description</title> + <p>This document describes the User Defined Functions within POI. + User defined functions allow you to take code that is written in VBA + and re-write in Java and use within POI. Consider the following example.</p> + </section> + <section><title>An Example</title> + <p>Suppose you are given a spreadsheet that can calculate the principal and interest + payments for a mortgage. The user enters the principal loan amount, the interest rate + and the term of the loan. The Excel spreadsheet does the rest.</p> + <p> + <img src="images/simple-xls-with-function.jpg" alt="mortgage calculation spreadsheet"/> + </p> + <p>When you actually look at the workbook you discover that rather than having + the formula in a cell it has been written as VBA function. You review the + function and determine that it could be written in Java:</p> + <p> + <img src="images/calculatePayment.jpg" alt="VBA code"/> + </p> + <p>If we write a small program to try to evaluate this cell, we'll fail. Consider this source code:</p> + <source><![CDATA[ +import java.io.File ; +import java.io.FileInputStream ; +import java.io.FileNotFoundException ; +import java.io.IOException ; + +import org.apache.poi.openxml4j.exceptions.InvalidFormatException ; +import org.apache.poi.ss.formula.functions.FreeRefFunction ; +import org.apache.poi.ss.formula.udf.AggregatingUDFFinder ; +import org.apache.poi.ss.formula.udf.DefaultUDFFinder ; +import org.apache.poi.ss.formula.udf.UDFFinder ; +import org.apache.poi.ss.usermodel.Cell ; +import org.apache.poi.ss.usermodel.CellValue ; +import org.apache.poi.ss.usermodel.Row ; +import org.apache.poi.ss.usermodel.Sheet ; +import org.apache.poi.ss.usermodel.Workbook ; +import org.apache.poi.ss.usermodel.WorkbookFactory ; +import org.apache.poi.ss.util.CellReference ; + +public class Evaluator { + + + + public static void main( String[] args ) { + + System.out.println( "fileName: " + args[0] ) ; + System.out.println( "cell: " + args[1] ) ; + + File workbookFile = new File( args[0] ) ; + + try { + FileInputStream fis = new FileInputStream(workbookFile); + Workbook workbook = WorkbookFactory.create(fis); + + FormulaEvaluator evaluator = workbook.getCreationHelper().createFormulaEvaluator(); + + CellReference cr = new CellReference( args[1] ) ; + String sheetName = cr.getSheetName() ; + Sheet sheet = workbook.getSheet( sheetName ) ; + int rowIdx = cr.getRow() ; + int colIdx = cr.getCol() ; + Row row = sheet.getRow( rowIdx ) ; + Cell cell = row.getCell( colIdx ) ; + + CellValue value = evaluator.evaluate( cell ) ; + + System.out.println("returns value: " + value ) ; + + + } catch( FileNotFoundException e ) { + e.printStackTrace(); + } catch( InvalidFormatException e ) { + e.printStackTrace(); + } catch( IOException e ) { + e.printStackTrace(); + } + } +} + +]]></source> + <p>If you run this code, you're likely to get the following error:</p> + + <source><![CDATA[ +Exception in thread "main" org.apache.poi.ss.formula.eval.NotImplementedException: Error evaluating cell Sheet1!B4 + at org.apache.poi.ss.formula.WorkbookEvaluator.addExceptionInfo(WorkbookEvaluator.java:321) + at org.apache.poi.ss.formula.WorkbookEvaluator.evaluateAny(WorkbookEvaluator.java:288) + at org.apache.poi.ss.formula.WorkbookEvaluator.evaluate(WorkbookEvaluator.java:221) + at org.apache.poi.hssf.usermodel.HSSFFormulaEvaluator.evaluateFormulaCellValue(HSSFFormulaEvaluator.java:320) + at org.apache.poi.hssf.usermodel.HSSFFormulaEvaluator.evaluate(HSSFFormulaEvaluator.java:182) + at poi.tests.Evaluator.main(Evaluator.java:61) +Caused by: org.apache.poi.ss.formula.eval.NotImplementedException: calculatePayment + at org.apache.poi.ss.formula.UserDefinedFunction.evaluate(UserDefinedFunction.java:59) + at org.apache.poi.ss.formula.OperationEvaluatorFactory.evaluate(OperationEvaluatorFactory.java:129) + at org.apache.poi.ss.formula.WorkbookEvaluator.evaluateFormula(WorkbookEvaluator.java:456) + at org.apache.poi.ss.formula.WorkbookEvaluator.evaluateAny(WorkbookEvaluator.java:279) + ... 4 more + +]]></source> + + <p>How would we make it so POI can use this sheet?</p> + </section> + + <section><title>Defining Your Function</title> + <p>To 'convert' this code to Java and make it available to POI you need to implement + a FreeRefFunction instance. FreeRefFunction is an interface in the org.apache.poi.ss.formula.functions + package. This interface defines one method, evaluate(ValueEval[] args, OperationEvaluationContext ec), + which is how you will receive the argument values from POI.</p> + <p>The evaluate() method as defined above is where you will convert the ValueEval instances to the + proper number types. The following code snippet shows you how to get your values:</p> + + <source><![CDATA[ +public class CalculateMortgage implements FreeRefFunction { + +@Override +public ValueEval evaluate( ValueEval[] args, OperationEvaluationContext ec ) { + if (args.length != 3) { + return ErrorEval.VALUE_INVALID; + } + + double principal, rate, years, result; + try { + ValueEval v1 = OperandResolver.getSingleValue( args[0], + ec.getRowIndex(), + ec.getColumnIndex() ) ; + ValueEval v2 = OperandResolver.getSingleValue( args[1], + ec.getRowIndex(), + ec.getColumnIndex() ) ; + ValueEval v3 = OperandResolver.getSingleValue( args[2], + ec.getRowIndex(), + ec.getColumnIndex() ) ; + + principal = OperandResolver.coerceValueToDouble( v1 ) ; + rate = OperandResolver.coerceValueToDouble( v2 ) ; + years = OperandResolver.coerceValueToDouble( v3 ) ; + ]]></source> + + <p>The first thing we do is check the number of arguments being passed since there is no sense + in attempting to go further if you are missing critical information.</p> + <p>Next we declare our variables, in our case we need variables for:</p> + <ul> + <li>principal - the amount of the loan</li> + <li>rate - the interest rate as a decimal</li> + <li>years - the length of the loan in years</li> + <li>result - the result of the calculation</li> + </ul> + <p>Next, we use the OperandResolver to convert the ValueEval instances to doubles, though not directly. + First we start by getting discreet values. Using the OperandResolver.getSingleValue() method + we retrieve each of the values passed in by the cell in the spreadsheet. Next, we use the + OperandResolver again to convert the ValueEval instances to doubles, in this case. This + class has other methods of coercion for getting Strings, ints and booleans. Now that we've + got our primitive values we can move on to calculating the value.</p> + <p>As shown previously, we have the VBA source. We need to add code to our class to calculate + the payment. To do this you could simply add it to the method we've already created but I've + chosen to add it as its own method. Add the following method: </p> + <source><![CDATA[ +public double calculateMortgagePayment( double p, double r, double y ) { + + double i = r / 12 ; + double n = y * 12 ; + + double principalAndInterest = + p * (( i * Math.pow((1 + i),n ) ) / ( Math.pow((1 + i),n) - 1)) ; + + return principalAndInterest ; +} + ]]></source> + <p>The biggest change necessary is related to the exponents; Java doesn't have a notation for this + so we had to add calls to Math.pow(). Now we need to add this call to our previous method:</p> + <source><![CDATA[ + result = calculateMortgagePayment( principal, rate, years ) ; + ]]></source> + <p>Having done that, the last things we need to do are to check to make sure we didn't get a bad result and, + if not, we need to return the value. Add the following code to the class:</p> + <source><![CDATA[ +private void checkValue(double result) throws EvaluationException { + if (Double.isNaN(result) || Double.isInfinite(result)) { + throw new EvaluationException(ErrorEval.NUM_ERROR); + } +} + ]]></source> + <p>Then add a line of code to our evaluate method to call this new static method, complete our try/catch and return the value:</p> + <source><![CDATA[ + checkValue(result); + + } catch (EvaluationException e) { + e.printStackTrace() ; + return e.getErrorEval(); + } + + return new NumberEval( result ) ; + ]]></source> + + <p>So the whole class would be as follows:</p> + + <source><![CDATA[ +import org.apache.poi.ss.formula.OperationEvaluationContext ; +import org.apache.poi.ss.formula.eval.ErrorEval ; +import org.apache.poi.ss.formula.eval.EvaluationException ; +import org.apache.poi.ss.formula.eval.NumberEval ; +import org.apache.poi.ss.formula.eval.OperandResolver ; +import org.apache.poi.ss.formula.eval.ValueEval ; +import org.apache.poi.ss.formula.functions.FreeRefFunction ; + +/** + * A simple function to calculate principal and interest. + * + * @author Jon Svede + * + */ +public class CalculateMortgage implements FreeRefFunction { + + @Override + public ValueEval evaluate( ValueEval[] args, OperationEvaluationContext ec ) { + if (args.length != 3) { + return ErrorEval.VALUE_INVALID; + } + + double principal, rate, years, result; + try { + ValueEval v1 = OperandResolver.getSingleValue( args[0], + ec.getRowIndex(), + ec.getColumnIndex() ) ; + ValueEval v2 = OperandResolver.getSingleValue( args[1], + ec.getRowIndex(), + ec.getColumnIndex() ) ; + ValueEval v3 = OperandResolver.getSingleValue( args[2], + ec.getRowIndex(), + ec.getColumnIndex() ) ; + + principal = OperandResolver.coerceValueToDouble( v1 ) ; + rate = OperandResolver.coerceValueToDouble( v2 ) ; + years = OperandResolver.coerceValueToDouble( v3 ) ; + + result = calculateMortgagePayment( principal, rate, years ) ; + + checkValue(result); + + } catch (EvaluationException e) { + e.printStackTrace() ; + return e.getErrorEval(); + } + + return new NumberEval( result ) ; + } + + public double calculateMortgagePayment( double p, double r, double y ) { + double i = r / 12 ; + double n = y * 12 ; + + //M = P [ i(1 + i)n ] / [ (1 + i)n - 1] + double principalAndInterest = + p * (( i * Math.pow((1 + i),n ) ) / ( Math.pow((1 + i),n) - 1)) ; + + return principalAndInterest ; + } + + /** + * Excel does not support infinities and NaNs, rather, it gives a #NUM! error in these cases + * + * @throws EvaluationException (#NUM!) if <tt>result</tt> is <tt>NaN</> or <tt>Infinity</tt> + */ + static final void checkValue(double result) throws EvaluationException { + if (Double.isNaN(result) || Double.isInfinite(result)) { + throw new EvaluationException(ErrorEval.NUM_ERROR); + } + } + +} + + ]]></source> + + <p>Great! Now we need to go back to our original program that failed to evaluate our cell and add code that will allow it run our new Java code.</p> + + </section> + + <section><title>Registering Your Function</title> + <p>Now we need to register our function in the Workbook, so that the Formula Evaluator can resolve the name "calculatePayment" +and map it to the actual implementation (CalculateMortgage). This is done using the UDFFinder object. +The UDFFinder manages FreeRefFunctions which are our analogy for the VBA code. We need to create a UDFFinder. There are + a few things we need to know in order to do this:</p> + <ul> + <li>The name of the function in the VBA code (in our case it is calculatePayment)</li> + <li>The Class name of our FreeRefFunction</li> + </ul> + <p>UDFFinder is actually an interface, so we need to use an actual implementation of this interface. Therefore we use the org.apache.poi.ss.formula.udf.DefaultUDFFinder class. If you refer to the Javadocs you'll see that this class expects to get two arrays, one + containing the alias and the other containing an instance of the class that will represent that alias. In our case our alias will be calculatePayment + and our class instance will be of the CalculateMortgage type. This class needs to be available at compile and runtime. Be sure to keep these arrays + well organized because you'll run into problems if these arrays are of different sizes or the alias aren't in the same relative position in their respective + arrays. Add the following code:</p> + <source><![CDATA[ +String[] functionNames = { "calculatePayment" } ; +FreeRefFunction[] functionImpls = { new CalculateMortgage() } ; + +UDFFinder udfs = new DefaultUDFFinder( functionNames, functionImpls ) ; +UDFFinder udfToolpack = new AggregatingUDFFinder( udfs ) ; + ]]></source> + <p>Now we have our UDFFinder instance and we've created the AggregatingUDFFinder instance. The last step is to pass this to our Workbook:</p> + + <source><![CDATA[ +workbook.addToolPack(udfToolpack); + ]]></source> + <p>So now the whole class will look like this:</p> + <source><![CDATA[ +import java.io.File ; +import java.io.FileInputStream ; +import java.io.FileNotFoundException ; +import java.io.IOException ; + +import org.apache.poi.openxml4j.exceptions.InvalidFormatException ; +import org.apache.poi.ss.formula.functions.FreeRefFunction ; +import org.apache.poi.ss.formula.udf.AggregatingUDFFinder ; +import org.apache.poi.ss.formula.udf.DefaultUDFFinder ; +import org.apache.poi.ss.formula.udf.UDFFinder ; +import org.apache.poi.ss.usermodel.Cell ; +import org.apache.poi.ss.usermodel.CellValue ; +import org.apache.poi.ss.usermodel.Row ; +import org.apache.poi.ss.usermodel.Sheet ; +import org.apache.poi.ss.usermodel.Workbook ; +import org.apache.poi.ss.usermodel.WorkbookFactory ; +import org.apache.poi.ss.util.CellReference ; + +public class Evaluator { + + public static void main( String[] args ) { + + System.out.println( "fileName: " + args[0] ) ; + System.out.println( "cell: " + args[1] ) ; + + File workbookFile = new File( args[0] ) ; + + try { + FileInputStream fis = new FileInputStream(workbookFile); + Workbook workbook = WorkbookFactory.create(fis); + + String[] functionNames = { "calculatePayment" } ; + FreeRefFunction[] functionImpls = { new CalculateMortgage() } ; + + UDFFinder udfs = new DefaultUDFFinder( functionNames, functionImpls ) ; + UDFFinder udfToolpack = new AggregatingUDFFinder( udfs ) ; + + workbook.addToolPack(udfToolpack); + + FormulaEvaluator evaluator = workbook.getCreationHelper().createFormulaEvaluator(); + + CellReference cr = new CellReference( args[1] ) ; + String sheetName = cr.getSheetName() ; + Sheet sheet = workbook.getSheet( sheetName ) ; + int rowIdx = cr.getRow() ; + int colIdx = cr.getCol() ; + Row row = sheet.getRow( rowIdx ) ; + Cell cell = row.getCell( colIdx ) ; + + CellValue value = evaluator.evaluate( cell ) ; + + System.out.println("returns value: " + value ) ; + + + } catch( FileNotFoundException e ) { + e.printStackTrace(); + } catch( InvalidFormatException e ) { + e.printStackTrace(); + } catch( IOException e ) { + e.printStackTrace(); + } + } +} + + ]]></source> + <p>Now that our evaluator is aware of the UDFFinder which in turn is aware of our FreeRefFunction, we're ready to re-run our example:</p> + <source>Evaluator mortgage-calculation.xls Sheet1!B4</source> + <p>which prints the following output in the console:</p> + <source><![CDATA[ +fileName: mortgage-calculation.xls +cell: Sheet1!B4 +returns value: org.apache.poi.ss.usermodel.CellValue [790.7936267415464] + ]]></source> + <p>That is it! Now you can create Java code and register it, allowing your POI based appliction to run spreadsheets that previously were inaccessible.</p> + <p>This example can be found in the <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/formula">poi-examples/src/main/java/org/apache/poi/examples/ss/formula</a> folder in the source.</p> + </section> + </section> +</body> +</document> + diff --git a/src/documentation/content/xdocs/devel/git.xml b/src/documentation/content/xdocs/devel/git.xml new file mode 100644 index 0000000000..a17fdc70f7 --- /dev/null +++ b/src/documentation/content/xdocs/devel/git.xml @@ -0,0 +1,90 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - Source Code Repository</title> + <authors> + <person id="NB" name="Nick Burch" email="dev@poi.apache.org"/> + </authors> + </header> + + <body> + <section><title>Download the Source</title> + <p> + Most users of the source code probably don't need to have day to + day access to the source code as it changes. Therefore most users will want + to make use of our <a href="site:download">source release</a> + packages, which contain the complete source tree for each binary + release, suitable for browsing or debugging. These source releases + are available from our + <a href="site:download">download page.</a> + </p> + <p> + The Apache POI source code is also available as source artifacts + in the <a href="https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache.poi%22">Maven Central repository</a>, + which may be helpful for those users who make use of POI via Maven + and wish to inspect the source (eg when debugging in an IDE). + </p> + </section> + <section><title>Access the Version Controlled Source Code</title> + <p>Apache POI uses Git as its version control system. We switched from Subversion to Git + in July 2025. + </p> + + <ul> + <li>For access to the latest Apache POI code, please use + <a href="https://github.com/apache/poi/tree/trunk/">https://github.com/apache/poi/tree/trunk/</a></li> + </ul> + + <p>If you are not a <em>Committer</em>, but you want to submit patches + or even request commit privileges, please see our + <a href="site:guidelines">Contribution Guidelines</a> for more + information.</p> + </section> + <section><title>Git access to POI sources</title> + <p> + The trunk source repository for Apache POI is in gitbox.apache.org. + The GitHub mirror can be used to access the repo too (https://github.com/apache/poi). + You can create PRs and issues using GitHub, if you like. + </p> + </section> + <section><title>Code metrics</title> + <p> + Code quality reports for Apache POI are available on the + <a href="https://sonarcloud.io/dashboard?id=poi-parent">Apache Sonar instance</a>. + </p> + <p> + Sonar provides lots of useful numbers and statistics, especially + watching the project over time shows how some of the indicators evolve + and allows to see which areas need some polishing. + </p> + </section> + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/devel/guidelines.xml b/src/documentation/content/xdocs/devel/guidelines.xml new file mode 100644 index 0000000000..8e379befff --- /dev/null +++ b/src/documentation/content/xdocs/devel/guidelines.xml @@ -0,0 +1,349 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - Contribution Guidelines</title> + <authors> + <person name="Nick Burch" email="dev@poi.apache.org"/> + <person name="David Fisher" email="dev@poi.apache.org"/> + </authors> + </header> + + <body> + + <section><title>Index of Contribution Guidelines</title> + <ul> + <li><a href="#Introduction">Introduction</a></li> + <li><a href="#WhereHelpNeeded">Where is help needed on the project?</a></li> + <li><a href="#GetInvolved">I just want to get involved, but don't know where to start?</a></li> + <li><a href="#SubmittingPatches">Submitting Patches</a></li> + <li><a href="#CodeStyle">Code Style</a></li> + <li><a href="#Mentoring">Mentoring and Committership</a></li> + <li><a href="#FileFormatInformation">File Format Information</a></li> + </ul> + </section> + + <anchor id="Introduction"/> + <section><title>Introduction</title> + + <section><title>Disclaimer</title> + <p> + Any information in here that might be perceived as legal information is + informational only. We're not lawyers, so consult a legal professional + if needed. + </p> + </section> + + <section><title>The Licensing</title> + <p> + The POI project is <a href="http://www.opensource.org">OpenSource</a> + and developed/distributed under the <a + href="https://www.apache.org/foundation/license-faq.html"> + Apache Software License v2</a>. Unlike some other licenses, the Apache + license allows free open source development. Unlike some other Open Source + licenses, it does not require you to release your source or use any + particular license for your code which builds on top of it. (There are a + handful of restrictions, especially around attribution, notices and trademarks, + so it's worth a read of the license - it isn't scary!). If you wish to + contribute to Apache POI (which you're very welcome and encouraged to do so), + then you must agree to grant your contributions to us under the same license. + </p> + </section> + </section> + + <anchor id="WhereHelpNeeded"/> + <section><title>Where is help needed on the project?</title> + <p>There are a lot of open issues in Bugzilla and TODOs in the code. Please see + the section below for more on these. Get in touch using our mailing lists if you want + to volunteer.</p> + </section> + + <anchor id="GetInvolved"/> + <section><title>I just want to get involved, but don't know where to start?</title> + <ul> + <li>Read the rest of the website, understand what POI is and what it does, + the project vision, etc.</li> + <li>Use POI a bit, look for gaps in the documentation and examples.</li> + <li>Join the <a href="site:mailinglists">mailing lists</a> and share your knowledge with others.</li> + <li>Get <a href="site:git">Git</a> and check out the POI source tree</li> + <li>Documentation is always the best place to start contributing, maybe you found that if the documentation just told you how to do X then it would make more sense, modify the documentation.</li> + <li>Contribute examples - if there's something people are often asking about on the <a href="site:mailinglists">user list</a> which isn't covered in the documentation or current examples, try writing an example of this and uploading it as a patch.</li> + <li>Get used to building POI, you'll be doing it a lot, be one with the build, know its targets, etc.</li> + <li>Write Unit Tests. Great way to understand POI. Look for classes that aren't tested, or aren't tested on a public/protected method level, start there.</li> + <li>Download the file format documentation from Microsoft - + <a href="https://msdn.microsoft.com/en-us/library/cc313105%28v=office.12%29.aspx">OLE2 Binary + File Formats</a> or + <a href="https://ecma-international.org/publications-and-standards/standards/ecma-376/">OOXML XML File Formats</a></li> + <li>Submit patches (see below) of your contributions, modifications.</li> + <li>Check the <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI">bug database</a> for simple problem reports, and write a patch to fix the problem</li> + <li>Review existing patches in the <a href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">bug database</a>, and report if they still apply, if they need unit tests atc.</li> + <li>Take a look at all the <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI;bug_status=NEW;bug_status=NEEDINFO">unresolved issues in the bug database</a>, and see if you can help with testing or patches for them</li> + <li>Add in new features, see <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug database</a> for suggestions.</li> + </ul> + + <p>The Apache <a href="https://infra.apache.org/contributors.html">Contributors Tech Guide</a> gives a good overview how to start contributing patches.</p> + + <p>The Nutch project also have a very useful guide on becoming a + new developer in their project. While it is written for their project, + a large part of it will apply to POI too. You can read it at + <a href="https://wiki.apache.org/nutch/Becoming_A_Nutch_Developer">http://wiki.apache.org/nutch/Becoming_A_Nutch_Developer</a>. The + <a href="https://community.apache.org/">Apache Community Development + Project</a> also provides guidance and mentoring for new contributors.</p> + </section> + + <anchor id="SubmittingPatches"/> + <section><title>Submitting Patches</title> + <p> + If you use GitHub, you can submit Pull Requests to https://github.com/apache/poi. It is probably + a good idea to create an issue in the <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug Database</a> + first and reference it in the PR. + </p> + <p> + You can add patch files to the Bugzilla issues at + <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug Database</a>. + If there is already a bug-report, attach it there, otherwise create a new bug, + set the subject to [PATCH] followed by a brief description. + Explain you patch and any special instructions and submit/save it. + Next, go back to the bug, and create attachments for the patch files you + created. Be sure to describe not only the files purpose, but its format. + (Is that ZIP or a tgz or a bz2 or what?). + </p> + <p> + Ideally, patches should be submitted early and often. This is for + two key reasons. Firstly, it's much easier to review smaller patches + than large ones. This means that smaller patches are much more likely + to be applied to Git in a timely fashion. Secondly, by sending in your + patches earlier rather than later, it's much easier to get feedback + on your coding and direction. If you've missed an easier way to do something, + or are duplicating some (probably hidden) existing code, or taking things + in an unusual direction, it's best to get the feedback sooner rather than + later! As such, when submitting patches to POI, as with other Apache + Software Foundation projects, do please try to submit early and often, rather + than "throwing a large patch over the wall" at the end. + </p> + <p> + A number of Apache projects provide far more comprehensive guides to producing + and submitting patches than we do, you may wish to review some of their + information if you're unsure. The + <a href="https://commons.apache.org/patches.html">Apache Commons</a> one + is fairly similar as a starting point. + </p> + <p>You may create your patch file using either of the following approaches (the committers recommend the first):</p> + <section><title>Using Git</title> + <p> + If you are working on a Git clone of Apache POI (see the + <a href="site:git">Version Control page</a> for + more info), it is possible to generate + a patch of your changes (including new binary files) using Git. + </p> + <p> + When generating a patch / patch set from Git, for many related and + small changes a squashed patch is probably best, as it makes the + (manual) review quicker. For larger changes, several distinct + patches are probably best. + </p> + <p> + If you intend to do a noticeable amount of work enhancing Apache POI + on your own Git repo, we would suggest sending in patches early and + asking for advice. There's nothing worse than spending a week working + hard on your own on a change, only to discover you did something on + Day 1 that isn't acceptable to the project meaning your whole patch + needs re-doing... Git's offline workflow makes this easier, so try not + to fall into that trap! + </p> + </section> + <section><title>checklist before submitting a patch</title> + <ul> + <li>Added code complies with <a href="#CodeStyle">coding standards</a>.</li> + <li>Added code compiles and runs on Java 1.8 and preferably newer versions.</li> + <li>New java files begin with the <a href="https://www.apache.org/foundation/license-faq.html"> + Apache Software License</a> statement.</li> + <li>The code does not depend on code that is unlicensed or + <a href="https://www.apache.org/legal/resolved.html#category-a">incompatibly licensed with ASL 2.0</a>. + <a href="https://www.apache.org/licenses/GPL-compatibility.html">GPL</a> and LGPL code may not be used.</li> + <li>The code does not include <code>@author</code> tags.</li> + <li>Existing test cases succeed.</li> + <li>New test cases written and succeed (Use <code>@Disabled</code> from <code>org.junit</code> for in-progress work).</li> + <li>Documentation page extended as appropriate.</li> + <li>Examples updated or added as appropriate.</li> + <li>Diff files generated using <code>svn diff</code>.</li> + <li>Newly added files are included in the patch or alongside the patch.</li> + <li>The <a href="https://bz.apache.org/bugzilla/describecomponents.cgi?product=POI">bugzilla</a> subject dev contains [PATCH], task name and patch reason in subject.</li> + <li>The bugzilla description contains a rationale for the patch.</li> + <li>Attachment to the bugzilla entry contains the patch file.</li> + </ul> + </section> + </section> + + <anchor id="CodeStyle"/> + <section><title>Code Style</title> + <p>The long standing + <a href="site:res001">Minimal + Coding Standards</a> from 2002 still largely apply to the project.</p> + <p>When making changes to an existing file, please try to follow the + same style that that file already uses. This will keep things + looking similar, and will prevent patches becoming largely about + whitespace. Whitespace fixing changes, if needed, should normally be + in their own commit, so that they don't crowd out coding changes + in review.</p> + <p>Normally, tabs should not be used to indent code. Instead, spaces + should be used. If starting on a fresh file, please use 4 spaces to + indent your code. If working on an existing file, please use + whichever of 3 or 4 spaces that file already follows.</p> + <p>Normally, braces should open on the same line as the decision + statement. Braces should normally close on their own line. Brackets + should normally have a space before them when they are the first.</p> + <p>Lines normally shouldn't be too long. There's no hard and fast rule, + but if you line is getting above about 90 characters think about + splitting it, and you should rarely create something over about 100 + characters without a very good reason!</p> + </section> + + <anchor id="Mentoring"/> + <section><title>Mentoring and Committership</title> + <p>The POI project will generally offer committership to contributors who send + in consistently good patches over a period of several months.</p> + <p>The requirement for "good patches" generally means patches which can be applied + to SVN with little or no changes. These patches should include unit test, and + appropriate documentation. Whilst your first patch to POI may require quite a + bit of work before it can be committed by an existing committer, with any luck + your later patches will be applied with no / minor tweaks. Please do take note + of any changes required by your earlier patches, to learn for later ones! If + in doubt, ask on the <a href="site:mailinglists">dev mailing list</a>.</p> + <p>The requirement for patches over several months is to ensure that committers + remain with the project. It's very easy for a good developer to fire off half + a dozen good patches in the couple of weeks that they're working on a POI + powered project. However, if that developer then moves away, and stops + contributing to POI after that spurt, then they're not a good candidate for + committership. As such, we generally require people to stay around for a while, + submitting patches and helping on the mailing list before considering them + for committership.</p> + <p>Where possible, patches should be submitted early and often. For more details + on this, please see the "Submitting Patches" section above.</p> + + <p>Where possible, the existing developers will try to help and mentor new + contributors. However, everyone involved in POI is a volunteer, and it may + happen that your first few patches come in at a time when all the committers + are very busy. Do please have patience, and remember to use the + <a href="site:mailinglists">dev mailing list</a> so that other + contributors can assist you!</p> + <p>For more information on getting started at Apache, mentoring, and local + Apache Committers near you who can offer advice, please see the + <a href="http://community.apache.org/">Apache Community Development + Project</a> website.</p> + </section> + + <anchor id="FileFormatInformation"/> + <section><title>File Format Information</title> + <section><title>Publicly Available Information on the file formats</title> + <p> + In early 2008, Microsoft made a fairly complete set of documentation + on the binary file formats freely and publicly available. These were + released under the <a href="https://msdn.microsoft.com/en-us/openspecifications/default"> + Open Specification Promise</a>, which does allow us to use them for + building open source software under the <a + href="https://www.apache.org/foundation/license-FAQ.html"> + Apache Software License</a>. + </p> + <p> + You can download the documentation on Excel, Word, PowerPoint and + Escher (drawing) from + <a href="https://msdn.microsoft.com/en-us/library/cc313118.aspx">http://msdn.microsoft.com/en-us/library/cc313118.aspx</a>. + Documentation on a few of the supporting technologies used in these + file formats can be downloaded from + <a href="https://msdn.microsoft.com/en-us/library/jj633110.aspx">http://msdn.microsoft.com/en-us/library/jj633110.aspx</a>. + </p> + <p> + For the VSDX format (implemented in Apache POI as XDGF), an + <a href="https://msdn.microsoft.com/en-us/library/office/jj228622.aspx">introduction + is available from Microsoft</a>, and full details are available + <a href="https://msdn.microsoft.com/en-us/library/office/jj684209(v=office.15).aspx">here</a> + and + <a href="https://msdn.microsoft.com/en-us/library/hh645006(v=office.12).aspx">here</a>. + </p> + <p> + Previously, Microsoft published a book on the Excel 97 file format. + It can still be of plenty of use, and is handy dead tree form. Pick up + a copy of "Excel 97 Developer's Kit" from your favourite second hand + book store. + </p> + <p> + The newer Office Open XML (ooxml) file formats are documented as part + of the ECMA / ISO standardisation effort for the formats. This + documentation is quite large, but you can normally find the bit you + need without too much effort! This can be downloaded from + <a href="https://ecma-international.org/publications-and-standards/standards/ecma-376/">https://ecma-international.org/publications-and-standards/standards/ecma-376/</a>, + and is also under the + <a href="https://msdn.microsoft.com/en-us/openspecifications/default">OSP</a>. + </p> + <p> + Additionally for the newer Office Open XML (ooxml) file formats, you can + find some good introductary documentation (often clearer for getting + started with) at <a href="http://officeopenxml.com/">officeopenxml.com</a>, + which is an independent site documenting the file formats. + </p> + <p> + It is also worth checking the documentation and code of the other + open source implementations of the file formats. + </p> + </section> + <section><title>I just signed an NDA to get a spec from Microsoft and I'd like to contribute</title> + <p> + In short, stay away, stay far far away. Implementing these file formats + in POI is done strictly by using public information. Most of this Public + Information currently comes from the documentation that Microsoft + makes freely available (see above). The rest of the public information + includes sources from other open source projects, books that state the + purpose intended is for allowing implementation of the file format and + do not require any non-disclosure agreement and just hard work. + We are intent on keeping it legal, by contributing patches you agree to + do the same. + </p> + <p> + If you've ever received information regarding the OLE 2 Compound Document + Format under any type of exclusionary agreement from Microsoft, or + received such information from a person bound by such an agreement, you + cannot participate in this project. Sorry. Well, unless you can persuade + Microsoft to release you from the terms of the NDA on the grounds that + most of the information is now publicly available. However, if you have + been party to a Microsoft NDA, you will need to get clearance from Microsoft + before contributing. + </p> + <p> + Those submitting patches that show insight into the file format may be + asked to state explicitly that they have only ever read the publicly + available file format information, and not any received under an NDA + or similar, and have only made us of the public documentation. + </p> + </section> + </section> + +</body> +<footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> +</footer> +</document> diff --git a/src/documentation/content/xdocs/devel/history/changes-3x.xml b/src/documentation/content/xdocs/devel/history/changes-3x.xml new file mode 100644 index 0000000000..bf20e18103 --- /dev/null +++ b/src/documentation/content/xdocs/devel/history/changes-3x.xml @@ -0,0 +1,2255 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE changes PUBLIC "-//APACHE//DTD Changes POI//EN" "changes-poi.dtd"> + +<changes> + <contexts> + <context id="OOXML" title="OOXML"/> + <context id="OPC" title="OPC"/> + <context id="POI_Overall" title="POI Overall"/> + <context id="HSSF" title="Horrible SpreadSheet Format"/> + <context id="XSSF" title="ooXml SpreadSheet Format"/> + <context id="SXSSF" title="Streaming ooXml SpreadSheet Format"/> + <context id="SS_Common" title="SpreadSheet Common"/> + <context id="HSLF" title="Horrible SlideShow Format"/> + <context id="XSLF" title="ooXml SlideShow Format"/> + <context id="SL_Common" title="SlideShow Common"/> + <context id="HWPF" title="Horrible WordProcessor Format"/> + <context id="XWPF" title="ooXml WordProcessor Format"/> + <context id="HDF" title="Horrible Document Format"/> + <context id="HPSF" title="Horrible PropertySet Format"/> + <context id="HDGF" title="Horrible Dreadful Graph Format"/> + <context id="XDGF" title="ooXml Dreadful Graph Format"/> + <context id="DDF" title="Dreadful Drawing Format"/> + <context id="XDDF" title="ooXml Dreadful Drawing Format"/> + <context id="HMEF" title="Horrible Mail Encoder Format"/> + <context id="HSMF" title="Horrible Senseless Format"/> + <context id="HPBF" title="Horrible Peep Book Format"/> + <context id="HWMF" title="Horrible Wannabe Metafile Format"/> + <context id="HEMF" title="Horrible Ermahgerd Metafile Format"/> + <context id="POIFS" title="Poor Obfuscation Implementation FileSystem"/> + </contexts> + + <section id="current_release"> + <title>Current releases</title> + <p>The change log for the <a href="site:changes">current release</a> can be found in the home section.</p> + </section> + + <release version="3.17" date="2017-09-15"> + <summary> + <summary-item>Removal of deprecated classes and methods that were marked for removal in v3.17</summary-item> + <summary-item>Various modules: add sanity checks and fix infinite loops / OOMs caused by fuzzed data</summary-item> + <summary-item>OPC: fix linebreak handling on XML signature calculation (#61182)</summary-item> + <summary-item>SS Common: fix number formatting (github-43/52, #60422)</summary-item> + <summary-item>SXSSF: fix XML processing - unicode surrogates and line breaks (#61048, #61246)</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="61478" context="OPC">POI OOXML-Schema lookup uses wrong classloader</action> + <action type="fix" fixes-bug="61470" context="XWPF">Handle ruby (phonetic) elements in XWPFRun</action> + <action type="fix" fixes-bug="61381" context="POIFS">PushbackInputStreams passed to ZipHelper may not hold 8 bytes</action> + <action type="fix" fixes-bug="58975" context="SS_Common">Support formula evaluation with functions containing more than 127 arguments</action> + <action type="fix" fixes-bug="60422" context="SS_Common">Fix issue with number formatting in non-default locales</action> + <action type="fix" fixes-bug="61048" context="SXSSF">Fix issue where carriage returns were being escaped as line feeds</action> + <action type="fix" fixes-bug="61246" context="SXSSF">Do not replace Unicode Surrogate chars with ? when writing SXXSF sheets</action> + <action type="fix" fixes-bug="61363" context="POI_Overall">Unify escher shape id allocation</action> + <action type="fix" fixes-bug="61350" context="OPC">Use unsynchronized xmlbeans</action> + <action type="fix" fixes-bug="61346" context="HEMF">Add more sanity checks before allocation of byte arrays in HEMF/HWMF</action> + <action type="fix" fixes-bug="61338" context="HWMF">Avoid infinite loop with corrupt file</action> + <action type="fix" fixes-bug="61295" context="HPSF">Avoid OOM in hpsf with corrupt file</action> + <action type="add" fixes-bug="61331" context="SL_Common">Font group handling / common font interface</action> + <action type="fix" fixes-bug="61300" context="POIFS">Avoid infinite loop with corrupt file</action> + <action type="fix" fixes-bug="61286,61287" context="HSSF">Handle zero-length headerfooter and 2 byte WriteProtectRecord</action> + <action type="fix" fixes-bug="github-43" context="SS_Common">RoundUp and RoundDown functions round incorrectly in some scenarios</action> + <action type="fix" fixes-bug="github-52" context="SS_Common">Support number formats with trailing commas</action> + <action type="fix" fixes-bug="61294" context="POI_Overall">Fix bug that allowed IOUtils.skipFully to enter infinite loop</action> + <action type="fix" fixes-bug="61266" context="POIFS">More helpful exception on unsupported old MS Write WRI files</action> + <action type="fix" fixes-bug="61243" context="POI_Overall">Refactor and unify toString/toXml in DDF</action> + <action type="fix" fixes-bug="61182" context="OPC">Invalid signature created for streamed xlsx file</action> + </actions> + </release> + + <release version="3.17-beta1" date="2017-07-01"> + <summary> + <summary-item>XSSF: improved support for XSSFTables</summary-item> + <summary-item>HSLF: various fixes in table support</summary-item> + <summary-item>HPSF: reworked to cover edge cases and better support non-latin charsets</summary-item> + <summary-item>SL Common: fixed rendering of preset-shapes</summary-item> + <summary-item>HWPF: support for Binary RC4 / CryptoAPI de-/encryption</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="61203" context="XSSF">XSSFDrawing.getAnchorFromParent handles CTOneCellAnchor incorrectly, ignores CTAbsoluteAnchor</action> + <action type="fix" fixes-bug="56557" context="SXSSF">Output file get corrupted with SXSSFWorkbook and "chart sheet"</action> + <action type="fix" fixes-bug="61045" context="HSLF">Allow for extra bytes in FormatRecord</action> + <action type="add" fixes-bug="52063" context="SS_Common">Add formula support for LOOKUP(lookup_value, array)</action> + <action type="fix" fixes-bug="61169" context="SL_Common">Text with Japanese characters overflows textbox</action> + <action type="add" context="XSSF">XSSFTable improved support for creating columns and setting table areas, without needing to use CT classes</action> + <action type="fix" context="XSSF">XSSFTable should format numeric/date cells when used as Column Header names as Excel does</action> + <action type="add" fixes-bug="61162" context="HWPF">En-/decryption support for HWPF</action> + <action type="fix" fixes-bug="60230" context="XSSF">Round trip workbook encryption and decryption</action> + <action type="fix" fixes-bug="58325" context="XSSF">XSSFDrawing.getShapes() returns zero if sheet has more than one embedded OLE object</action> + <action type="fix" fixes-bug="61119" context="SL_Common">Fix preset shape rendering and shading</action> + <action type="fix" fixes-bug="61059" context="HSSF">Allow workbooks to contain more than 32k names</action> + <action type="fix" fixes-bug="github-55" context="XSSF">Allow XSSFNames set with a long name that looks similar to a cell address</action> + <action type="add" fixes-bug="github-25" context="SXSSF">Add lock/unlock sheet protection and tab colors</action> + <action type="update" fixes-bug="github-32" context="SS_Common">Speed up Irr() formula evaluation</action> + <action type="add" fixes-bug="github-52" context="HSSF">Add a function to convert an HSSFWorkbook to an HTML document from an InputStream</action> + <action type="fix" fixes-bug="github-53" context="XWPF">fix NPE when iterating over paragraphs in certain *.docx files</action> + <action type="update" fixes-bug="github-54" context="XSSF">Decrease execution time and memory consumption when adding XSSFPictures to an XSSFWorkbook</action> + <action type="fix" fixes-bug="52117" context="HPSF">Invalid "last printed" summary field value</action> + <action type="fix" fixes-bug="60352" context="XSSF">Text extraction: Don't include the text "null" for empty cells</action> + <action type="fix" fixes-bug="52372" context="HPSF">OutOfMemoryError parsing a word file</action> + <action type="fix" fixes-bug="61062" context="HPSF">Various HPSF related fixes</action> + <action type="fix" fixes-bug="61034" context="XSSF">Call to XSSFReader.getSheetsData() returns duplicate sheets</action> + <action type="fix" fixes-bug="61049" context="SS_Common">Fix order of two built-in formats</action> + <action type="add" fixes-bug="61021" context="XSSF">Extract Excel 2013 absPath info from xlsb</action> + <action type="fix" fixes-bug="60998" context="HSLF">HSLFTable.setRowHeight sets row height incorrect</action> + <action type="fix" fixes-bug="60996" context="XSSF">Multiple embedded objects on same sheet are ignored</action> + <action type="fix" fixes-bug="60993" context="HSLF">Grid and rowspan calculation in table cells is wrong</action> + <action type="fix" fixes-bug="60973" context="XDGF">Support for "PolylineTo" as well as existing alternate spelling "PolyLineTo"</action> + </actions> + </release> + + <release version="3.16" date="2017-04-19"> + <summary> + <summary-item>add initial streaming, read-only support for xlsb files</summary-item> + <summary-item>SL Common: various rendering issues resolved</summary-item> + <summary-item>various charset related fixes in SS Common, XSSF and HWPF</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="60810" context="XSLF">Check for duplicate relation-names for notes similar to the fix for slides (fixed via bug 55791)</action> + <action type="fix" fixes-bug="60823" context="SS_Common">Correct behavior of function DGET with multiple result entries but only one non-blank. Thanks to Patrick Zimmermann for the patch</action> + <action type="fix" fixes-bug="50955" context="HWPF">Fix charset handling in HWPFOldDocument</action> + <action type="add" fixes-bug="60826" context="XSSF">Add initial streaming, read-only support for xlsb files</action> + <action type="fix" fixes-bug="51519" context="XSSF">Allow user to select or ignore phonetic strings in shared strings table</action> + <action type="fix" fixes-bug="60662" context="XSLF">Slide import delete unrecognized elements in group shape</action> + <action type="fix" fixes-bug="60715" context="XSLF">Blank layout was not found</action> + <action type="add" fixes-bug="59227,github-48" context="SS_Common">Support Chinese and Japanese date formats</action> + <action type="fix" fixes-bug="59983" context="XSSF">Shift shared formulas when shifting rows in a sheet</action> + <action type="fix" fixes-bug="60625" context="SL_Common XSLF HSLF">Rendering issue with background and shape overlayed by image</action> + <action type="fix" fixes-bug="60626" context="XSSF">ArrayIndexOutOfBoundsException in EvilUnclosedBRFixingInputStream</action> + </actions> + </release> + + <release version="3.16-beta2" date="2017-02-02"> + <summary> + <summary-item>The third-party jar for commons-collections4 is now required for handling of OLE2 properties</summary-item> + <summary-item>Primitive (experimental) EMF/WMF text extraction support</summary-item> + <summary-item>Unicode and internationalization improvements</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="60219" context="SS_Common">FormulaParser can't parse external references when sheet name is quoted, thanks to Ignacio HR for the patch</action> + <action type="fix" fixes-bug="60369" context="SS_Common">Adjust pattern to better handle non-ASCII characters in Month-names which can appear since Java 8, thanks to Patrick Metz for the patch</action> + <action type="fix" fixes-bug="60512" context="OOXML">Missing XSSFRelation.CUSTOM_PROPERTY generates POIXMLException on cloneSheet() method, thanks to Samson Tesfay for the patch</action> + <action type="fix" fixes-bug="60031" context="SS_Common">DataFormatter parses months incorrectly when put at the end of date segment, thanks to Andrzej Witecki for the patch</action> + <action type="fix" fixes-bug="60601" context="XSSF">Unlink hyperlinks node if all hyperlinks removed from a sheet</action> + <action type="add" fixes-bug="60570" context="HEMF">Add rudimentary read-only capability for EMF</action> + <action type="add" fixes-bug="60586" context="SS_Common XSSF">Support embedding OLE1.0 package in XSSF / SS Common</action> + <action type="add" fixes-bug="60260" context="SS_Common">Partial support for unicode sheet names</action> + <action type="add" fixes-bug="60550" context="HSMF">Parse Content-ID for inline images in MAPIMessages</action> + <action type="fix" fixes-bug="60498" context="XSSF">Fix performance problem with XPath parsing in XSSF import from XML</action> + <action type="fix" fixes-bug="60484" context="HWPF">NPE when reading a document containing an embedded picture</action> + <action type="add" fixes-bug="60521" context="XSSF">XSSFGroupShape nesting</action> + <action type="add" fixes-bug="60519" context="SS_Common">Extractor for *SSF embeddings</action> + <action type="add" fixes-bug="60520" context="SS_Common">SS Common classes for *SSF shapes</action> + <action type="fix" fixes-bug="60526" context="OOXML">Make loggers final and make throttled log actually work, thanks to PJ Fanning for the patch</action> + <action type="fix" fixes-bug="60452" context="SS_Common">WorkdayCalculator calculateWorkdays does return wrong value for same day input, thanks to Fabio Heer for the patch</action> + <action type="add" fixes-bug="60465" context="XWPF">Cannot specify Interline spacing for paragraphs</action> + <action type="fix" fixes-bug="58237" context="XWPF">Unable to add image to Word document header</action> + <action type="update" fixes-bug="55902" context="SL_Common">Mixed fonts issue with Chinese characters (unable to form images from ppt)</action> + <action type="remove" fixes-bug="60331" breaks-compatibility="true" context="OOXML">Remove deprecated classes - remove constructors with PackageRelationship argument</action> + <action type="fix" fixes-bug="60329" context="XWPF">Added try/catch block to swallow NPE</action> + <action type="fix" fixes-bug="60370" context="XSSF">Encode some special characters when setting title/text for validation text-boxes</action> + <action type="fix" fixes-bug="60427" context="XSLF">Creating pictures in PowerPoint slides requires scratchpad-jar for adding WMF images</action> + <action type="remove" fixes-bug="60331" breaks-compatibility="true" context="HPSF">Remove deprecated classes - deprecate Mutable* property classes</action> + <action type="fix" fixes-bug="59200" context="SS_Common">Check for actual Excel limits on data validation title/text</action> + <action type="fix" fixes-bug="60373" context="XSLF">TableCell.getTextHeight() returns NullPointerException</action> + </actions> + </release> + + <release version="3.16-beta1" date="2016-11-20"> + <summary> + <summary-item>Initial work on adding a Gradle build, the Ant based build is currently still the official buildsystem, but there are plans to replace this with Gradle in the future</summary-item> + <summary-item>Add support for mixed-length cipher/hashes in password protected files typically used by Office for Mac</summary-item> + <summary-item>Add CryptoAPI and encryption write support for HSSF</summary-item> + <summary-item>Improve support for reading VBA macros</summary-item> + <summary-item>Examples to encrypt temp files in SXSSF</summary-item> + </summary> + <actions> + <action type="remove" fixes-bug="60331" context="XSSF">Remove deprecated classes (POI 3.16) - remove StylesTable.getNumberFormatAt(int)</action> + <action type="add" fixes-bug="60345" context="HSLF">Handle corrupt PICT streams</action> + <action type="fix" fixes-bug="59273" context="XSLF OOXML">Unable to create pptx file by potx file using Apache POI</action> + <action type="add" fixes-bug="github-42" context="SS_Common">Add setFormattingRanges() to interface ConditionalFormatting</action> + <action type="add" fixes-bug="60321" context="SXSSF">Examples: encrypt temp files created when unzipping or zipping an SXSSF workbook</action> + <action type="fix" fixes-bug="60337" context="XWPF">Table row isRepeatingHeader and isCantSplit throw NPE</action> + <action type="fix" fixes-bug="60342" context="XWPF">Handle an SdtCell that has no SdtContentCell</action> + <action type="fix" fixes-bug="60341" context="XWPF">Handle an SdtBody that has no SdtPr</action> + <action type="add" context="SS_Common">CellStyle support for "Quote Prefix" aka "123 Prefix"</action> + <action type="fix" fixes-bug="60320" context="POIFS">Issue opening password protected xlsx</action> + <action type="fix" fixes-bug="57366" breaks-compatibility="true" context="XWPF">Refactor Header/Footer creation to allow table in header/footer. No longer creates empty paragraph in header/footer</action> + <action type="fix" fixes-bug="53611" context="XSSF">Populate dimension of XSSF Worksheet when writing the document</action> + <action type="fix" fixes-bug="60315" context="OPC">Add 'yyyy-MM-dd' as a possible format for date metadata items in OPC</action> + <action type="fix" fixes-bug="60305" context="HSLF">Gracefully handle AIOOBE in reading potentially truncated pictstream</action> + <action type="fix" fixes-bug="59026" context="XSSF">Avoid possible NullPointerException when exporting to XML</action> + <action type="remove" fixes-bug="60059" context="XSLF">Deprecate xslf.usermodel.Drawing* - was: Can't change text of DrawingParagraph</action> + <action type="add" context="HDGF">Partial v5 Pointer and Text Extraction support</action> + <action type="fix" fixes-bug="60294" context="HSLF">Add "unknown" ShapeType for 4095</action> + <action type="fix" fixes-bug="60289" context="XSSF">Fix handling of rich-text unicode escapes with lowercase hex-chars</action> + <action type="fix" fixes-bug="60288" context="OOXML">reduce time needed to lookup document relationships</action> + <action type="add" fixes-bug="60029" context="SS_Common">Fix problem with Days360 method for the month of february</action> + <action type="add" fixes-bug="60134" context="POI_Overall">General: Enhance the Gradle build to allow to run API comparisons against previous releases using the Japicmp tool</action> + <action type="fix" fixes-bug="55714" context="XSLF">background image ignored on slide copy</action> + <action type="fix" fixes-bug="60255" context="XSSF">create drawings when workbook contains non-sequential drawing indices</action> + <action type="fix" fixes-bug="59302,60273,59830,59858,60158" context="POI_Overall">Various improvements for reading VBA macros</action> + <action type="fix" fixes-bug="53191" context="HSLF">Problems with line style when converting ppt to png</action> + <action type="fix" fixes-bug="60255" context="XSSF">Check for in-use drawing part names and use next available, when creating a new sheet drawing</action> + <action type="fix" fixes-bug="56781,60246" context="SS_Common">named range validation</action> + <action type="fix" fixes-bug="59907" context="SS_Common">Regression in getting and setting anchor type introduced in 3.15</action> + <action type="add" fixes-bug="60153" context="SXSSF">AES encrypt temporary files and workbook on disk</action> + <action type="fix" fixes-bug="51233,55075" context="SXSSF">image is incorrectly resized if custom row height is set</action> + <action type="fix" fixes-bug="60197" context="SS_Common">named range sheet index not updated when changing sheet order</action> + <action type="add" fixes-bug="60003" context="HSLF">Regression: Powerpoint text extractor from footer of master slide</action> + <action type="add" fixes-bug="60226" context="OOXML">ClassLoader workaround for OSGI when processing OOXML files</action> + <action type="fix" fixes-bug="59907" context="HSLF">Regression: types in HSSFClientAnchor.setAnchorType() were changed, breaking Jasperreports POI support</action> + <action type="add" fixes-bug="53028" context="HSSF">Broken auto fit row height in the cells with word wrap</action> + <action type="add" fixes-bug="60187" context="SS_Common">support BorderStyle enums in RegionUtil</action> + <action type="add" fixes-bug="59857" context="HSSF">Password protected files with "Microsoft Enhanced Cryptographic Provider v1.0"</action> + <action type="fix" fixes-bug="59687" context="XSSF">Comments removed from wrong row when removing a row from a sheet with empty rows</action> + <action type="fix" fixes-bug="59933" context="POI_Overall">Fix IllegalAccess exception caused by logger</action> + <action type="add" fixes-bug="59853" context="XSSF">Support Table (structured reference) sources in PivotTables</action> + <action type="add" context="POI_Overall">Add initial Gradle build</action> + </actions> + </release> + + <release version="3.15" date="2016-09-19"> + <summary> + <summary-item>HSSF, HSLF, HPSF, and HWPF support for writing out to a File, + including an existing open file (#<bug num="57919"/>)</summary-item> + <summary-item>Various improvements to HSSF and XSSF.</summary-item> + <summary-item>XSSF performance improvements for large numbers of named ranges.</summary-item> + <summary-item>Progress towards enums rather than ints for various types</summary-item> + <summary-item>CellStyle#BORDER_HAIR and #BORDER_DOTTED were swapped to correctly + reflect the official names and to be consistent with BorderStyle enum. + HAIR has smaller dots than DOTTED.</summary-item> + <summary-item>Removal of deprecated classes and methods detailed on bug <bug num="59170"/></summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="60140" context="OOXML">Fixed memory leak in FileBackedDataSource</action> + <action type="fix" fixes-bug="60128" context="OOXML">Close open file handles before raising an exception</action> + <action type="fix" fixes-bug="60131" context="SS_Common">D* function refactorings</action> + <action type="fix" fixes-bug="60130" context="SS_Common">Fix DGET function behaviour with empty cells</action> + <action type="fix" fixes-bug="52425" context="XSSF">Error adding Comments into cloned Sheets</action> + <action type="fix" fixes-bug="60025" context="SS_Common">DataFormatter should return TRUE or FALSE for boolean cell values</action> + <action type="add" fixes-bug="58191" context="XSLF">Support merge cells within a table row</action> + <action type="fix" fixes-bug="59958" context="XSSF">Add cells on the fly to the evaluation sheet cache on cache miss</action> + <action type="fix" fixes-bug="60005" context="XSLF">NPE in XSLFTextParagraph.getDefaultFontSize()</action> + <action type="add" context="POI_Overall" breaks-compatibility="true">Add Apache commons-collections4 dependency</action> + <action type="fix" context="SS_Common">XSSFFormulaEvaluator.evaluateAll() should mirror HSSF and use any setup referenced workbooks</action> + <action type="fix" fixes-bug="59736" context="SS_Common">Incorrect evaluation of SUBTOTAL with composite interval</action> + <action type="fix" fixes-bug="55384" context="SXSSF">Handle setting pre-evaluation string correctly in SXSSF as well</action> + <action type="fix" fixes-bug="59634" context="POI_Overall">Clarify and refine JavaDoc of various close() methods to consistently state that close() invalidates the object</action> + <action type="add" fixes-bug="57919" context="POI_Overall">HSSF, HSLF and HPSF support for in-place writing to the currently open File (requires the POIFS/NPOIFS was opened from a read-write File)</action> + <action type="add" fixes-bug="57919" context="POI_Overall">HSSF, HSLF, HPSF and HWPF support for writing out to a new File - normally faster than writing to an OutputStream</action> + <action type="fix" fixes-bug="59881" context="SS_Common">D* formula evaluation from blank cells in database headers</action> + <action type="add" fixes-bug="52122" context="XSSF">Excel does not handle conditional formatting based on formula correctly unless recalculation is forced</action> + <action type="add" fixes-bug="59106" context="SS_Common">WorkdayFunction does not read the area with holidays correctly to calculate work days</action> + <action type="add" fixes-bug="58802" context="HWPF">Allow reading of footnote and endnote properties</action> + <action type="add" fixes-bug="59665" context="HSSF">Using HSSFWorkbook#setSheetOrder to move sheets to the end corrupts bspos value in WorkbookRecordList</action> + <action type="add" fixes-bug="59740" context="SS_Common">Sheet.shiftRows incorrectly shifts merged region if there exists another merged region</action> + <action type="add" fixes-bug="59873" context="SS_Common SL_Common">migrate hyperlink constants from Hyperlink to HyperlinkType enum</action> + <action type="add" fixes-bug="59837" context="SS_Common">migrate cell alignment constants from CellStyle to HorizontalAlignment and VerticalAlignment enums</action> + <action type="add" fixes-bug="59791" context="SS_Common">migrate cell type constants from Cell to CellType enum</action> + <action type="fix" fixes-bug="59775" context="XSSF">correctly recognized URL hyperlinks containing a hash mark</action> + <action type="add" fixes-bug="59872" context="SS_Common">add Sheet#getHyperlink(CellAddress)</action> + <action type="add" fixes-bug="59841" context="OOXML">enable custom zip streams via OPCPackage.open(ZipEntrySource)</action> + <action type="add" fixes-bug="59833" context="SS_Common">migrate fill pattern constants from CellStyle to FillPatternType enum</action> + <action type="add" fixes-bug="56154" context="OOXML">Get and set last modified by user property</action> + <action type="add" fixes-bug="59776" context="OPC">Attach cause of exception when marshalling a Zip Package</action> + <action type="fix" fixes-bug="59814" context="SS_Common">clear cached EvaluationWorkbook and EvaluationSheetvalues from WorkbookEvaluator</action> + <action type="fix" fixes-bug="59805" context="POI_Overall">fixed memory leak in LocaleUtil</action> + <action type="fix" fixes-bug="59780" context="OPC">OPC support for a wider range of timezone'd created and modified date formats in package properties</action> + <action type="fix" fixes-bug="59796" context="XSSF">XSSFTable.getRowCount off-by-one error</action> + <action type="fix" fixes-bug="59795" context="XSSF">XSSFTable needs a method to reset start/end Cell References</action> + <action type="fix" fixes-bug="59790" context="SS_Common">convert FormulaType class to enum</action> + <action type="fix" fixes-bug="59789" context="HSSF">improve performance of row shifting on sheets that contain comments</action> + <action type="fix" fixes-bug="59786" context="HMEF">fix NPE from HMEFContentsExtractor</action> + <action type="add" fixes-bug="59788,59166" context="POI_Overall">Create temporary directories that are deleted on JVM exit</action> + <action type="remove" fixes-bug="59170" breaks-compatibility="true" context="HSSF">Remove deprecated classes (POI 3.15) - o.a.p.hssf.model.*Shape classes removed</action> + <action type="add" fixes-bug="59781" context="SS_Common">Move PaneInformation from HSSF to SS package</action> + <action type="fix" fixes-bug="59766" context="XSSF">When setting SAX features, handle Error too (eg from Google AppEngine)</action> + <action type="fix" fixes-bug="59734" context="XSSF">Make lookup and creation of named ranges constant-time instead of linear in the number of ranges in the workbook</action> + <action type="fix" fixes-bug="59920" context="XSSF">Fix regression in the handling of empty passwords for workbook protection</action> + <action type="fix" fixes-bug="59922" context="XSSF">Rename XSSFPaswordHelper to XSSFPasswordHelper</action> + </actions> + </release> + + <release version="3.15-beta2" date="2016-07-02"> + <summary> + <summary-item>initial work on extracting VBA macros (#<bug num="52949"/>)</summary-item> + <summary-item>remove deprecated classes (#<bug num="59170"/>)</summary-item> + <summary-item>various X/HSLF fixes for table and color handling</summary-item> + <summary-item>XSSF: formula evaluation performance improvements (#<bug num="57840"/>)</summary-item> + <summary-item>various fixes for merged regions in Common SS</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="59748" context="POI_Overall">Replace Hashtable with HashMap</action> + <action type="fix" fixes-bug="59746" context="XSSF">XSSF support for files from certain alternate tools where the row XML is missing the row number</action> + <action type="fix" fixes-bug="59743" context="SXSSF">ZipSecureFile throwing "zip bomb detected" exception when writing SXSSFWorkbook</action> + <action type="fix" fixes-bug="59742" context="XSLF">XSLFPictureData support for TIFF images</action> + <action type="add" fixes-bug="59717" context="OOXML">POIXMLProperties helper methods for reading and changing OOXML document thumbnails</action> + <action type="add" fixes-bug="59730" context="SS_Common">add Sheet.removeMergedRegions</action> + <action type="fix" fixes-bug="59729" context="SS_Common">move CellRangeUtil to o.a.p.ss.util</action> + <action type="fix" fixes-bug="56958" context="SS_Common">correctly check array formulas for intersection when adding merged regions</action> + <action type="fix" fixes-bug="59724" context="POI_Overall">Provide a close() method and implement Closeable on all OLE2-based POIDocument classes</action> + <action type="fix" fixes-bug="59719" context="XSSF">correctly parse literal data validation constraints</action> + <action type="remove" fixes-bug="59170" breaks-compatibility="true" context="POI_Overall">Remove deprecated classes</action> + <action type="add" fixes-bug="59645" context="SS_Common">Print row and column headings</action> + <action type="fix" fixes-bug="55983" context="HSLF">Creating transparent Freeform object does not result in transparent shape</action> + <action type="fix" fixes-bug="59702" context="XSLF">Setting background color in slide master</action> + <action type="add" fixes-bug="57838" context="XSSF">Remove related cell-comments when removing a row</action> + <action type="add" context="POI_Overall">Initial steps to allow to compile against Java 9</action> + <action type="add" fixes-bug="57840" context="XSSF">30% faster formula evaluation</action> + <action type="fix" fixes-bug="57840,57721" context="XSSF">Formula parsing and evaluation containing structured references (data tables)</action> + <action type="fix" fixes-bug="59684" context="SS_Common">Parsing absolute entire-row CellReferences</action> + <action type="fix" fixes-bug="59686" context="XSLF">Error when trying to access XSLFTableCell properties like textHeight, lineWidth, etc</action> + <action type="remove" fixes-bug="59170" breaks-compatibility="true" context="POI_Overall">Remove deprecated classes (POI 3.15) - remove BuiltinFormats.getBuiltinFormats()</action> + <action type="add" fixes-bug="59638" context="SS_Common">allow DataFormatter to use Locale-aware number grouping separator</action> + <action type="add" fixes-bug="57766" context="XSLF">Table isn't exported on convert slides of a .pptx slide show to a PNG/SVG image</action> + <action type="add" fixes-bug="58217" context="XSLF">support alpha channel on solid colors (fill, line, text)</action> + <action type="fix" context="XSLF">remove creation of empty paragraph in XSLFTextShape.addNewTextParagraph()</action> + <action type="fix" fixes-bug="59355" context="XSSF">XSSFPivotTable::addColumnLabel sets the cell type of a cell outside of the source data area</action> + <action type="fix" fixes-bug="54570" context="XSLF">InvalidFormatException because of Absolute URI forbidden</action> + <action type="remove" fixes-bug="59170" breaks-compatibility="true" context="POI_Overall">Remove deprecated classes (POI 3.15) - use FormulaError instead of ErrorConstants</action> + <action type="add" fixes-bug="58144" context="SL_Common">Behaviour for headers and footers of slides is inconsistent between slideshows created in 2003 and 2007</action> + <action type="add" fixes-bug="59443" context="SS_Common">get and set Comment addresses</action> + <action type="fix" fixes-bug="59434" context="XSLF">Cannot add a picture on a slide that already have an image with an hyperlink on it</action> + <action type="fix" fixes-bug="59383" context="SS_Common">performance regression: DataFormatter no longer caches formats</action> + <action type="fix" fixes-bug="59327" context="SL_Common">Setting text direction on a table cell has no effect</action> + <action type="add" fixes-bug="58648" context="SS_Common">Regression: Fix handling of whitespaces in formulas after it was slightly broken by the changes to support the intersection operator</action> + <action type="add" fixes-bug="59342" context="XSSF">Get and set sheet tab color</action> + <action type="add" fixes-bug="59340" context="SS_Common">Lookup IndexedColors by index</action> + <action type="add" fixes-bug="59336" context="SS_Common">Deprecate CellUtil methods that do not need a workbook parameter</action> + <action type="add" fixes-bug="59338" context="HSSF">Mark HSSFCellUtil for removal, replaced with Common SS CellUtil</action> + <action type="add" fixes-bug="52949" context="HSSF">VBA Macro reader and extractor</action> + <action type="fix" fixes-bug="55982" context="HSSF">Don't fail to open the spreadsheet if no TabIdRecord is found</action> + <action type="fix" context="POI_Overall">Fix some cases where file-handles were not closed properly, mostly when the documents could not be opened correctly</action> + <action type="add" fixes-bug="56911" context="HWPF">Fix IndexOutOfBoundsException in PlfLfo.add()</action> + <action type="add" fixes-bug="59264" context="SS_Common">unify setting cell border line style with BorderStyle</action> + </actions> + </release> + + <release version="3.15-beta1" date="2016-04-15"> + <summary> + <summary-item>removal of deprecated elements (#<bug num="59170"/>)</summary-item> + <summary-item>avoid XmlBeans calls to piccolo parser which caused OOM in rare cases (#<bug num="57031"/>)</summary-item> + <summary-item>support for passwords longer than 15 chars for write-protection or binary formats (#<bug num="59135"/>)</summary-item> + <summary-item>various NPE fixes in XSSF/HSSF</summary-item> + <summary-item>fixes for color handling in XSSF and support for system colors in Common SL</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="58909" context="XSSF">Add a cloneSheet() which directly sets the sheetname to allow to avoid a costly renaming of sheets</action> + <action type="fix" fixes-bug="59183" context="OPC">Regression in 3.14 on OPC files with less common timezone formats in the core properties</action> + <action type="fix" fixes-bug="59132" context="SS_Common">Adjust implementation of COUNTBLANK to be conforming to Excel, empty strings are counted as blank as well</action> + <action type="fix" fixes-bug="59199" context="XSSF">Gracefully handle null-values in Cell.setValue() for Date and Calendar similar to String</action> + <action type="fix" fixes-bug="59224" context="XSSF">fix XSSFColor.hasTint which incorrectly used the alpha channel, add XSSFColor.hasAlpha</action> + <action type="fix" fixes-bug="59222" context="XSSF">fix NPE raised by XSSFSheet.getCellComments()</action> + <action type="fix" fixes-bug="59212" context="SS_Common">copy non-validating XSSFSheet.addMergedRegionUnsafe from bug 58885 to Sheet interface</action> + <action type="fix" fixes-bug="59208" context="XWPF">bold xml value of "1" treated as false</action> + <action type="add" context="HSLF">Add support for system colors</action> + <action type="fix" fixes-bug="56930" context="SS_Common">Add Workbook.getNames() to allow to query for names that appear multiple times</action> + <action type="fix" fixes-bug="55791" context="XSLF">Avoid using an existing file-name when creating a new slide, it could still be left over from previous partial removal</action> + <action type="fix" fixes-bug="55668" context="SS_Common">Try to avoid NullPointerException by setting the cell to BLANK instead, when changing cell-type and a formula leads to null-string</action> + <action type="fix" fixes-bug="59135" context="HSSF">Password gets truncated when using passwords longer than 15 characters for the function protectSheet()</action> + <action type="add" fixes-bug="56549" context="HWPF">Correctly calculate char index ranges for HWPF in the TextPieceTable</action> + <action type="add" fixes-bug="57495" context="XWPF">Fix problem with tables in documents at pos 0</action> + <action type="fix" context="POI_Overall">Fix a number of edge-cases where file-handles would be leaked</action> + <action type="remove" fixes-bug="59170" breaks-compatibility="true" context="POI_Overall">Remove deprecated classes (POI 3.15) - *Workbook.setRepeatingRowsAndColumns()</action> + <action type="remove" fixes-bug="59170" breaks-compatibility="true" context="SS_Common">Remove deprecated classes (POI 3.15) - org.apache.poi.hssf/ss.util.Region</action> + <action type="add" fixes-bug="57031" context="XWPF">Out of Memory when extracting text from attached files</action> + <action type="fix" context="POI_Overall">More helpful exception when POIFSFileSystem is given a raw XML file</action> + <action type="fix" context="POI_Overall">More helpful exceptions when OPCPackage is given OLE2 or ODF or raw XML files</action> + </actions> + </release> + + <release version="3.14" date="2016-03-07"> + <summary> + <summary-item>Common: New version of ooxml-schema and ooxml-security jars which are linked to custom safe type loader</summary-item> + <summary-item>Common: OPC relation fix for multiple same named ids (<bug num="54916"/>)</summary-item> + <summary-item>Common: Update third-party dependencies: commons-logging, commons-codec, xmlsec, bouncycastle</summary-item> + <summary-item>Excel: Allow to set multiple cell style properties at once (<bug num="58633"/>)</summary-item> + <summary-item>Excel: Add API for inserting ignored warnings into XSSF sheets. + This can be used e.g. to suppress 'number stored as text' warnings. (<bug num="56892"/>)</summary-item> + <summary-item>Powerpoint: unify hyperlink handling</summary-item> + <summary-item>HSLF: various fixes for parsing and rendering</summary-item> + <summary-item>WMF: new API for WMF parsing and rendering (for Powerpoint)</summary-item> + <summary-item>XWPF: various fixes for handling paragraphs and tables</summary-item> + </summary> + <actions> + <action type="add" fixes-bug="57914" context="OPC">Provide a better error message for OOXML strict format which we do not support yet</action> + <action type="add" fixes-bug="47245" context="HSSF">Adjust handling of missing row-records as it seems LibreOffice/Excel are handling such documents</action> + <action type="add" fixes-bug="59056" context="SL_Common">Render individual slideshow shapes</action> + <action type="fix" fixes-bug="59074" context="POIFS">ExtractorFactory should give a more helpful exception on old Excel files too old for ExcelExtractor</action> + <action type="add" fixes-bug="57989" context="XSSF">XSSFChart support for setting chart titles</action> + <action type="fix" fixes-bug="59030" context="XWPF">Prevent NPE in XWPFTableCell's getVerticalAlignment() from Prasad Babu</action> + <action type="fix" fixes-bug="59021" context="XSSF">XSSFSheetXMLHandler fails to extract content if namespace is included in qName</action> + <action type="fix" fixes-bug="56345" context="SS_Common">Reject single-cell merged regions</action> + <action type="fix" fixes-bug="58339" context="SS_Common">Make OFFSET() allow missing optional height and width parameters</action> + <action type="add" fixes-bug="github-27" context="XWPF">Handle documents with a picture-only header</action> + <action type="fix" fixes-bug="58996" context="XSSF">Regression caused by fixing bug 56295: Don't try to unset fill color if it is not set to avoid invalid access inside the Xml structures</action> + <action type="fix" fixes-bug="57034" context="SXSSF">Cell.setCellValue((String)null) should be treated as an empty cell on SXSSF as well, to avoid a NPE when autosizing columns</action> + <action type="fix" context="XSLF">fixed NPE when adding pictures with existing non-picture media files (e.g. movies)</action> + <action type="fix" fixes-bug="58885" context="XSSF">Fixed performance regression after fixing bug 58443 when adding a merged region to an XSSFSheet</action> + <action type="add" context="OPC">Raised xmlsec version to 2.0.6</action> + <action type="add" fixes-bug="47291" context="HSLF">Cannot open link correctly which insert in ppt</action> + <action type="add" fixes-bug="41047" context="HSLF">Support hyperlinks in HSLF shapes and textruns</action> + <action type="add" fixes-bug="58879" context="SS_Common">Return SpreadsheetVersion from Workbook</action> + <action type="fix" context="HSLF">Fix NPE when calling HSLFTextRun.setHorizontalCentered()</action> + <action type="add" fixes-bug="58633" context="SS_Common">Set multiple cell style properties at once</action> + <action type="add" fixes-bug="56004" context="HSLF">Support for WMF rendering</action> + <action type="add" fixes-bug="56892" context="XSSF">Add API for inserting ignored warnings into XSSF sheets. This can be used e.g. to suppress 'number stored as text' warnings</action> + <action type="add" fixes-bug="58847" context="HPSF">Getters/setters/removers for the additional well-known document summary information properties from Office 12</action> + <action type="add" fixes-bug="57796" context="XSLF">Support hyperlink extraction when rendering slides</action> + <action type="fix" fixes-bug="54916" context="XSLF">POI does not always read all the slides in pptx files</action> + <action type="fix" fixes-bug="58043" context="SS_Common">Provide some compatibility between HSSF and XSSF in regards to values for CellStyle.setRotation()</action> + <action type="fix" fixes-bug="58067" context="XWPF">don't return deleted text when document is in review-mode</action> + <action type="fix" fixes-bug="58618" context="XWPF">XWPFParagraph insertNewRun and removeRun work incorrectly for runs after hyperlink/field runs</action> + <action type="fix" fixes-bug="58760" context="XSSF">Non-standard namespace-key breaks parsing XLSX files</action> + <action type="fix" fixes-bug="58746" context="HSSF">Fix missing adjustment of formulas when sheet-ordering is changed</action> + <action type="fix" fixes-bug="58616" context="XSSF">Try to initialize with empty password if not done before</action> + <action type="fix" context="POI_Overall">Fix some cases where file-handles were left open, mostly when failing to parse documents</action> + <action type="fix" fixes-bug="55030" context="HSLF">RichTextRun getFontName can not get chinese font name</action> + <action type="fix" fixes-bug="56570" context="HSLF">RecordType has repeat by code type 3009</action> + <action type="fix" fixes-bug="58159" context="HSLF">getHeaderText() and getFooterText() duplicate text in sheet.getTextRuns()</action> + <action type="fix" fixes-bug="58775" context="XSSF">Set maximum number of data formats to avoid corrupted workbook</action> + <action type="add" fixes-bug="58778" context="XSSF">Override built-in number formats in XSSFWorkbooks</action> + <action type="fix" fixes-bug="58733" context="HSLF">New AIOOBE in getCell while iterating through a table in PPT</action> + <action type="fix" fixes-bug="58718" context="HSLF">Master styles not initialized when running multithreaded</action> + </actions> + </release> + + <release version="3.14-beta1" date="2015-12-24"> + <actions> + <action type="fix" fixes-bug="58084" context="XSSF">Corrupted .xlsx file created when styles with borders are cloned from other workbooks</action> + <action type="add" fixes-bug="58570" context="SS_Common">Promote setting and getting the active cell in a worksheet to Common SS</action> + <action type="add" fixes-bug="47904" context="HSLF">Update text styles in HSLF MasterSlide</action> + <action type="add" fixes-bug="58670" context="SXSSF">Change underlying data structure in SXSSFRow to use a TreeMap instead of an array to store SXSSFCells</action> + <action type="add" fixes-bug="58671" context="SS_Common">Replace MissingCellPolicy class with enum</action> + <action type="add" fixes-bug="57450" context="SXSSF">Autosize columns on SXSSFSheets considering both active window and flushed rows</action> + <action type="add" fixes-bug="58557,52903" context="SS_Common">Add support for shifting hyperlinks when shifting rows on a sheet</action> + <action type="add" fixes-bug="58667" context="SS_Common">Implement Comparable interface in HSSFRow, XSSFRow, and SXSSFRow classes</action> + <action type="fix" fixes-bug="46210" context="HSLF">Title placeholder not recognized by Powerpoint 2003</action> + <action type="fix" fixes-bug="58663" context="XSLF">Pictures cannot be removed from a slide</action> + <action type="add" fixes-bug="58636" context="SS_Common">Replace ClientAnchor anchor type constants with AnchorType enum</action> + <action type="add" fixes-bug="58644" context="SS_Common">Replace Sheet.setZoom(num, den) with Sheet.setZoom(scale)</action> + <action type="remove" fixes-bug="58642" breaks-compatibility="true" context="SS_Common">Remove deprecated functions</action> + <action type="add" fixes-bug="58365" context="SS_Common">Get all cell comments on a sheet with Sheet.getCellComments()</action> + <action type="add" fixes-bug="58637" context="SS_Common">Add CellAddress class, to be used instead of CellReference when the concept of an absolute/relative reference is not applicable</action> + <action type="add" fixes-bug="58617" context="POI_Overall">Add custom safe XmlBeans type loader / rename vendor specific schema packages</action> + <action type="fix" fixes-bug="58630" context="POIFS">Signing failed after deletion of first sheet</action> + <action type="fix" fixes-bug="55955" context="HSLF">Filling an existing ppt table stopped working with 3.9</action> + <action type="fix" fixes-bug="54210" context="HSLF">When saving PPT to PNG, some text is rendered backwards</action> + <action type="fix" fixes-bug="53189" context="HSLF">Shapes drawn wrongly when ppt file converted to image</action> + <action type="remove" context="POI_Overall">Removed most reflection calls on private methods/fields from production code; others are wrapped by AccessController.doPrivileged()</action> + <action type="fix" fixes-bug="58597" context="XWPF">XWPFDocument causes SecurityException under SecurityManager</action> + <action type="fix" fixes-bug="53192" context="HSLF">Images in ppt file have wrong width when converting ppt to png</action> + <action type="add" context="HSLF">Add support for HSLF metro blobs</action> + <action type="fix" fixes-bug="52297" context="HSLF">Bullets are not aligned properly while converting ppt slide to image</action> + <action type="fix" fixes-bug="55265" context="SS_Common">DataFormatter correct support for alternate number grouping characters, eg 1234 + #'##0 = 1'234 not 1,234</action> + <action type="fix" fixes-bug="51622" context="SS_Common">autoSizeColumn incorrectly sizes columns containing leading whitespace</action> + <action type="fix" fixes-bug="58576" context="SS_Common">Rename misspelled SheetUtil.canComputeColumnWidth</action> + <action type="add" fixes-bug="58572" context="SS_Common">Add getHyperlink and getHyperlinkList to Sheet interface</action> + <action type="add" fixes-bug="58348" context="SS_Common">Add support for copying rows in XSSFWorkbooks</action> + <action type="fix" fixes-bug="45908" context="HSLF">RichTextRun.setBullet(false) doesn't work, bullets still here</action> + <action type="fix" fixes-bug="45088" context="HSLF">POI-HSLF changeTextInRichTextRun corrupts presentation</action> + <action type="fix" fixes-bug="45124" context="HSSF">inserting text or images wipes out boldness and makes everything italic</action> + <action type="add" fixes-bug="58452" context="SS_Common">Set cell formulas containing unregistered function names</action> + <action type="add" fixes-bug="58442" context="SS_Common">Add method to reorganize AreaPtg as top-left and bottom-right references</action> + <action type="fix" fixes-bug="58443" context="SS_Common">Prohibit adding merged regions that would overlap with existing merged regions</action> + <action type="add" context="OPC">Add a limit of the max number of characters that can be extracted to avoid sending applications out of memory with very large documents. Limit can be adjusted via ZipSecureFile.setMaxTextSize() if necessary</action> + <action type="fix" fixes-bug="58516" context="HSLF">Rare new aioobe in 3.13 on initialization of a handful of ppts</action> + <action type="fix" fixes-bug="56957" context="XSSF">Avoid error if Workbook with empty SharedStringTable is written</action> + <action type="fix" context="SL_Common">Common sl unification - copy first paragraph / textrun properties on XSLFTextShape.setText()</action> + <action type="fix" context="SL_Common">Common sl unification - converted ApacheconEU08 example to common sl - added missing functionality</action> + <action type="fix" context="SL_Common">Common sl unification - return null instead of default values for missing borders X/HSLFTable</action> + <action type="fix" context="SL_Common">Common sl unification - use points in HSLFTable.setColumnWidth()</action> + <action type="fix" context="SL_Common">Fix appending text to empty HSLFTextParagraph</action> + <action type="fix" fixes-bug="58558" context="SXSSF">SXSSFCell.setCellValue((RichTextString)null) fixed to work like XSSF and HSSF</action> + <action type="fix" fixes-bug="58536" context="SS_Common">DataFormatter and CellFormat non-localised support for localised currency formats like [$$-408]</action> + <action type="fix" fixes-bug="58532" context="SS_Common">DataFormatter cell formatting for things like [>999999]#,,"M";[>999]#,"K";#</action> + <action type="fix" fixes-bug="58085" context="HSSF">Fix removing sheet so not to break other existing sheet references</action> + <action type="fix" fixes-bug="58480" context="HSSF">Work around problem where on Windows systems a Mapped Buffer can still lock a file even if the Channel was closed properly</action> + <action type="add" context="POI_Overall">Update commons-logging to 1.2 and commons-codec to 1.10</action> + <action type="remove" breaks-compatibility="true" context="XSSF">Removed deprecated mixed case getter/setter in XSSFColor</action> + <action type="fix" fixes-bug="55032" context="SS_Common">Fix handling missing option values in financial functions PV, FV, NPER and PMT</action> + <action type="fix" fixes-bug="50319" context="HSSF">Make row groups which include row 0 work</action> + <action type="remove" breaks-compatibility="true" context="HDF">Removed deprecated HDF API</action> + <action type="fix" fixes-bug="58466" context="XSSF">Improve column manipulation in XSSF to avoid changes overwriting each other</action> + <action type="fix" fixes-bug="58471" context="SS_Common">Improve number formatting to more closely match Excel's behaviour</action> + <action type="fix" fixes-bug="58549" context="HSSF">Fix row limits for HSSFClientAnchor to allow the full range supported by Excel</action> + <action type="fix" fixes-bug="58579" context="XSSF">Add CTTableStyleInfo to poi-ooxml-schemas JAR</action> + </actions> + </release> + + <release version="3.13" date="2015-09-25"> + <summary> + <summary-item>conditional formatting support for DataBars, Icon Sets / Multi-States, and Color Scales</summary-item> + <summary-item>various improvements in spreadsheets formula and cell reference handling</summary-item> + <summary-item>enforcement of locale and timezone-aware handling through forbidden-apis check, + locale and timezone can now be switched via LocaleUtil</summary-item> + <summary-item>common api for slideshow (common sl) is now available + be aware of several api breaks especially in HSLF text handling</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="58350" context="XSSF">Make XSSF and HSSF consistent on Sheet.getMergedRegions: return empty list if there are none</action> + <action type="add" fixes-bug="58216" context="XSLF">provide picture-shape resize that maintains the aspect ratio</action> + <action type="add" fixes-bug="57925" context="SS_Common">Add a simple fix to avoid an NPE when Workbooks have invalid external references</action> + <action type="add" fixes-bug="57915" context="SS_Common">Fix Dev2Hex for numbers larger than Integer.MAX_VALUE and less than Integer.MIN_VALUE</action> + <action type="add" fixes-bug="57890" context="XSSF">Add support for different datatypes in XSSFImportFromXML</action> + <action type="add" fixes-bug="58207" context="XSLF">Provide user access to the original image dimensions</action> + <action type="fix" fixes-bug="55476" context="XWPF">Fix adding pictures to XWPFRun instances</action> + <action type="fix" fixes-bug="58341" context="SS_Common">Handle edge-cases in D* function</action> + <action type="add" fixes-bug="58245" context="SS_Common">Workbook support for iterating over Sheets</action> + <action type="fix" fixes-bug="58353" context="SS_Common">Return correct value in Match-Function with match-type == -1</action> + <action type="fix" fixes-bug="58315" context="XSSF">Avoid NPE for RichTextString without font-details</action> + <action type="fix" fixes-bug="53275" context="XSSF">XSSFFont: reset indexed color flag when setting a non-indexed color</action> + <action type="fix" fixes-bug="58039" context="SS_Common">Make DGet and DMin function implementations thread-safe</action> + <action type="fix" context="POI_Overall">Adjust Locale/Timezone handling to pass forbidden-api-checks and provide LocaleUtil to dynamically adjust the locale and timezone that POI operates on</action> + <action type="fix" context="SS_Common">Fix DAYS360 handling for US/EU method</action> + <action type="fix" fixes-bug="58254" context="SS_Common">CellFormatResult.text should check for nulls as per the javadoc</action> + <action type="fix" fixes-bug="58260" context="SXSSF">Fix checks for limit on number of styles in XSSF/SXSSF, fix more than 32k styles in SXSSF workbooks</action> + <action type="fix" fixes-bug="58262" context="SXSSF">ReadOnlySharedStringsTable now handles workbooks with an empty SST part</action> + <action type="fix" fixes-bug="52111" context="HSSF">Intersection formulae are now supported in XSSF</action> + <action type="fix" fixes-bug="58253" context="SS_Common">CellReference upper-case check for #REF!, and javadoc improvements</action> + <action type="fix" fixes-bug="58252" context="SS_Common">More CellReference unit testing coverage</action> + <action type="fix" fixes-bug="54938" context="POI_Overall">Throw InvalidFormatException as documented instead of IllegalArgumentException in WorkbookFactory.create()</action> + <action type="fix" fixes-bug="58237" context="XWPF">When adding a picture to a XWPF header or footer, attach it to the right part</action> + <action type="fix" fixes-bug="58220" context="XSSF">Improve the javadocs for XSSFFont and Font getFontHeight methods</action> + <action type="fix" fixes-bug="56479" context="OPC">Don't hardcode dcterms as namespace alias in the attribute, but expect the actual alias that is used in the corresponding element</action> + <action type="fix" fixes-bug="56519" context="XSLF">XSLFSlide.draw is not working with text embedded in PPTX</action> + <action type="fix" fixes-bug="58205" context="XSLF">getSlideMasters() returns the master slides in the incorrect order</action> + <action type="fix" fixes-bug="57786" context="XSLF">XSLFFreeformShape ignores quadratic bezier curves</action> + <action type="fix" fixes-bug="58206" context="XSLF">provide a mechanism to find slide layouts by name</action> + <action type="fix" fixes-bug="58204" context="XSLF">STYLE: ShapeContainer interface makes internal getShapesList() redundant</action> + <action type="add" fixes-bug="58190" context="XSLF">The current picture handling uses raw integers for types and index, replace with enum and reference</action> + <action type="fix" fixes-bug="58203" context="POI_Overall">Apparently Maven uses plurals for all artifacts except javadocs, so tweak our naming to make it happy</action> + <action type="add" fixes-bug="58193" context="XSLF">Use input stream rather than byte array for checksum etc</action> + <action type="add" fixes-bug="58200" context="SXSSF">SXSSF support for evaluating formula cells, provided the cell and all its references are within the current window</action> + <action type="fix" fixes-bug="58098" context="POIFS">Avoid NPE in cleanup if NPOIFSFileSystem is opened on a locked File under Windows</action> + <action type="add" context="SL_Common">Merged common_sl branch to trunk</action> + <action type="fix" fixes-bug="57571" context="SXSSF">Fix creating comments for XSSF/SXSSF, regression was introduced via bug <bug num="54920"/></action> + <action type="fix" fixes-bug="58175" context="SXSSF">Fix creating comments for XSSF/SXSSF, regression was introduced via bug <bug num="54920"/></action> + <action type="fix" fixes-bug="58156" context="POIFS">Possible data corruption in hasPOIFSHeader and hasOOXMLHeader</action> + <action type="add" fixes-bug="57484" context="POI_Overall">Allow processing of non-OOXML core namespace packages</action> + <action type="add" fixes-bug="58130" context="SS_Common">Conditional Formatting support for DataBars, Icon Sets / Multi-States, and Color Scales</action> + </actions> + </release> + + <release version="3.13-beta1" date="2015-07-23"> + <actions> + <action type="add" fixes-bug="56791" context="POIFS">The default POIFS implementation has been switched to NPOIFS. If you request a POIFSFileSystem, you will now get a NPOIFSFileSystem-based one. OPOIFSFileSystem remains for those who still want the old implementation</action> + <action type="add" fixes-bug="58138" context="SS_Common">Conditional Formatting support for the common Color class, in addition to previous color shorts</action> + <action type="fix" fixes-bug="58133" context="POIFS">Agile encryption - wrong checksum calculation</action> + <action type="fix" fixes-bug="58113" context="SXSSF">Regression: NullPointerException when setting cell value to null</action> + <action type="add" fixes-bug="57893" context="XSSF">Add a method for obtaining all merged regions on a worksheet. This is faster for XSSFSheet than obtaining each individually by iteration</action> + <action type="add" fixes-bug="58036" context="XSSF">Add basic support for VBA macro-enabled workbooks (xlsm)</action> + <action type="fix" fixes-bug="57744" context="HSMF">Fix parsing the email submission data when id contains a hyphen</action> + <action type="fix" fixes-bug="57678" context="HSMF">Better handle years in mail-messages between 1980 and 1999</action> + <action type="fix" fixes-bug="54332" context="HSLF">WMF extraction failing in Tika for older PowerPoint Files</action> + <action type="add" fixes-bug="56865" context="POI_Overall">Limit number of bytes (by counting them) while opening office docs</action> + <action type="add" fixes-bug="50090" context="POI_Overall">zip bomb prevention</action> + <action type="fix" fixes-bug="58069" context="HSSF">Biff8RC4 xorShort returns wrong value for unsigned shorts</action> + <action type="fix" fixes-bug="56420" context="SS_Common">Fix possible NullPointerException when empty cell is included in Sumif calculation</action> + <action type="fix" fixes-bug="58040" context="POI_Overall">Log Forging</action> + <action type="fix" fixes-bug="56328" context="XSSF">Improve AreaReference to take account of the spreadsheet format version when determining whether a reference is whole-column</action> + <action type="fix" fixes-bug="57963" context="XWPF">Fix and verify in CI builds that we can compile most examples without requiring scratchpad-jar, update documentation</action> + <action type="fix" fixes-bug="53109" context="HSSF">Correctly handle unicode strings in NameCommentRecord</action> + <action type="add" fixes-bug="57904" context="POI_Overall">Automatically verify that the resulting source-packages can be built</action> + <action type="fix" fixes-bug="57512" context="HSSF">Fix potential NPE in DateUtil for invalid dates</action> + <action type="fix" fixes-bug="57889" context="XWPF">Fix potential NPE in XWPFParagraph.getNumFmt()</action> + <action type="fix" fixes-bug="57951" context="SS_Common">Use BigDecimal in some cases in DataFormatter.formatRawCellContents, to avoid rounding problems on JDK8</action> + <action type="fix" fixes-bug="55410" context="XSSF">Use specific ID value which prevents Excel from turning comments into giant curved arrows</action> + </actions> + </release> + + <release version="3.12" date="2015-05-11"> + <summary> + <summary-item>remove limitations within XSSF - up to 64k cell styles (<bug num="57880"/>) and 65k comments (<bug num="56380"/>)</summary-item> + <summary-item>fixed XSSF cloning issues - for sheets (<bug num="57165"/>), styles (<bug num="56295"/>), pictures (<bug num="56467"/>)</summary-item> + <summary-item>Fix shifting comments with shifted rows (<bug num="56017"/>)</summary-item> + </summary> + <actions> + <action type="add" context="XWPF">Initial XWPFStyles support for working with default document paragraph and run styles</action> + <action type="fix" context="POI_Overall">If an empty file or stream is given to WorkbookFactory.create, give a more informative exception - EmptyFileException</action> + <action type="fix" fixes-bug="57552" context="XSLF">Sort PackagePart returns from OPCPackage by name considering numbers in filenames, so Image10.png comes after Image9.png, fixing problems with XSLF adding 10+ images to a slide</action> + <action type="fix" fixes-bug="57880" context="XSSF">Handle >32,767 cell styles and formats in XSSF (file format limit is 64,000)</action> + <action type="add" fixes-bug="57593" context="HSSF">Allow WorkbookFactory.create methods to open xlsx files protected with the default password</action> + <action type="add" fixes-bug="57593" context="HSSF">Add overloaded WorkbookFactory.create methods which take the spreadsheet password</action> + <action type="fix" fixes-bug="57666" context="SXSSF">When removing a SXSSF sheet, ensure temp files associated with it are disposed of</action> + <action type="fix" fixes-bug="57826" context="XSSF">If a XSSF shape has a buFont but no bullet character, mirror Excel and treat as un-bulleted</action> + <action type="fix" fixes-bug="57642" context="XSSF">Fix setSheetName with ISERROR on XSSF</action> + <action type="add" fixes-bug="57747" context="SS_Common">Add ISERR() function</action> + <action type="fix" fixes-bug="57829" context="XWPF">Avoid XmlValueDisconnectedException when removing a XWPFRun from a XWPFParagraph by removing from IRuns as well</action> + <action type="fix" fixes-bug="57851" context="POIFS">Skip null properties in PropertyTableBase, which is how PropertyFactory reports unsupported POIFS properties</action> + <action type="fix" fixes-bug="57820" context="HSLF">Avoid NPE on HSLF Tables with a top position of -1</action> + <action type="fix" fixes-bug="56579" context="XSSF">Throw exception if max string length of 32767 chars is exceeded in XSSF and SXSSF</action> + <action type="fix" fixes-bug="55386" context="SS_Common">Fix handling of bold formatting in example application 'ToHtml'</action> + <action type="fix" fixes-bug="47304" context="HDF">Use fixed encoding when extracting text in WordDocument</action> + <action type="fix" fixes-bug="56017" context="XSSF">Fix shifting comments with shifted rows</action> + <action type="fix" fixes-bug="56295" context="XSSF">Fix cloning of styles across workbooks and handling of default value of attribute applyFill</action> + <action type="fix" fixes-bug="56380" context="HSSF">Remove limitation of 1024 comments per Workbook</action> + <action type="fix" fixes-bug="56467" context="XSSF">Fix cloning of sheets with pictures</action> + <action type="add" context="XDGF">More helpful ExtractorFactory exception if given a Visio VSDX ooxml file</action> + <action type="fix" fixes-bug="56799" context="XWPF">Include CTTblGrid in the smaller poi-ooxml-schemas jar</action> + <action type="fix" fixes-bug="57165" context="XSSF">Avoid PartAlreadyExistsException when removing/cloning sheets</action> + <action type="fix" fixes-bug="56893" context="HSSF">Additional check for supported string-length to avoid creating broken XLS files later one</action> + <action type="fix" context="OPC">When saving an OPCPackage with no Core Properties (eg from Jasper Reports), ensure they are always added even if not yet used</action> + <action type="fix" fixes-bug="github-18" context="XWPF">Handle documents with a picture-only header</action> + <action type="fix" fixes-bug="57622" context="POI_Overall">Change from XMLEventFactory.newFactory to XMLEventFactory.newInstance, for IBM JDK Compatibility</action> + </actions> + </release> + + <release version="3.12-beta1" date="2015-02-28"> + <actions> + <action type="fix" fixes-bug="57459" context="SXSSF">Add method in SXSSFSheet to directly set row OutLineLevel</action> + <action type="fix" fixes-bug="57456" context="HSSF">Add workaround to read empty SSTRecord where Excel puts random number in unique-strings-count-field</action> + <action type="fix" fixes-bug="57535" context="XSSF">Add POI-specific error codes to FormulaError</action> + <action type="add" context="HWPF XWPF">Start on common interfaces for Paragraphs and Character Runs for HWPF and XWPF</action> + <action type="add" context="XWPF">Double Strikethrough support for XWPF runs, along the lines of the HWPF support</action> + <action type="fix" fixes-bug="57482" context="XSSF">Handle XSSF .xlsx files with no shared strings table in read-only mode</action> + <action type="fix" context="OPC">ExtractorFactory opening of OPCPackage from File should be read-only by default, as text extracting will never change things</action> + <action type="add" context="XSSF">XSSFSheet support for getDrawingPatriarch(), alongside the existing createDrawingPatriarch() method</action> + <action type="fix" context="HSSF">TIKA-1515 - Handle Excel 3 files with a 0x8001 codepage</action> + <action type="add" fixes-bug="53453" context="HWPF">Add methods to set margins in sections of HWPF documents</action> + <action type="fix" fixes-bug="46898" context="XSSF">Return #VALUE! for circular references</action> + <action type="fix" fixes-bug="46192" context="HSSF">Add methods to query outline level for HSSF and XSSF</action> + <action type="fix" fixes-bug="56240" context="HSLF">Handle PP97_DUALSTORAGE streams</action> + <action type="fix" fixes-bug="47261" context="HSLF">SlideShow.removeSlide makes PPT corrupted</action> + <action type="add" fixes-bug="49541" context="HSLF">Mapping of symbol characters to unicode equivalent</action> + <action type="add" fixes-bug="54541" context="HSLF">Add support for cropped images in Slide.draw()</action> + <action type="add" fixes-bug="57007" context="HSSF">Add initial implementations of DMIN and DGET functions</action> + <action type="add" context="HSLF">Support for Office Binary Document RC4 CryptoAPI Encryption for HSLF</action> + <action type="add" fixes-bug="57195" context="POIFS">Support for Office Binary Document RC4 Encryption</action> + <action type="fix" fixes-bug="57373" context="XSSF">Fix get/setFirstVisibleTab() for XSSFWorkbook</action> + <action type="fix" fixes-bug="57362" context="XSSF">Properly initialize chart-axis datastructure when loading a spreadsheet which already contains one</action> + <action type="fix" fixes-bug="56511" context="XSSF">Fix NullPointerException for RichText strings with no formatting for some runs</action> + <action type="add" fixes-bug="56550" context="POI_Overall">Avoid IBM JDK fail immediately during loading some POI classes, note: IBM JDK 1.7 or higher is needed because of XML APIs</action> + <action type="add" fixes-bug="56595" context="POI_Overall">Switch the cache in DateUtil.isADateFormat() to ThreadLocals to not have another syncpoint here</action> + <action type="fix" fixes-bug="56644" context="XSSF">NullPointerException in XSSFCell Constructor with different MissingCellPolicy</action> + <action type="fix" fixes-bug="56888" context="XSSF">XSSFDataValidation ignores "allow blank" read from sheet, assumes true</action> + <action type="fix" fixes-bug="57171" context="XSSF">Adjust the active sheet in setSheetOrder()</action> + <action type="fix" fixes-bug="57163" context="HSSF">Adjust the active sheet in removeSheet()</action> + <action type="fix" fixes-bug="57231" context="HSSF">Add missing ArrayRecord.clone()</action> + <action type="add" context="HSSF">Expose the version information from OldExcelExtractor</action> + <action type="fix" fixes-bug="57071" context="XSSF">3+ XSSF column label names for pivot tables</action> + <action type="add" fixes-bug="57063" context="XSSF">XSSF custom column label names for pivot tables</action> + <action type="fix" fixes-bug="57254" context="XWPF">Correctly build internal list of styles when styles are added</action> + <action type="fix" fixes-bug="57312" context="XWPF">Add check for null value of underline w:val</action> + </actions> + </release> + + <release version="3.11" date="2014-12-21"> + + <summary> +<!-- FIXME: formatting --> +<!--The most notable changes in this release are:--> + + <summary-item>Basic text extractor for very old Excel formats such as Excel 4 (Biff4), and + older Excel 5 and 95 formats</summary-item> + <summary-item>XML Signature support for XSSF, XWPF and XSLF (<bug num="56836"/>)</summary-item> + <summary-item>HSSF and XSSF support for getting existing Data Validations for a Sheet</summary-item> + <summary-item>HSSF and XSSF formula support for the PROPER function (<bug num="57010"/>)</summary-item> + <summary-item>XSLF support for adding slide notes (<bug num="55164"/>)</summary-item> + <summary-item>XMLBeans performance improved when using getXXXList() methods (<bug num="56854"/>)</summary-item> + <summary-item>Recommended Apache XMLBeans version increased to 2.6.0 (any version from + 2.3.0 or later will work though)</summary-item> + <summary-item>XSSF support for evaluating formula references to other Workbooks (<bug num="56737"/>)</summary-item> + <summary-item>HSSF and XSSF support for evaluating formulas with multi-sheet references, + for functions that support that (<bug num="55906"/>)</summary-item> + <summary-item>HSSF and XSSF Workbooks are now Closeable, so you can call close() to + explicitly free the file based resources when you're done (<bug num="56537"/>)</summary-item> + <summary-item>NPOIFS now fully supports writing, including streaming write, and in-place + updating of existing entries. NPOIFSFileSystem now surpasses the old + POIFSFileSystem in all cases.</summary-item> + <summary-item>XSSF Text Extraction support for Headers, Footers and Comments (<bug num="56022, 56023"/>)</summary-item> + <summary-item>SXSSF Shared Strings optional support (<bug num="53130"/>)</summary-item> + <summary-item>XWPF Change Tracking support (<bug num="56075"/>)</summary-item> + <summary-item>HWPF password hash function (<bug num="56077"/>)</summary-item> + <summary-item>XWPF document protection with password support (<bug num="56076"/>)</summary-item> + <summary-item>SXSSF support for a system-wide setting of where Temp files get created, via + TempFile / TempFileCreationStrategy (<bug num="56735"/>)</summary-item> + + +<!--Backwards Incompatible changes:--> + + <summary-item>The minimum Java version has been increased to Java 1.6</summary-item> + <summary-item>The minimum Apache Ant version has been increased to Apache Ant 1.8</summary-item> + <summary-item>The interface org.apache.poi.xssf.eventusermodel.XSSFSheetXMLHandler.SheetContentsHandler + has had two method signature changes: + <!--FIXME: formatting--> + endRow() -> endRow(int) + and + cell(String,String) -> cell(String,String,Comment) + </summary-item> + + +<!--Security related changes:--> + + <summary-item>All security related changes from 3.10.1 (CVE-2014-3529 and CVE-2014-3574) + are included in 3.11. Thanks to Stefan Kopf, Mike Boufford, Mohamed Ramadan, + and Christian Schneider for their help with these.</summary-item> + + <summary-item>Please note: You should use xmlbeans-2.6.jar (as shipped with this release) + instead of the xmlbeans-2.3.jar version from old releases to work around + CVE-2014-3574. If you have an alternate XML parser like Apache Xerces + in classpath, be sure to use a recent version! Older versions are likely to + break on setting required security features.</summary-item> + </summary> + + <actions> + <action type="fix" fixes-bug="57479" context="HSSF">Typo in HSSFWorkbook javadocs and quick-guide</action> + <action type="fix" fixes-bug="57480" context="HSSF">Fix some unnecessary casts, generics, Eclipse warnings, ...</action> + <action type="add" context="HSLF">Added workarounds to tests for JDK 6 LineBreakMeasurer bug</action> + <action type="fix" fixes-bug="57250" context="XSLF">XMLSlideShow.setSlideOrder() produces corrupted CTSlideIdList</action> + <action type="fix" fixes-bug="57272" context="HSLF">Deadlock on corrupted PPT file</action> + <action type="fix" context="OPC">XML signatures - ignore line breaks in Office 2007 .rels files</action> + <action type="add" context="HSSF">Basic text extractor for older Excel 5 and 95 formats</action> + <action type="add" context="HSSF">Basic text extractor for very old Excel formats such as Excel 4 (Biff4)</action> + <action type="fix" context="OPC">ClassCastException in validating xml signatures due to missing xml beans resources</action> + <action type="fix" fixes-bug="57171" context="XSSF">Adjust active sheet correctly when sheets are moved</action> + <action type="fix" fixes-bug="57163" context="HSSF">Adjust active sheet correctly when sheets are removed</action> + <action type="fix" fixes-bug="57164" context="XSSF">XSSFDrawing.createCellComment() does not honor dx and dy values passed in</action> + <action type="add" fixes-bug="55967" context="XSSF">Picture method to resize with different scales in width and height</action> + <action type="add" fixes-bug="github-13" context="HSSF XSSF">Add Cell.removeHyperlink() for HSSF and XSSF</action> + </actions> + </release> + + <release version="3.11-beta3" date="2014-11-11"> + <actions> + <action type="add" fixes-bug="57003" context="HSSF">Implement FIXED function</action> + <action type="add" fixes-bug="github-7" context="XWPF">Form check box extraction with XWPFWordExtractor</action> + <action type="add" fixes-bug="github-11" context="HSSF XSSF">Add Sheet.getDataValidations() for HSSF and XSSF</action> + <action type="add" fixes-bug="github-12" context="HSSF XSSF">Add Comment.getClientAnchor() for HSSF and XSSF</action> + <action type="fix" fixes-bug="57185" context="POI_Overall">Correct naming from "Serie" to "Series"</action> + <action type="fix" fixes-bug="57176" context="XSSF">Include CTDefinedNamesImpl in the smaller poi-ooxml-schemas jar</action> + <action type="fix" fixes-bug="57162" context="OPC">Could not open macro enabled xlsm file after writing using POI3.11beta2 version</action> + <action type="add" fixes-bug="57010" context="HSSF">Add implementation of function PROPER</action> + <action type="fix" fixes-bug="57166" context="HSSF">Add missing HSSFWorkbook constructor javadocs</action> + <action type="add" fixes-bug="57151" context="XSSF">And documentation and validation in CellRangeAddress to prevent invalid row/column combinations</action> + <action type="add" fixes-bug="55164" context="XSLF">Support for adding slide notes</action> + <action type="fix" fixes-bug="57143" context="XSSF">Javadocs and throws clause for WorkbookUtil</action> + <action type="add" fixes-bug="54542" context="XSLF">Add support for cropped images in XSLFPictureShape.drawContent()</action> + <action type="add" context="OPC">added ooxml-security-1.0 to the maven artifacts</action> + <action type="fix" fixes-bug="55864" context="XSSF">XSSFImportFromXML.importFromXML() does not support optional elements</action> + <action type="fix" fixes-bug="56835" context="XSSF">Unreadable content when adding multiple comments to cell</action> + <action type="add" context="SS_Common">SheetUtil.getCellWithMerges for getting a cell at a co-ordinate, or the primary one of it's merged region if it's a merged cell</action> + <action type="add" fixes-bug="56836" context="POIFS">XML signature support</action> + <action type="fix" fixes-bug="57080" context="POIFS">IndexOutOfBoundsException in poi decryptor</action> + <action type="add" context="POI_Overall">The minimum Apache Ant version required to build has been increased to 1.8.x or later</action> + <action type="add" fixes-bug="56956" context="POIFS">Add a NPOIFSFileSystem constructor with a FileChannel and the read-only option</action> + <action type="fix" fixes-bug="56914" context="XSSF">XSSFRowShifter.updateConditionalFormatting throws IOOBE when there are more than 1 CTConditionalFormatting</action> + <action type="fix" fixes-bug="56913" context="POI_Overall">Replace usages of o.a.p.util.ArrayUtil.copyOf* methods with replacements from j.u.Arrays</action> + <action type="fix" fixes-bug="51483" context="XSSF">XSSF locking of specific features not working</action> + <action type="fix" fixes-bug="48195" context="HSSF">Formulas: Fix incorrect evaluation of IF() with ROW()/COLUMN() as else-result</action> + <action type="fix" fixes-bug="55280" context="XSSF">Greatly improve performance of shifting rows in sheets with many merged regions</action> + <action type="fix" fixes-bug="51222" context="XSSF">XSSFColor.getARGBHex() returns wrong color for Excel 2007 xlsx file</action> + <action type="fix" fixes-bug="56730" context="XSSF">Fix exporting XML if schema contains ref-elements</action> + <action type="fix" fixes-bug="56864" context="XWPF">XWPFLatentStyles.isLatentStyle always returns true if there is at least 1 lsdException</action> + <action type="fix" fixes-bug="56854" context="XSSF">XMLBeans performance when using getXXXList() and other proxy methods</action> + </actions> + </release> + + <release version="3.11-beta2" date="2014-08-22"> + <actions> + <action type="fix" fixes-bug="56812" context="XSLF">For XSLF Pictures, provide a way to get the URI of externally linked pictures</action> + <action type="fix" fixes-bug="54764" context="XSSF">On supported XML parser versions (Xerces or JVM built-in, XMLBeans 2.6), enforce sensible limits on entity expansion in OOXML files, and ensure that subsequent normal files still pass fine (CVE-2014-3574)</action> + <action type="fix" context="POI_Overall">Recommended Apache XMLBeans version increased to 2.6.0 (any version from 2.3.0 or later will work though)</action> + <action type="fix" fixes-bug="56800" context="XSSF">Provide a helpful exception, XLSBUnsupportedException, if XSSFWorkbook is passed a .xlsb file</action> + <action type="fix" fixes-bug="56814" context="OPC">Switch from dom4j to JAXP</action> + </actions> + </release> + + <release version="3.10.1" date="2014-08-18"> + <summary> + <!-- FIXME: formatting--> + <summary-item>This release is a bugfix release to fix two security issues with OOXML:</summary-item> + <summary-item>Tidy up the OPC SAX setup code with a new common Helper, preventing + external entity expansion (CVE-2014-3529).</summary-item> + <summary-item>On supported XML parser versions (Xerces or JVM built-in, XMLBeans 2.6), + enforce sensible limits on entity expansion in OOXML files, and ensure + that subsequent normal files still pass fine (CVE-2014-3574).</summary-item> + + <summary-item>Please note: You should use xmlbeans-2.6.jar (as shipped with this release) + instead of the xmlbeans-2.3.jar version from the 3.10-FINAL release to work + around CVE-2014-3574. If you have an alternate XML parser like Apache Xerces + in classpath, be sure to use a recent version! Older versions are likely to + break on setting required security features.</summary-item> + + <summary-item>Thanks to Stefan Kopf, Mike Boufford, Mohamed Ramadan, and Christian Schneider + for reporting these issues!</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="54764" context="XSSF">On supported XML parser versions (Xerces or JVM built-in, XMLBeans 2.6), enforce sensible limits on entity expansion in OOXML files, and ensure that subsequent normal files still pass fine (CVE-2014-3574)</action> + <action type="fix" fixes-bug="56164" context="OPC">Tidy up the OPC SAX setup code with a new common Helper, preventing external entity expansion (CVE-2014-3529)</action> + </actions> + </release> + + <release version="3.11-beta1" date="2014-08-04"> + <summary> + <!-- FIXME: copy release summary from official release notes--> + <summary-item>Security fix CVE-2014-3529: external XML entity expansion. Affects reading OOXML documents.</summary-item> + <summary-item>Dropped support for Java 1.5. Java 6 is now the minimum version required to run POI.</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="56164" context="OPC">Tidy up the OPC SAX setup code with a new common Helper, preventing external entity expansion (CVE-2014-3529)</action> + <action type="fix" fixes-bug="55196" context="XWPF">Correct XWPF createTOC handling of short style names</action> + <action type="fix" fixes-bug="55050" context="SS_Common">If the start+end row and cell are the same on an AreaPtg, avoid inverting the relative flag</action> + <action type="fix" fixes-bug="54725" context="HWPF">HWPF where no parent style CHP exists, use an empty set when processing the style to avoid a NPE</action> + <action type="fix" fixes-bug="56502" context="XSSF">When shifting XSSF rows with formula cells, if the formula can't be parsed, log + leave it unchanged rather than failing</action> + <action type="fix" fixes-bug="56527" context="XSSF">Avoid NPE from XSSFHyperLink when setting the cell it references on a new link</action> + <action type="fix" fixes-bug="53984" context="HSSF">If an unsupported BofRecord is found for a sheet, warn and skip rather than breaking</action> + <action type="fix" fixes-bug="53984" context="HSSF">Support the ColInfoRecord coming after the cells, rather than before as is normal</action> + <action type="fix" fixes-bug="56132" context="XSSF">Allow XSSF formula evaluation to also skip missing external workbook references, if requested, in line with existing HSSF support</action> + <action type="add" fixes-bug="56020" context="XSSF">XSSF support for creating Pivot Tables</action> + <action type="add" fixes-bug="55906" context="SS_Common">Formula Evaluator support for multi-sheet references for those functions which support them, eg SUM(Sheet1:Sheet3!A1:B2)</action> + <action type="add" fixes-bug="56023" context="XSSF" breaks-compatibility="true">Allow XSSF event model to find + return comments, and use this for the event based .xlsx text extractor. Required backwards-incompatible updates to XSSFSheetXMLHandler.SheetContentsHandler</action> + <action type="fix" fixes-bug="56194" context="HPSF">HPSF thumbnail format tags are Int not UInt</action> + <action type="fix" fixes-bug="56735" context="POI_Overall">Allow a system wide setting of where Temp files (eg for SXSSF) are stored, via TempFile / TempFileCreationStrategy</action> + <action type="fix" fixes-bug="56683" context="OPC OOXML">Have XMLBeans request UTF-8 for strings by default, to avoid issues on the odd platform where that isn't already the case</action> + <action type="fix" fixes-bug="54443" context="HSSF">Correct HSSFOptimiser logic for the case where the to-keep style wasn't previously in use</action> + <action type="add" fixes-bug="56737" context="XSSF">XSSF support for evaluating formula references to other Workbooks</action> + <action type="fix" fixes-bug="56688" context="SS_Common">Fix border cases in EDATE function: handle RefEval and BlankEval and also return #VALUE, not #REF in case of error</action> + <action type="add" fixes-bug="56744" context="XSSF">Initial support for XSSF External Links tables, which hold references to other workbooks referenced by formulas and names</action> + <action type="fix" fixes-bug="56702" context="XSSF">If a cell is of type numeric but has an empty <v/> tag, return as 0</action> + <action type="fix" fixes-bug="56537" context="SS_Common">Make Workbook be Closeable, so you can call close() to explicitly free the file based resources when you're done</action> + <action type="fix" fixes-bug="54771" context="XWPF">Read text from SDTs at the table cell level, including (sometimes) Cover Page, Table of Contents and Bibliography</action> + <action type="fix" fixes-bug="56556" context="XSSF">Change how ColumnHelper finds CTCol instances, to speed up the more common use case when most are wanted for reading</action> + <action type="fix" fixes-bug="56572" context="SS_Common">HSSFCell should follow XSSF, and allow setting a null-style to return to the default style</action> + <action type="fix" fixes-bug="56563" context="HSSF">Fix multithreading bug when reading 2 similar files</action> + <action type="fix" fixes-bug="53691" context="HSSF">Fix a copy/paste error in CFRuleRecord.clone() </action> + <action type="fix" fixes-bug="56170" context="HSSF">Fix a problem with cells in workbooks becoming disconnected</action> + <action type="fix" fixes-bug="56514" context="XSSF">Add missing null-check if simple shape does not</action> + <action type="fix" fixes-bug="56325" context="HSSF">Bug 54400 introduced a problem when removing a sheet with named ranges</action> + <action type="fix" fixes-bug="47251" context="HSSF">NoteRecord can sometimes be double-padded if there's no author set</action> + <action type="fix" fixes-bug="54034" context="XSSF">Handle date format strings in an iso8601 style format, with a T in them</action> + <action type="fix" fixes-bug="56274" context="SXSSF">Correct SXSSF writing of tables when creating from a template</action> + <action type="fix" fixes-bug="56468" context="XSSF">Writing a workbook more than once corrupts the file</action> + <action type="fix" fixes-bug="53983" context="HSMF">Outlook sometimes stores a codepage of ANSI when it means 1252, detect and alias</action> + <action type="add" fixes-bug="56486" context="HSSF">Add XOR obfuscation/decryption support to HSSF</action> + <action type="add" fixes-bug="56269" context="XSSF">DateFormat - Rounding of fractionals</action> + <action type="fix" fixes-bug="56482" context="XSSF">Excel 2007 and later allows for more than 3 Conditional Formatting rules per sheet, so change our hard limit to logging a compatibility warning</action> + <action type="add" context="POIFS">Add NPOIFS in-place write support, including updating the contents of existing entries</action> + <action type="add" context="POIFS">Complete NPOIFS write support</action> + <action type="fix" fixes-bug="56447" context="POIFS">NPOIFS fixes for 2+gb files loaded via File (InputStream is limited to 2gb due to ByteBuffer limits)</action> + <action type="fix" fixes-bug="56450" context="HSSF">Avoid a NPE if a comment has no associated NoteRecord (but we still don't know where it belongs)</action> + <action type="fix" fixes-bug="56437" context="POIFS">Streaming write support in NPOIFS</action> + <action type="fix" fixes-bug="56315" context="SS_Common">Fix floating point rounding problems with ROUND function</action> + <action type="fix" fixes-bug="55594" context="SXSSF">Fix SXSSF encodings on EBCDIC platforms, by setting the required encoding explicitly</action> + <action type="fix" fixes-bug="56278" context="XSSF">Support loading .xlsx files with no Styles Table</action> + <action type="fix" fixes-bug="56195" context="XSSF">Replace System.err in XSSFSheetXMLHandler with proper logging</action> + <action type="fix" fixes-bug="56169" context="XSSF">Fix NPE during XSSFExportToXml export to XML with xs:all</action> + <action type="fix" fixes-bug="55923" context="XSSF">Fix compare/sorting of nodes in exported XML via XSSFExportToXml</action> + <action type="fix" fixes-bug="55926" context="XSSF">Handle numeric formula values when exporting to XML</action> + <action type="fix" fixes-bug="55927" context="XSSF">Handle date types when exporting to XML</action> + <action type="fix" fixes-bug="56011" context="XSSF">Use default style if the cell style attribute is not present</action> + <action type="add" context="POI_Overall" breaks-compatibility="true">End support for Java 1.5. POI now requires Java 6 or higher</action> + <action type="add" context="POI_Overall" breaks-compatibility="true">Upgrade third party libs to latest versions: commons-logging, commons-codec, log4j</action> + <action type="fix" fixes-bug="56260" context="HSLF">Avoid warnings when a TextHeaderAtom is empty and has another straight after, or where there's a TextRulerAtom / MasterTextPropAtom / TextSpecInfoAtom before the Text Chars / Bytes</action> + <action type="add" fixes-bug="56075" context="XWPF">Add Change Tracking support to XWPF</action> + <action type="add" fixes-bug="56077" context="HWPF">Add password hash function to HWPF</action> + <action type="add" fixes-bug="56076" context="XWPF">Add document protection with password support to XWPF</action> + <action type="fix" fixes-bug="55026" context="POI_Overall">Support OOXML ContentTypes which include parameters</action> + <action type="fix" fixes-bug="55732" context="HSLF">PPT can't open, fails with "Couldn't instantiate ... StyleTextProp9Atom"</action> + <action type="fix" fixes-bug="56138" context="HPSF">HPSF code page strings can be zero length</action> + <action type="add" fixes-bug="53130" context="SXSSF">SXSSF Shared Strings option support</action> + <action type="fix" fixes-bug="55902" context="XSLF">Mixed fonts issue with Chinese characters (unable to form images from ppt)</action> + <action type="add" fixes-bug="56022" context="XSSF">XSSF Event Text Extractor header/footer support</action> + <action type="fix" fixes-bug="53282" context="XSSF">Hyperlink with a non-breaking space throws java.lang.IllegalStateException</action> + <action type="fix" fixes-bug="55802" context="XWPF">Wrong encoding used for non-ASCII characters in text runs</action> + <action type="add" context="HWPF">Expose the StyleIndex of HWPF CharacterRuns</action> + <action type="fix" fixes-bug="51891" context="POIFS">Fix StringIndexOutOfBoundsException : Ole10Native.<init> (parsing word file)</action> + </actions> + </release> + + <release version="3.10-FINAL" date="2014-02-08"> + <actions> + <action type="fix" fixes-bug="51585" context="XSSF">WorkbookFactory.create() hangs when creating a workbook</action> + <action type="add" fixes-bug="55873" context="POI_Overall">Support for COUNTIFS function</action> + <action type="fix" fixes-bug="55723" context="HSSF">Inconsistent behavior in HSSFSheet.setAutoFilter() function, also make XSSF work when setAutoFilter is called multiple times</action> + <action type="fix" fixes-bug="51158" context="XSSF">Writing a workbook multiple times produces unreadable content</action> + <action type="fix" fixes-bug="45776" context="HSLF">Fix corrupt file problem using TextRun.setText</action> + <action type="fix" fixes-bug="41246" context="HSLF">AIOOBE with missing notes entries</action> + <action type="fix" fixes-bug="48593" context="HSLF">Multiple Saves Causes Slide Corruption</action> + <action type="add" fixes-bug="55579" context="HSLF">Support embedding OLE objects into HSLF</action> + <action type="add" fixes-bug="55818" context="POIFS">Add encryption support</action> + <action type="fix" fixes-bug="55731" context="POI_Overall">Fix StringBuilder logic in DataFormatter.cleanFormatForNumber </action> + <action type="fix" fixes-bug="55730" context="HSSF">Fix org.apache.poi.ss.usermodel.BuiltinFormats.java for 0x29-0x2c </action> + <action type="fix" fixes-bug="55901" context="HPSF">Avoid using RMI based exception from PropertySetFactory, as it's not needed nor helpful</action> + <action type="fix" fixes-bug="55850" context="XSSF">Fix NullPointerException during Xml-extraction from xlsx</action> + <action type="fix" fixes-bug="55640" context="XSSF">Avoid IndexOutOfboundsException when setting nested row grouping</action> + <action type="fix" fixes-bug="55745" context="XSSF">fix handling of tables in XSSF if there are comments as well</action> + <action type="add" fixes-bug="55560" context="HSLF">Patch for hiding slides in HSLF</action> + <action type="fix" fixes-bug="53176" context="XSLF">Fixed auto shapes render problem in pptx files</action> + <action type="add" fixes-bug="55661" context="XSSF">CellStyle support for get/set Shrink To Fit</action> + <action type="fix" fixes-bug="49237" context="HSSF">HSSF Row Style XfIndex is 12 not 16 bits of data</action> + <action type="fix" fixes-bug="53475" context="POIFS">OOXML encrypted document fix for cspname being optional</action> + <action type="fix" fixes-bug="55733" context="XWPF">XWPFWordExtractor needs to handle .docx files with neither headers nor footers</action> + <action type="fix" fixes-bug="55729" context="HSSF">DataFormatter should format Error cells, returning the Excel error string</action> + <action type="add" fixes-bug="55612" context="HSSF">Performance improvement in HSSFCellStyle.getDataFormatString()</action> + <action type="add" fixes-bug="55611" context="HSSF">Performance improvement in DateUtil.isADateFormat(int, String)</action> + <action type="add" fixes-bug="55578" context="HSSF">Support embedding OLE1.0 packages in HSSF</action> + <action type="add" fixes-bug="49658" context="HSSF">Support embedding EMF/WMF pictures in HSSF</action> + <action type="fix" fixes-bug="52400" context="HMEF">Fix handling some types of TNEF files</action> + <action type="fix" fixes-bug="54400" context="HSSF">Updating the index in the LinkTable whenever sheets are removed</action> + <action type="fix" fixes-bug="49940" context="XSSF">Apply patch to avoid XmlValueDisconnectedException when saving a file twice</action> + <action type="add" fixes-bug="55369" context="SXSSF">Add support for collapsing rows in SXSSF</action> + <action type="fix" fixes-bug="55692" context="POIFS">Give a more helpful error if an Encrypted .xlsx file is passed to HSSF</action> + <action type="fix" fixes-bug="55650" context="XSSF">Avoid AIOOBE if a non-existant Xfs is requested for a style</action> + <action type="fix" fixes-bug="55658" context="SXSSF">Don't fail in SXSSF if a numeric cell is overwritten with a string</action> + <action type="fix" fixes-bug="55341" context="POI_Overall">Constants for HAIR and DOTTED border styles are swapped</action> + <action type="add" context="POI_Overall">Add Eclipse project files</action> + <action type="add" fixes-bug="55647" context="POI_Overall">When creating a temp file, ensure the name isn't already taken</action> + <action type="add" fixes-bug="54722" context="HSLF">Extract text from HSLF tables</action> + <action type="add" fixes-bug="55544" context="POIFS">Support for SHA-512 hashes on OOXML protected documents, as used by Office 2013</action> + </actions> + </release> + + <release version="3.10-beta2" date="2013-09-19"> + <actions> + <action type="fix" fixes-bug="53798" context="XSSF">Add fix for XmlValueDisconnectException during shifting rows</action> + <action type="fix" fixes-bug="54524" context="POI_Overall">Fix handling of special case in FormulaShifter</action> + <action type="fix" fixes-bug="50298" context="HSSF">Fix corruption of Workbook when setting sheet order</action> + <action type="fix" fixes-bug="55419" context="POI_Overall">Fix SimpleFractionException when fraction goes to greater than overflow</action> + <action type="add" fixes-bug="54786" context="XSSF">Add support for quoting in date formatting</action> + <action type="fix" fixes-bug="52233" context="XSSF">Do not make the XSSFSheet invalid during write()</action> + <action type="add" fixes-bug="55195" context="HSSF">MultiOperandNumericFunction.collectValue() currently uses concrete final classes but should use interfaces instead</action> + <action type="fix" fixes-bug="55380" context="HSSF">Endless loop in CellRangeUtil.mergeRanges() when regions are overlapping</action> + <action type="add" fixes-bug="55347,45551" context="XSSF">Integrate 55292 into XSSF extractors -- extract text from text boxes in xlsx files</action> + <action type="fix" fixes-bug="55361" context="XWPF">Tika 792 - Avoid CTMarkup NoSuchMethodException stack trace by adding two beans to ooxml-lite"</action> + <action type="fix" fixes-bug="55294,52186" context="XSSF">Fix column grouping in XSSF</action> + <action type="add" fixes-bug="55292" context="XSSF">Enhancements to XSSFSimpleShape (textbox) including: ability to add multiple paragraphs, formatting (read/write) and text extraction</action> + <action type="fix" fixes-bug="55191" context="HPSF">Avoid a ClassCastException if a HPSF string property isn't directly stored as a string</action> + <action type="fix" context="HSMF">HSMF ascii encoding detection should use the CodePage properties where available</action> + <action type="fix" context="HSMF">HSMF fixed length property parsing should be more forgiving of some type differences from the property default</action> + <action type="fix" fixes-bug="54233" context="HPSF">Some HPSF documents require UnicodeStrings to be 4-byte aligned, spot these from the otherwise invalid length</action> + <action type="add" context="POI_Overall">Upgrade version of JUnit to 4.11 to avoid problems when executing unit tests using Apache Ant >= 1.7</action> + </actions> + </release> + + <release version="3.10-beta1" date="2013-06-28"> + <actions> + <action type="fix" fixes-bug="54925" context="HSLF">Avoid issues if the length of a StyleTextPropAtom prop is longer than the parent text</action> + <action type="fix" fixes-bug="54564" context="HSSF">Fix error message text for a workbook with no sheets when a sheet operation is performed</action> + <action type="fix" fixes-bug="53972" context="HSSF">Presence of PLV record shouldn't affect HSSF Data Validation</action> + <action type="fix" fixes-bug="55142" context="XWPF">Not all XWPF SDT blocks need newlines</action> + <action type="fix" fixes-bug="54920" context="XSSF">XSSFDrawing.createCellComment causes CommentsTable to lose reference to comment in cell A1</action> + <action type="fix" fixes-bug="54982" context="XSSF">ExtractorFactory does not close files when extracting via OCPPackage.open()</action> + <action type="fix" fixes-bug="54607" context="XSSF">NullPointerException in XSSFSheet.getTopRow() when the top row is 1</action> + <action type="fix" fixes-bug="54686" context="XSSF">Improve how DataFormatter handles fractions</action> + <action type="fix" fixes-bug="55066" context="XWPF">Don't load XWPF Footnotes twice</action> + <action type="add" fixes-bug="54849" context="XWPF">Controlled content/Form (Std/StdBlock) content</action> + <action type="fix" fixes-bug="github-2" context="HSSF">HSSFWorkbook.getAllEmbeddedObjects() needs to recurse into container Shapes</action> + <action type="add" fixes-bug="github-4" context="XWPF">Expose from XWPFParagraph the number level and format, if applied</action> + <action type="add" fixes-bug="github-3" context="XWPF">Extract references from XWPF footnotes</action> + <action type="fix" fixes-bug="55053" context="POI_Overall">Update License links following ECMA site re-organisation</action> + <action type="add" fixes-bug="49658" context="HSSF">Support embedding EMF/WMF pictures in HSSF </action> + <action type="add" fixes-bug="55047" context="POI_Overall">REPT formula support </action> + <action type="add" fixes-bug="55042" context="POI_Overall">COMPLEX formula support </action> + <action type="add" fixes-bug="55041" context="POI_Overall">CODE formula support </action> + <action type="fix" fixes-bug="55001" context="HSLF">Support Unicode text (TextCharsAtom) in HSLF TextShape</action> + <action type="fix" fixes-bug="54682" context="HWPF">UnhandledDataStructure should sanity check before allocating, not after</action> + <action type="add" fixes-bug="54673" context="POI_Overall">Simple wildcard support in HLOOKUP, VOOLKUP, MATCH, COUNTIF </action> + <action type="fix" fixes-bug="54625" context="HSSF">Register user-defined functions in instance scope instead of static </action> + <action type="fix" fixes-bug="54469" context="SS_Common">Support for financial functions IPMT and PPMT </action> + <action type="fix" fixes-bug="54407" context="HSLF">Avoid XmlValueDisconnectedException when merging slides </action> + <action type="fix" fixes-bug="54356" context="POI_Overall">Support of statistical function SLOPE</action> + <action type="fix" fixes-bug="54403" context="POI_Overall">Support of statistical function INTERCEPT</action> + <action type="fix" fixes-bug="54557" context="POI_Overall">Don't mis-detect format patterns like .000 as dates</action> + <action type="fix" fixes-bug="54506" context="HSSF">Support unusual .xls files with a BOOK directory entry (normally it is Workbook)</action> + <action type="add" fixes-bug="54508" context="POI_Overall">EDATE formula support</action> + <action type="fix" fixes-bug="53810" context="POIFS">NPOIFS fix for 0 not -1 padded partially used XBATs</action> + <action type="fix" fixes-bug="54402" context="POI_Overall">IfError handling of indirect references</action> + <action type="add" fixes-bug="53966" context="POI_Overall">IfError support (from Analysis Toolpak)</action> + <action type="fix" fixes-bug="53650" context="SXSSF">Prevent unreadable content and disallow to overwrite rows from input template in SXSSF</action> + <action type="fix" fixes-bug="54228,53672" context="XSSF">Fixed XSSF to read cells with missing R attribute</action> + <action type="fix" fixes-bug="54206" context="HSSF">Ensure that shared formulas are updated when shifting rows in a spreadsheet</action> + <action type="fix" context="HSSF">Synchronize table headers with parent sheet in XSSF</action> + <action type="fix" fixes-bug="54210" context="HSLF">Fixed rendering text in flipped shapes in PPT2PNG and PPTX2PNG</action> + </actions> + </release> + + <release version="3.9" date="2012-12-03"> + <actions> + <action type="fix" fixes-bug="54188" context="HSLF">Avoid NPE in PPT2PNG</action> + <action type="fix" fixes-bug="52628" context="POI_Overall">Replace System.err info messages with a POILogger</action> + <action type="fix" fixes-bug="54137" context="POI_Overall">improved performance of DataFormatter with Fractions</action> + <action type="fix" fixes-bug="54099" context="XWPF">Ensure that CTHMerge and CTTcBorders go to poi-ooxml-schemas jar</action> + <action type="fix" fixes-bug="54111" context="HSLF">Fixed extracting text from table cells in HSLF</action> + <action type="add" fixes-bug="52583" context="HWPF">add support for drop-down lists in doc to html conversion</action> + <action type="add" fixes-bug="52863" context="HWPF">add workaround for files with broken CHP SPRMs</action> + <action type="fix" fixes-bug="53182" context="HWPF">Reading combined character styling and direct formatting of a character run</action> + <action type="fix" fixes-bug="52311" context="HWPF">Conversion to html : Problem in titles number </action> + <action type="fix" fixes-bug="53914" context="HWPF">TableRow#getTopBorder() return bottom's border</action> + <action type="fix" fixes-bug="53282" context="XSSF">Avoid exception when parsing OPC relationships with non-breaking spaces</action> + <action type="fix" fixes-bug="54016" context="HSSF">Avoid exception when parsing workbooks with DConRefRecord in row aggregate</action> + <action type="fix" fixes-bug="54008" context="POI_Overall">Fixed Ant build to support build directories with blanks</action> + <action type="fix" fixes-bug="53374" context="POI_Overall">Avoid exceptions when parsing hyperlinks of type "javascript://"</action> + <action type="fix" fixes-bug="53404" context="HSSF">Fixed compatibility bug with modifying xls files created by POI-3.6 and earlier</action> + <action type="add" fixes-bug="53979" context="HSLF">Support fetching properties of Numbered Lists from PPT files</action> + <action type="add" fixes-bug="53784" context="HSMF">Partial HSMF support for fixed sized properties</action> + <action type="add" fixes-bug="53943" context="HWPF">added method processSymbol() to allow converting word symbols </action> + <action type="fix" fixes-bug="53763" context="HSSF">avoid style mess when using HSSFOptimiser </action> + <action type="fix" fixes-bug="52972" context="SXSSF">preserve leading / trailing spaces in SXSSF </action> + <action type="fix" fixes-bug="53965" context="XSSF">Fixed XmlValueOutOfRangeException calling getDataValidations for custom validations with XSSFSheet </action> + <action type="fix" fixes-bug="53974" context="HSSF">Avoid NPE when constructing HSSFWorkbook on Google App Engine</action> + <action type="fix" fixes-bug="53568" context="XSSF">Fixed null returned by XSSFPicture.getPictureData()</action> + <action type="fix" fixes-bug="53950" context="XSSF">fixed setForceFormulaRecalculation to reset workbook-level "manual" flag</action> + <action type="fix" fixes-bug="52211" context="XSSF">avoid unnecessary re-converting content types to US-ASCII, it can cause exceptions on ibm mainframes</action> + <action type="fix" fixes-bug="53568" context="XSSF">Set shapes anchors in XSSF when reading from existing drawings</action> + <action type="add" context="HSSF">HSSFOptimiser will now also tidy away un-used cell styles, in addition to duplicate styles</action> + <action type="fix" fixes-bug="53493" context="SXSSF">Fixed memory and temporary file leak in SXSSF </action> + <action type="fix" fixes-bug="53780" context="SXSSF">Fixed memory and temporary file leak in SXSSF </action> + <action type="fix" fixes-bug="53380" context="HWPF">ArrayIndexOutOfBounds Exception parsing word 97 document. </action> + <action type="fix" fixes-bug="53434" context="POI_Overall">Subtotal is not return correct value. </action> + <action type="fix" fixes-bug="53642" context="POI_Overall">XLS formula evaluation logging </action> + <action type="fix" fixes-bug="53561" context="HSSF">Unexpected adding of drawings into a workbook </action> + <action type="fix" fixes-bug="53413" context="HSSF">[GSoC] Improved work with shapes. HSSF </action> + <action type="fix" fixes-bug="53361" context="HSSF">feature: enhancements in EscherAggregate </action> + <action type="fix" fixes-bug="53302" context="HSSF">EscherAggregate does not handle Continue records </action> + <action type="fix" fixes-bug="53144" context="HSSF">First comment not cloned after cloneSheet() </action> + <action type="fix" fixes-bug="53028" context="HSSF">Broken auto fit row height in the cells with word wrap </action> + <action type="fix" fixes-bug="53010" context="HSSF">[GSoC2012] Improve drawing support in HSSF </action> + <action type="fix" fixes-bug="52764" context="HSSF">Unmodified cell comments disappear after HSSFWorkbook.write </action> + <action type="fix" fixes-bug="52300" context="HSSF">Corrupted File after cloneSheet() </action> + <action type="fix" fixes-bug="52272" context="HSSF">Inserting images on cloned sheet with images. </action> + <action type="fix" fixes-bug="51796" context="HSSF">The [EscherClientAnchorRecord] for object (eg: TextBox,Shape) may get lost. </action> + <action type="fix" fixes-bug="51683" context="HSSF">[HSSF] Improve support for Shapes and Shape Groups </action> + <action type="fix" fixes-bug="51676" context="HSSF">Using drawingPatriarch.createCellComment(anchor) leads to File error: data may have been lost </action> + <action type="fix" fixes-bug="51675" context="HSSF">Background images cause problems in HSSF spreadsheet </action> + <action type="fix" fixes-bug="51455" context="HSSF">It would be really nice to be able to set the background picture of a comment </action> + <action type="fix" fixes-bug="51341" context="HSSF">Adding Image to Header in Excel Using HSSF </action> + <action type="fix" fixes-bug="51280" context="HSSF">when we insert a new image to the existing excel file that corrupts the previous images </action> + <action type="fix" fixes-bug="50696" context="HSSF">File Error: data may have been lost </action> + <action type="fix" fixes-bug="48989" context="HSSF">If we have a comment but the row is not created we will not be able to get it. </action> + <action type="fix" fixes-bug="48873" context="HSSF">Comments not saving in XLS files with collapsible columns </action> + <action type="fix" fixes-bug="48654" context="HSSF">Not able to read Excel (xls) file having drawing objects </action> + <action type="fix" fixes-bug="48590" context="HSSF">Excel crashes after using removeCellComment methods </action> + <action type="fix" fixes-bug="46444" context="HSSF">cloning cloned sheet with autofilters corrupts the workbook </action> + <action type="fix" fixes-bug="45129" context="HSSF">Lost picture in file output after saving with POI </action> + <action type="fix" fixes-bug="47624" context="HSSF">File Error Data May Have been Lost error while opening commented workbook(excel file) </action> + <action type="fix" fixes-bug="46143" context="HSSF">setLineStyleColor for comments do not work </action> + <action type="fix" fixes-bug="53699" context="XSSF">Patch to correct BorderStyle enum positions </action> + <action type="add" fixes-bug="53604" context="HSSF">Ugly Duckling case study</action> + <action type="add" fixes-bug="53644" context="HSSF">XLS formula bugfix (CalFieldFunc) + WeekDay addon </action> + <action type="add" fixes-bug="53446" context="POI_Overall">Fixed some problems extracting PNGs </action> + <action type="fix" fixes-bug="53205" context="HDGF">Fixed some parsing errors and encoding issues in HDGF </action> + <action type="add" fixes-bug="53204" context="HSSF">Improved performance of PageSettingsBlock in HSSF </action> + <action type="add" fixes-bug="53500" context="POI_Overall">Getter for repeating rows and columns</action> + <action type="fix" fixes-bug="53369" context="XSSF">Fixed tests failing on JDK 1.7</action> + <action type="fix" fixes-bug="53360" context="SXSSF">Fixed SXSSF to correctly write text before escaped Unicode control character</action> + <action type="add" context="HSMF">Change HSMF Types to have full data on ID, Name and Length, rather than just being a simple ID</action> + <action type="add" fixes-bug="48469" context="HSSF">Updated case study</action> + <action type="add" fixes-bug="53476" context="HSSF">Support Complex Name in formulas </action> + <action type="fix" fixes-bug="53414" context="HSSF">properly update sheet dimensions when adding column </action> + <action type="add" context="OPC">Add File based constructor to OPCPackage, alongside existing String one (which constructed a File from the string internally)</action> + <action type="fix" fixes-bug="53389" context="POI_Overall">Handle formatting General and @ formats even if a locale is prefixed to them</action> + <action type="fix" fixes-bug="53271" context="SXSSF">Removed unconditional asserts in SXSSF</action> + <action type="add" fixes-bug="53025" context="XSSF">Updated documentation and example on using Data Validations </action> + <action type="add" fixes-bug="53227" context="XSSF">Corrected AddDimensionedImage.java to support XSSF/SXSSF </action> + <action type="add" fixes-bug="53058" context="HSSF">Utility for representing drawings contained in a binary Excel file as a XML tree</action> + <action type="add" fixes-bug="53165" context="HWPF">HWPF support for fetching the description (alt text) of a picture</action> + <action type="fix" fixes-bug="48528" context="XSSF">support negative arguments to the DATE() function</action> + <action type="fix" fixes-bug="53092" context="POI_Overall">allow specifying of a TimeZone to DateUtil.getJavaDate(), for when it is known that a file comes from a different (known) timezone to the current machine</action> + <action type="fix" fixes-bug="53043" context="XSSF">don't duplicate hyperlink relationships when saving XSSF file</action> + <action type="fix" fixes-bug="53101" context="XSSF">fixed evaluation of SUM over cell range > 255</action> + <action type="fix" fixes-bug="49529" context="HSSF">avoid exception when cloning sheets with no drawing records and initialized drawing patriarch</action> + </actions> + </release> + + <release version="3.8-FINAL" date="2012-03-26"> + <summary> +<!-- FIXME: formatting --> +<!-- Significant changes --> + <summary-item>NPOIFS: NIO driven API to read OLE2 filesystems with low memory footprint.</summary-item> + <summary-item>SXSSF: a low-memory footprint API built on top of XSSF that can be used when very large spreadsheets have to be produced, and heap space is limited</summary-item> + <summary-item>poi-excelant: Ant tasks for running POI against a workbook</summary-item> + <summary-item>Supported evaluation of new Excel formulas: IRR,NPV,MROUND,VAR,VARP,CLEAN,CHAR,ADDRESS,HOUR,MINUTE,SECOND,RATE,WORKDAY,NETWORKDAYS,SUMIFS,RANK</summary-item> + <summary-item>XSLF usermodel API: POI's implementation of the PowerPoint 2007 OOXML (.xlsx) file format. XSLF provides a rich usermodel API and a PPTX2PNG utility to export slides to images.</summary-item> + <summary-item>WordToFO, WordToHtml and WordToText converters: utilities to export MS Word .doc files into XSL-FO, html and text files. Output from WordToFO can be used to convert .doc files to pdf using Apache FOP.</summary-item> + +<!-- Other notable changes:--> + <summary-item>Numerous improvements and refactorings in HWPF, Java API for MS Word .doc files: support for reading + footnotes, endnotes and bookmarks, improved support for handling tables, paragraphs, text runs and much more...</summary-item> + <summary-item>Initial support for charts in XSSF</summary-item> + <summary-item>support for OOXML Agile Encryption</summary-item> + </summary> + <actions> + <action type="add" fixes-bug="52928" context="POI_Overall">DateFormatConverter: an utility to convert instances of java.text.DateFormat to Excel format patterns</action> + <action type="fix" fixes-bug="52895" context="HSSF">show SSTIndex instead of XFIndex in LabelSSTRecord.toString()</action> + <action type="fix" fixes-bug="52835" context="XSSF">Tolerate missing Count and UniqueCount attributes when parsing shared strings table in XSSF eventusermodel</action> + <action type="add" fixes-bug="52818" context="HSSF">Added implementation for RANK()</action> + <action type="fix" fixes-bug="52682" context="HSLF">allow setting text with trailing carriage return in HSLF</action> + <action type="fix" fixes-bug="52244" context="HSLF">use correct text attributes when presentation has multiple TxMasterStyleAtoms of the same type</action> + <action type="add" context="XSSF">support setting background color of sheet tab in XSSF</action> + <action type="add" fixes-bug="51564" context="XWPF">support for enforcing fields update in XWPF</action> + <action type="add" fixes-bug="51673" context="SXSSF">support grouping rows in SXSSF</action> + <action type="add" fixes-bug="51780" context="POI_Overall">support replacement of content types in OPC packages </action> + <action type="fix" fixes-bug="52784" context="SXSSF">replace ISO control characters with question marks in SXSSF to be consistent with XSSF </action> + <action type="add" fixes-bug="52057" context="HSSF">updated formula test framework to be aware of recently added Functions </action> + <action type="add" fixes-bug="52574" context="HSSF">support setting header / footer page margins in HSSF </action> + <action type="add" fixes-bug="52583" context="HWPF">fixed WorkbookUtil#createSafeSheetName to escape colon </action> + <action type="add" fixes-bug="51710" context="XSSF">fixed reading shared formulas in XSSF </action> + <action type="add" fixes-bug="52708" context="POI_Overall">misc improvements in CellFormat </action> + <action type="add" fixes-bug="52690" context="POIFS">added a getter for length of encrypted data in Ecma and Agile decryptors</action> + <action type="fix" fixes-bug="52255" context="XWPF">support adding TIFF,EPS and WPG pictures in OOXML documents </action> + <action type="fix" fixes-bug="52078" context="HSLF">avoid OutOfMemoryError when rendering grouped pictures in HSLF </action> + <action type="fix" fixes-bug="52745" context="XSSF">fixed XSSFRichtextString.append to preserve leading / trailing spaces </action> + <action type="fix" fixes-bug="52716" context="XSSF">tolerate hyperlinks that have neither location nor relation </action> + <action type="fix" fixes-bug="52599" context="HSLF">avoid duplicate text when rendering slides in HSLF</action> + <action type="fix" fixes-bug="52598" context="HSLF">respect slide background when rendering slides in HSLF</action> + <action type="fix" fixes-bug="51731" context="HSLF">fixed painting shape outlines in HSLF</action> + <action type="fix" fixes-bug="52701" context="XSLF">fixed setting vertical alignment for XSLFTableCell</action> + <action type="fix" fixes-bug="52687" context="XSLF">fixed merging slides with pictures with associated custom tags</action> + <action type="add" context="SS_Common"> allow runtime registration of functions in FormulaEvaluator</action> + <action type="fix" fixes-bug="52665" context="POI_Overall">When reading from a ZipFileZipEntrySource that has already been closed, give IllegalArgumentException rather than NPE</action> + <action type="fix" fixes-bug="52664" context="HSMF">MAPIMessage may not always have name chunks when checking for 7 bit encodings</action> + <action type="fix" fixes-bug="52649" context="HWPF">fixed namespace issue in WordToFoConverter</action> + <action type="fix" fixes-bug="52385" context="HPSF">avoid truncated array and vector data when reading OLE properties</action> + <action type="fix" fixes-bug="52662" context="HWPF">CharacterRun NPE fix when fetching symbol fonts, where no fonts are defined</action> + <action type="add" fixes-bug="52658" context="XSLF">support merging table cells in XSLF</action> + <action type="add" context="SXSSF">validate row number and column index in SXSSF when creating new rows / cells</action> + <action type="fix" fixes-bug="51498" context="POI_Overall">fixed evaluation of blank cells in COUNTIF</action> + <action type="add" fixes-bug="52576" context="HSSF">support changing external file references in HSSFWorkbook</action> + <action type="add" fixes-bug="49896" context="POI_Overall">support external references in FormulaRenderer</action> + <action type="fix" fixes-bug="52527" context="HSSF">avoid exception when matching shared formula records in HSSF</action> + <action type="add" fixes-bug="52568" context="XWPF">Added methods to set/get an XWPFRun's text color</action> + <action type="add" fixes-bug="52566" context="XWPF">Added methods to set/get vertical alignment and color in XWPFTableCell</action> + <action type="add" fixes-bug="52562" context="XWPF">Added methods to get/set a table row's Can't Split and Repeat Header attributes in XWPF</action> + <action type="add" fixes-bug="52561" context="XWPF">Added methods to set table inside borders and cell margins in XWPF</action> + <action type="add" fixes-bug="52569" context="HSSF">Support DConRefRecord in HSSF</action> + <action type="add" fixes-bug="52575" context="HSSF">added an option to ignore missing workbook references in formula evaluator</action> + <action type="add" context="XSSF">Validate address of hyperlinks in XSSF</action> + <action type="fix" fixes-bug="52540" context="XWPF">Relax the M4.1 constraint on reading OOXML files, as some Office produced ones do have 2 Core Properties, despite the specification explicitly forbidding this</action> + <action type="add" fixes-bug="52462" context="HSSF">Added implementation for SUMIFS()</action> + <action type="add" context="OOXML">POIXMLPropertiesTextExtractor support for extracting custom OOXML properties as text</action> + <action type="fix" fixes-bug="52449" context="XWPF">Support writing XWPF documents with glossaries (Glossaries are not yet supported, but can now be written out again without changes)</action> + <action type="fix" fixes-bug="52446" context="POIFS">Handle files which have been truncated by a few bytes in NPropertyTable</action> + <action type="fix" fixes-bug="52438" context="POI_Overall">Update CellDateFormatter to handle times without seconds</action> + <action type="add" fixes-bug="52389" context="XSSF">Support ?/? as well as #/# fractions, and tighten DataFormatter rules for fraction matching</action> + <action type="add" fixes-bug="52200" context="XWPF">Updated XWPF table example code </action> + <action type="add" fixes-bug="52378" context="HSSF">Support for WORKDAY and NETWORKDAYS functions</action> + <action type="add" fixes-bug="52349" context="XSSF">Merge the logic between the TEXT function and DataFormatter</action> + <action type="fix" fixes-bug="52349" context="XSSF">Correctly support excel style date format strings in the TEXT function</action> + <action type="fix" fixes-bug="52369" context="XSSF">XSSFExcelExtractor should format numeric cells based on the format strings applied to them</action> + <action type="fix" fixes-bug="52369" context="XSSF">Event based XSSF parsing should handle formatting of formula values in XSSFSheetXMLHandler</action> + <action type="fix" fixes-bug="52348" context="XSSF">Avoid exception when creating cell style in a workbook that has an empty xf table</action> + <action type="fix" fixes-bug="52219" context="XSSF">fixed XSSFSimpleShape to set rich text attributes from XSSFRichtextString</action> + <action type="fix" fixes-bug="52314" context="POI_Overall">enhanced SheetUtil.getColumnWidth</action> + </actions> + </release> + + <release version="3.8-beta5" date="2011-12-17"> + <actions> + <action type="fix" fixes-bug="52204" context="XSSF">Deprecated XSSFWorkbook(String path) constructor because it does not close underlying .zip file</action> + <action type="fix" fixes-bug="46288" context="HSLF">fixed refcount of Fill pictures in HSLF </action> + <action type="add" fixes-bug="51961" context="SXSSF">support compression of temp files in SXSSF </action> + <action type="add" fixes-bug="52268" context="XSSF">support cloning sheets with drawings in XSSF </action> + <action type="add" fixes-bug="52285" context="XWPF">Support XWPF smart tags text in Paragraphs</action> + <action type="fix" fixes-bug="51875" context="XSSF">More XSSF new-line in formula support</action> + <action type="add" context="POIFS">POIFS EntryUtils.copyNodes(POFS,POIFS) now uses FilteringDirectoryNode, so can exclude from copying nodes not just directly under the root</action> + <action type="add" context="POIFS">POIFS Helper FilteringDirectoryNode, which wraps a DirectoryEntry and allows certain parts to be ignored</action> + <action type="fix" fixes-bug="52209" context="XSLF">fixed inserting multiple pictures in XSLF </action> + <action type="fix" fixes-bug="51803" context="HSLF">fixed HSLF TextExtractor to extract content from master slide </action> + <action type="fix" fixes-bug="52190" context="XWPF">null check on XWPF setFontFamily</action> + <action type="fix" fixes-bug="52062" context="SXSSF">ensure that temporary files in SXSSF are deleted</action> + <action type="fix" fixes-bug="50936" context="HWPF">Exception parsing MS Word 8.0 file (as duplicate of 47958)</action> + <action type="fix" fixes-bug="47958" context="HWPF">ArrayIndexOutOfBoundsException from PicturesTable.getAllPictures() during Escher tree walk</action> + <action type="fix" fixes-bug="51944" context="HWPF">PAPFormattedDiskPage.getPAPX - IndexOutOfBounds</action> + <action type="fix" fixes-bug="52032" context="HWPF">HWPF - ArrayIndexOutOfBoundsException with no stack trace (broken after revision 1178063)</action> + <action type="add" context="XSLF">support for converting pptx files into images with a PPTX2PNG tool</action> + <action type="add" fixes-bug="52050" context="HSSF">Support for the Excel RATE function</action> + <action type="fix" fixes-bug="51566" context="HSLF">HSLF fix for finishing parsing the picture stream on the first non-valid type</action> + <action type="fix" fixes-bug="51974" context="HWPF">Avoid HWPF issue when identifying the picture type</action> + <action type="fix" fixes-bug="52035" context="HWPF">Fix signed issue with very large word 6 files</action> + <action type="fix" fixes-bug="51949" context="POI_Overall">Avoid NPE on double close of ZipFileZipEntrySource</action> + <action type="fix" fixes-bug="51950" context="XWPF">XWPF fix for footnotes not always being present in a document</action> + <action type="fix" fixes-bug="51963" context="POI_Overall">Correct AreaReference handling of references containing a sheet name which includes a comma</action> + <action type="fix" fixes-bug="51955" context="XSSF">XSSFReader supplied StylesTables need to have the theme data available</action> + <action type="fix" fixes-bug="51716" context="SXSSF">Removed incorrect assert in SXSSFSheet#getSXSSFSheet</action> + <action type="fix" fixes-bug="51834" context="HWPF">Opening and Writing .doc file results in corrupt document</action> + <action type="fix" fixes-bug="51902" context="HWPF">Picture.fillRawImageContent - ArrayIndexOutOfBoundsException (duplicate)</action> + <action type="fix" fixes-bug="51890" context="HWPF">ArrayIndexOutOfBounds ExceptionPicture.fillRawImageContent</action> + <action type="add" context="SS_Common">Allow the passing of a File object to WorkbookFactory.create, which permits lower memory processing than the InputStream version</action> + <action type="fix" fixes-bug="51873" context="HSMF">update HSMF to ignore Outlook 2002 Olk10SideProp entries, which don't behave like normal chunks</action> + <action type="fix" fixes-bug="51850" context="XSSF">support creating comments in XSSF on an earlier slide when later ones already have them</action> + <action type="add" fixes-bug="51804" context="XSLF">optionally include Master Slide text in XSLF text extraction, as HSLF already offers</action> + <action type="add" context="OPC">New PackagePart method getRelatedPart(PackageRelationship) to simplify navigation of relations between OPC Parts</action> + <action type="fix" fixes-bug="51832" context="HSSF">handle XLS files where the WRITEPROTECT record precedes the FILEPASS one, rather than following as normal</action> + <action type="fix" fixes-bug="51809" context="HSSF">correct GTE handling in COUNTIF</action> + <action type="add" context="HWPF">Add HWPF API to update range text and delete bookmarks</action> + <action type="add" context="HWPF">HWPF Bookmarks tables are correctly updated on text updates</action> + <action type="add" fixes-bug="51670" context="POI_Overall">avoid LeftoverDataException when reading .xls files with invalid LabelRecords</action> + <action type="add" fixes-bug="51196" context="XSSF">prevent NPE in XWPFPicture.getPictureData() </action> + <action type="add" fixes-bug="51771" context="HSLF">prevent NPE when getting object data from OLEShape in HSLF</action> + <action type="add" fixes-bug="51196" context="XSSF">more progress with Chart APi in XSSF</action> + <action type="fix" fixes-bug="51785" context="XSSF">Allow XSSF setForceFormulaRecalculation to work with the minimal ooxml-schemas jar</action> + <action type="fix" fixes-bug="51772" context="HWPF">IllegalArgumentException Parsing MS Word 97 - 2003</action> + <action type="add" context="XSLF">XSLFPowerPointExtractor support for including comment authors with comment text</action> + <action type="fix" context="XSLF">Converted XSLFPowerPointExtractor to use UserModel for all text extraction</action> + <action type="add" context="XSLF">XSLF initial UserModel support for Notes and Comments for Slides</action> + <action type="add" context="HSLF">support for uncompressed OLE embeddings</action> + </actions> + </release> + + <release version="3.8-beta4" date="2011-08-26"> + <actions> + <action type="fix" fixes-bug="51678" context="HWPF">Extracting text from Bug51524.zip is slow</action> + <action type="fix" fixes-bug="51671" context="HWPF">HWPFDocument.write based on NPOIFSFileSystem throws a NullPointerException</action> + <action type="add" context="XSLF">support for tables and hyperlinks in XSLF</action> + <action type="fix" fixes-bug="51535" context="HSSF">correct signed vs unsigned short reading in NDocumentInputStream</action> + <action type="add" fixes-bug="51634" context="SXSSF">support SXSSF streaming from templates</action> + <action type="add" context="XSLF">initial support for XSLF usermodel API</action> + <action type="fix" fixes-bug="51187" context="XSLF">fixed OPCPackage to correctly handle self references</action> + <action type="fix" fixes-bug="51635" context="XSSF">Improved performance of XSSFSheet#write</action> + <action type="fix" fixes-bug="47731" context="HWPF">Word Extractor considers text copied from some website as an embedded object</action> + <action type="add" context="HWPF">Add Word-to-Text converter and use it as replacement for WordExtractor</action> + <action type="fix" fixes-bug="51604" context="HWPF">replace text fails for doc ( poi 3.8 beta release from download site )</action> + <action type="fix" context="SXSSF">Fixed incorrect encoding of non-breaking space (0xA0) in SXSSF</action> + <action type="add" context="XSSF">Support for conditional formatting in XSSF</action> + <action type="add" context="HSSF">Support isRightToLeft and setRightToLeft on the common spreadsheet Sheet interface, as per existing HSSF support</action> + <action type="fix" fixes-bug="50209" context="HSSF">Fixed evaluation of Subtotals to ignore nested subtotals</action> + <action type="fix" fixes-bug="44431" context="HWPF">HWPFDocument.write destroys fields</action> + <action type="fix" fixes-bug="50401" context="HSLF">fixed EscherProperty to return property name instead of 'unknown' for complex properties </action> + <action type="add" context="HWPF">Initial support for endnotes and footnotes in HWPF</action> + <action type="fix" fixes-bug="51470" context="XSSF">avoid exception when cloning XSSF sheets with background images</action> + <action type="fix" fixes-bug="51481" context="HSSF">Fixed autofilters in HSSF to avoid warnings in Excel 2007</action> + <action type="fix" fixes-bug="51533" context="XSSF">Avoid exception when changing name of a sheet containing shared formulas</action> + <action type="add" context="HSSF">Support for appending images to existing drawings in HSSF</action> + <action type="add" context="HWPF">Initial support for bookmarks in HWPF</action> + <action type="fix" fixes-bug="46250" context="HSSF">Fixed cloning worksheets with images</action> + <action type="fix" fixes-bug="51524" context="HWPF">PapBinTable constructor is slow (regression)</action> + <action type="fix" fixes-bug="51514" context="HSSF">allow HSSFObjectData to work with both POIFS and NPOIFS</action> + <action type="fix" fixes-bug="51514" context="HSSF">avoid NPE when copying nodes from one HSSF workbook to a new one, when opened from NPOIFS</action> + <action type="fix" fixes-bug="51504" context="HSSF">avoid NPE when DefaultRowHeight or DefaultColumnWidth records are missing</action> + <action type="fix" fixes-bug="51502" context="POI_Overall">Correct Subtotal function javadoc entry</action> + <action type="add" context="SXSSF">Support for hyperlinks in SXSSF</action> + <action type="fix" fixes-bug="49933" context="HWPF">Word 6/95 documents with sections cause ArrayIndexOutOfBoundsException</action> + <action type="add" fixes-bug="51469" context="XSSF">XSSF support for row styles, to match existing HSSF functionality</action> + <action type="fix" fixes-bug="51476" context="XSSF">Correct XSSF cell formatting in HTML export</action> + <action type="add" fixes-bug="51486" context="XWPF">XWPF support for adding new footnotes</action> + <action type="fix" fixes-bug="48065" context="HWPF">Problems with save output of HWPF (losing formatting)</action> + <action type="fix" fixes-bug="47563" context="HWPF">Exception when working with table</action> + <action type="fix" fixes-bug="47287" context="HWPF">StringIndexOutOfBoundsException in CharacterRun.replaceText()</action> + <action type="fix" fixes-bug="46817" context="HWPF">Regression: Text from some table cells missing</action> + <action type="add" context="HWPF">Add getOverallRange() method to HWPFDocumentCore</action> + <action type="fix" context="HWPF">PAPX referenced outside of TextPiecesTable are ignored now and not loaded</action> + <action type="fix" context="HWPF">Fix main part range (and section) detection for files with additional parts (like footers/headers)</action> + <action type="fix" context="HWPF">Fix wrong TextPiece parsing in very rare cases like Bug33519.doc</action> + <action type="fix" context="HWPF">Inner tables are correctly supported</action> + <action type="add" context="HWPF">Allow user to retrieve Table nesting level (based on file information)</action> + <action type="add" context="HWPF">Functionality of internal tool HWPFLister is greatly improved, including output of document PAPX and paragraphs</action> + <action type="add" context="HWPF">Expand Word structures definitions (TAP, PAP, TLP, etc) based on official documentation</action> + <action type="add" context="HWPF">Add Excel-to-HTML converter (2007 versions)</action> + <action type="add" context="HWPF">Add Word-to-HTML converter (95-2007 versions)</action> + <action type="fix" context="HWPF">Skip wrong-type SPRMs when characters SPRM is expected</action> + <action type="add" context="HWPF">Add toStrings() methods to internal HWPF structures: BorderCode, PAPX, Paragraph, PieceDescriptor, Section, SEPX, SprmOperation, TextPiece etc</action> + <action type="fix" fixes-bug="51474" context="SXSSF">SXSSF handling for null strings</action> + <action type="fix" fixes-bug="48294" context="HSSF">Fixed HSSFWorkbook.setSheetOrder() to respect inter-sheet references </action> + <action type="fix" fixes-bug="51448" context="POI_Overall">Avoid exception when evaluating workbooks with more than 256 sheets </action> + <action type="fix" fixes-bug="51458" context="POI_Overall">Correct BitField wrapping when setting large values</action> + <action type="add" fixes-bug="51460" context="HSSF">Improve HSSF performance when loading very long rows, by switching the CellValue array to an iterator</action> + <action type="fix" fixes-bug="51444" context="XSSF">Prevent corrupted output when saving files created by LibreOffice 3.3 </action> + <action type="add" fixes-bug="51422" context="HSSF">Support using RecalcIdRecord to trigger a full formula recalculation on load </action> + <action type="add" fixes-bug="50474" context="XWPF">Example demonstrating how to update Excel workbook embedded in a WordprocessingML document </action> + <action type="fix" fixes-bug="51431" context="XSSF">Avoid IndexOutOfBoundException when removing freeze panes in XSSF </action> + <action type="fix" fixes-bug="48877" context="XSSF">Fixed XSSFRichTextString to respect leading and trailing line breaks </action> + <action type="fix" fixes-bug="49564" context="XSSF">Fixed default behaviour of XSSFCellStyle.getLocked() </action> + <action type="fix" fixes-bug="48314" context="XSSF">Fixed setting column and row breaks in XSSF</action> + <action type="add" fixes-bug="51424" context="HWPF">Ignore exceptions in ParagraphSprmUncompressor</action> + <action type="fix" fixes-bug="51415" context="XSSF">Fixed Workbook.createSheet(sheetName) to truncate names longer than 31 characters</action> + <action type="fix" fixes-bug="51332" context="HSSF">Fixed internal IDs of shapes generated by HSSFPatriarch when there are more than 1023 drawing objects </action> + <action type="fix" fixes-bug="48408" context="HSSF">Improved documentation for Sheet.setColumnWidth </action> + <action type="add" fixes-bug="51390" context="HWPF">Added handling of additional properties to HWPF ParagraphSprmCompressor</action> + <action type="add" fixes-bug="51389" context="HWPF">Support for sprmPJc paragraph SPRM in HWPF</action> + <action type="fix" fixes-bug="48469" context="HSSF">New Case Study for POI web site </action> + <action type="fix" fixes-bug="50681" context="XSSF">Avoid exceptions in HSSFDataFormat.getDataFormatString() </action> + <action type="fix" fixes-bug="50681" context="XSSF">Fixed autosizing columns beyond 255 character limit </action> + <action type="fix" fixes-bug="51374" context="XSSF">Fixed incorrect setting of lastPrinted OOXML core property </action> + <action type="add" fixes-bug="51351" context="HWPF">Word to XSL-FO converter</action> + <action type="fix" fixes-bug="50458" context="XSSF">Fixed missing shapeId in XSSF drawings </action> + <action type="fix" fixes-bug="51339" context="XSSF">Fixed arithmetic rounding in formula evaluation </action> + <action type="add" fixes-bug="51356" context="SXSSF">Support autoSizeColumn in SXSSF</action> + <action type="add" fixes-bug="51335" context="HWPF">Parse picture goal and crop sizes in HWPF</action> + <action type="add" fixes-bug="51305" context="HWPF">Add sprmTCellPaddingDefault support in HWPF</action> + <action type="add" fixes-bug="51265" context="XWPF">Enhanced Handling of Picture Parts in XWPF</action> + <action type="add" fixes-bug="51292" context="HDF">Additional HWPF Table Cell Descriptor values</action> + </actions> + </release> + + <release version="3.8-beta3" date="2011-06-06"> + <actions> + <action type="fix" fixes-bug="51098" context="XSSF">Correctly calculate image width/height, if image fits into one cell</action> + <action type="fix" fixes-bug="47147" context="XWPF">Correct extra paragraphs from XWPF Table Cells</action> + <action type="add" fixes-bug="51188" context="XWPF">Support for getting and setting XWPF zoom settings</action> + <action type="add" fixes-bug="51134" context="XWPF">Support for adding Numbering and Styles to a XWPF document that doesn't already have them</action> + <action type="fix" fixes-bug="51273" context="HSSF">Formula Value Cache fix for repeated evaluations</action> + <action type="add" fixes-bug="51171" context="HSSF">Improved performance of SharedValueManager </action> + <action type="fix" fixes-bug="51236" context="XSSF">XSSF set colour support for black/white to match getter</action> + <action type="add" fixes-bug="51196" context="XSSF">Initial support for Spreadsheet Chart API</action> + <action type="add" context="OPC">Add support for OOXML Agile Encryption</action> + <action type="add" fixes-bug="51160" context="XSSF">Initial version of SXSSF, a low memory footprint API to produce xlsx files</action> + <action type="fix" fixes-bug="51171" context="HSSF">Improved performance of opening large .xls files</action> + <action type="add" fixes-bug="51172" context="XWPF">Add XWPF support for GIF pictures</action> + <action type="add" context="POIFS">NPOIFS Mini Streams now support extending the underlying big block stream to fit more data</action> + <action type="fix" fixes-bug="51148" context="XWPF">XWPFDocument now properly tracks paragraphs and tables when adding/removing them</action> + <action type="fix" fixes-bug="51153" context="HSSF">Correct sizing of LbsDataSubRecord with unused padding fields</action> + <action type="fix" fixes-bug="51143" context="HSSF">NameCommentRecord correction for writing non ASCII strings</action> + <action type="fix" fixes-bug="51112" context="XWPF">Correct XWPFTable tracking of new rows</action> + <action type="fix" fixes-bug="51113" context="XWPF">Correct XWPFParagraph tracking of inserted runs</action> + <action type="fix" fixes-bug="51111" context="XWPF">Correct XWPFParagraph tracking of new runs</action> + <action type="fix" fixes-bug="51115" context="POI_Overall">Handle DataFormatter escaping of "." in the same way as "-" and "/"</action> + <action type="fix" fixes-bug="51100" context="POIFS">Fix IOUtils issue for NPOIFS reading from an InputStream where every block is full</action> + <action type="fix" fixes-bug="50956" context="XSSF">Correct XSSF cell style cloning between workbooks</action> + <action type="add" context="XSSF">Add get/setForceFormulaRecalculation for XSSF, and promote the methods to the common usermodel Sheet</action> + <action type="fix" context="HSSF">Tweak the logic for sizing the HSSFCells array on a HSSFRow to reduce memory over allocation in many use cases</action> + <action type="add" fixes-bug="49765" context="XWPF">Support for adding a picture to a XSSFRun</action> + <action type="fix" context="XSSF">Rename/Move xssf.model.Table to xssf.usermodel.XSSFTable as it now has usermodel-like features</action> + <action type="fix" fixes-bug="51061" context="XSSF">Correct target URI for new XSSF Tables</action> + <action type="add" context="XSSF">Initial support for XSSF Charts. Provides easy access to the underlying CTChart object via the Sheet Drawing, but no high level interface onto the chart contents as yet</action> + <action type="fix" fixes-bug="50884" context="XSSF">XSSF and HSSF freeze panes now behave the same</action> + <action type="add" context="XSSF">Support for adding a table to a XSSFSheet</action> + <action type="add" context="HSMF">Improve HSMF MAPIMessage access to the HTML and RTF versions of the message body (where available)</action> + <action type="add" context="HSMF">Add new method to HSMF of MAPIMessage.has7BitEncodingStrings() to make it easier to decide when encoding guessing is needed</action> + <action type="fix" context="HSMF">OutlookTextExtractor now requests 7 bit encoding guessing</action> + <action type="add" context="HSMF">Improve HSMF encoding guessing for 7 bit fields in MAPIMessage</action> + <action type="add" context="HSMF">Allow HSMF access to the HTML body contents in MAPIMessage</action> + </actions> + </release> + + <release version="3.8-beta2" date="2011-04-08"> + <actions> + <action type="add" context="OPC">Implement the load method on MemoryPackagePart</action> + <action type="add" fixes-bug="50967" context="HSSF">Support for continued ExtSSTRecords</action> + <action type="add" fixes-bug="48968" context="HSSF">Support for HOUR, MINUTE and SECOND date formulas</action> + <action type="add" context="POIFS">Added NPOIFS constructors to most POIDocument classes and their extractors, and more widely deprecated the Document(DirectoryNode, POIFSFileSystem) constructor in favour of the more general Document(DirectoryNode) one</action> + <action type="fix" context="POIFS">Fixed NPOIFS handling of new and empty Document Nodes</action> + <action type="fix" context="POIFS">Fixed NPOIFS access to Document Nodes not in the top level directory</action> + <action type="fix" fixes-bug="50841" context="POI_Overall">Improved SpreadSheet DataFormatter to handle scientific notation, invalid dates and format spacers</action> + <action type="fix" fixes-bug="49381" context="HSSF">Correct createFreezePane in XSSF, so that the left row/column matches the documentation + HSSF</action> + <action type="fix" fixes-bug="49253" context="XSSF">When setting repeating rows and columns for XSSF, don't break the print settings if they were already there</action> + <action type="fix" fixes-bug="49219" context="HSSF">ExternalNameRecord support for DDE Link entries without an operation</action> + <action type="fix" fixes-bug="50846" context="XSSF">More XSSFColor theme improvements, this time for Cell Borders</action> + <action type="fix" fixes-bug="50939" context="HSSF">ChartEndObjectRecord is supposed to have 6 bytes at the end, but handle it not</action> + <action type="add" context="HMEF">HMEF - New component which supports TNEF (Transport Neutral Encoding Format), aka winmail.dat</action> + <action type="fix" fixes-bug="50313" context="HWPF">support for getting HWPFDocument fields</action> + <action type="fix" fixes-bug="50912" context="HSSF">fixed setting named styles to HSSFCells</action> + <action type="fix" fixes-bug="50779" context="HSSF">fixed RecordFormatException when reading unicode strings with photenic data</action> + <action type="fix" fixes-bug="50718" context="POI_Overall">More helpful error message when you try to create a CellReference with #REF!</action> + <action type="fix" fixes-bug="50784" context="XSSF">XSSFColors return by XSSFFont now have theme information applied to them</action> + <action type="fix" fixes-bug="50846" context="XSSF">Improve how XSSFColor inherits from Themes</action> + <action type="fix" fixes-bug="50847" context="XSSF">XSSFFont now accepts the full range of Charsets from FontChartset</action> + <action type="fix" fixes-bug="50786" context="XSSF">Speed up calls to HSSFColor.getIndexHash() by returning a cached, unmodifiable Map. HSSFColor.getModifiableIndexHash() provides access to the old (slow but modifiable) functionality</action> + <action type="fix" fixes-bug="47100" context="XSSF">Change related formulas and named ranges when XSSFWorkbook.setSheetName is called</action> + </actions> + </release> + + <release version="3.8-beta1" date="2011-03-07"> + <actions> + <action type="add" fixes-bug="50610" context="HSSF">Ant tasks for running POI against a workbook</action> + <action type="add" fixes-bug="32903" context="POIFS">Correct XBAT chaining explanation in /poifs/fileformat.html</action> + <action type="add" fixes-bug="50829" context="XSSF">Support for getting the tables associated with a XSSFSheet</action> + <action type="fix" fixes-bug="50299" context="XSSF">More XSSFColor updates for ARGB vs RGB</action> + <action type="fix" fixes-bug="50581" context="OOXML">Use stax:stax-api instead of org.apache.geronimo.specs:geronimo-stax-api_1.0_spec</action> + <action type="fix" fixes-bug="50786" context="XSSF">Fix XSSFColor to fetch the RGB values of old-style indexed colours</action> + <action type="fix" fixes-bug="50299" context="XSSF">Fix XSSFColor fetching of white and black background themes</action> + <action type="fix" fixes-bug="50795" context="XSSF">Avoid NPE from xmlbeans when moving XSSF Comments from one cell to another</action> + <action type="fix" fixes-bug="46664" context="HSSF">When creating HSSF Print Areas, ensure the named range is reference based not value based</action> + <action type="fix" fixes-bug="50756" context="POI_Overall">When formatting numbers based on their Cell Style, treat GENERAL the same as the more typical General</action> + <action type="fix" context="HSSF">fixed HSSFWorkbook.createCellStyle to throw exception if the maximum number of cell styles was exceeded</action> + <action type="fix" fixes-bug="50539" context="XSSF">Better fix for html-style br tags (invalid XML) inside XSSF documents</action> + <action type="add" fixes-bug="49928" context="POI_Overall">allow overridden built-in formats in HSSFCellStyle</action> + <action type="add" fixes-bug="50607" context="POI_Overall">Added implementation for CLEAN(), CHAR() and ADDRESS()</action> + <action type="add" fixes-bug="50587" context="HSSF">Improved documentation on user-defined functions</action> + <action type="add" context="OOXML">Inside ExtractorFactory, support finding embedded OOXML documents and providing extractors for them</action> + <action type="add" context="HDGF">Partial HDGF LZW compression support</action> + <action type="add" fixes-bug="50244" context="HSSF">Support for continued NameRecords</action> + <action type="fix" fixes-bug="50416" context="HSSF">Correct shifting of the first or last row in a sheet by multiple rows</action> + <action type="fix" fixes-bug="50440" context="XSSF">Support evaluating formulas with newlines in them, which XSSF may have (but HSSF may not)</action> + <action type="add" context="XSSF">Added inline string support to XSSF EventModel</action> + <action type="fix" fixes-bug="50246" context="HSSF">Properly position GutsRecord when reading HSSF workbooks</action> + <action type="add" fixes-bug="48539" context="XSSF">Added implementation for MROUND(), VAR() and VARP()</action> + <action type="add" fixes-bug="50446" context="POI_Overall">Code cleanup and optimizations to keep some IDE quiet</action> + <action type="add" fixes-bug="50437" context="POI_Overall">Support passing ranges to NPV()</action> + <action type="add" fixes-bug="50409" context="XSSF">Added implementation for IRR()</action> + <action type="add" fixes-bug="47405" context="HSSF">Improved performance of RowRecordsAggregate.getStartRowNumberForBlock / getEndRowNumberForBlock</action> + <action type="fix" fixes-bug="50315" context="XSSF">Avoid crashing Excel when sorting XSSFSheet autofilter</action> + <action type="add" fixes-bug="50076" context="XSSF">Allow access from XSSFReader to sheet comments and headers/footers</action> + <action type="add" fixes-bug="50076" context="XSSF">Refactor XSSFEventBasedExcelExtractor to make it easier for you to have control over outputting the cell contents</action> + <action type="fix" fixes-bug="50258" context="XSSF">avoid corruption of XSSFWorkbook after applying XSSFRichTextRun#applyFont</action> + <action type="fix" fixes-bug="50154" context="POIFS">Allow white spaces and unicode in OPC relationship targets </action> + <action type="fix" fixes-bug="50113" context="XSSF">Remove cell from Calculation Chain after setting cell type to blank </action> + <action type="fix" fixes-bug="49966" context="XSSF">Ensure that XSSFRow#removeCell clears calculation chain entries </action> + <action type="fix" fixes-bug="50096" context="XSSF">Fixed evaluation of cell references with column index greater than 255 </action> + <action type="fix" fixes-bug="49761" context="HSSF">Tolerate Double.NaN when reading .xls files</action> + <action type="fix" fixes-bug="50211" context="HSSF">Use cached formula result when auto-sizing formula cells</action> + <action type="fix" fixes-bug="50118" context="POIFS">OLE2 does allow a directory with an empty name, so support this in POIFS</action> + <action type="fix" fixes-bug="50119" context="XSSF">avoid NPE when XSSFReader comes across chart sheets</action> + </actions> + </release> + + <release version="3.7" date="2010-10-29"> + <summary> +<summary-item>OOXML</summary-item> +<summary-item>support for reading aes-encrypted/write-protected ooxml files</summary-item> +<summary-item>support Java 1.5 in auto-generated xmlbeans for ooxml schemas</summary-item> +<summary-item></summary-item> + +<summary-item>Spreadsheet (Excel)</summary-item> +<summary-item>initial support for autofilters</summary-item> +<summary-item>support for data validation for ooxml format</summary-item> +<summary-item>initial support for themes for ooxml format</summary-item> +<summary-item>added implementation for new functions: RANDBETWEEN, POISSON, SUBTOTAL, TEXT, TRUNC</summary-item> +<summary-item>support evaluation of indirect defined names in INDIRECT</summary-item> +<summary-item>numerous fixes and performance optimizations in the Formula Evaluation module</summary-item> +<summary-item>ability to add, modify and remove series from HSSF Charts</summary-item> +<summary-item>numerous improvements in the cell data formatter (handling more formatting rules, + better color detection, allow overriding of default locale)</summary-item> +<summary-item>more examples including a rich "spreadsheet to HTML" converter</summary-item> +<summary-item></summary-item> + +<summary-item>Document (Word)</summary-item> +<summary-item>initial support for the HWPF revision marks authors list</summary-item> +<summary-item>support for border codes in HWPF</summary-item> +<summary-item>support for processing of symbols in HWPF</summary-item> +<summary-item>support sections in Word 6 and Word 95 files</summary-item> +<summary-item>improved reading of auto-saved ("complex") documents in HWPF</summary-item> +<summary-item>improved support for manipulation of tables and paragraphs in XWPF</summary-item> +<summary-item></summary-item> + +<summary-item>SlideShow (PowerPoint)</summary-item> +<summary-item>allow editing workbooks embedded into HSLF slide shows</summary-item> +<summary-item></summary-item> + +<summary-item>Text Extraction</summary-item> +<summary-item>support for text extraction from XSLF tables</summary-item> +<summary-item>add PublisherTextExtractor support to extractorfactory</summary-item> +<summary-item>support attachments as embedded documents within the new OutlookTextExtactor</summary-item> +<summary-item>new event based XSSF text extractor (XSSFEventBasedExcelExtractor)</summary-item> +<summary-item>make it easier to tell which content types each POIXMLTextExtractor handles</summary-item> +<summary-item>paragraph level as well as whole-file text extraction for word 6/95 files</summary-item> +<summary-item></summary-item> + +<summary-item>...and much much more: code cleanup, many bug fixes and performance improvements</summary-item> + </summary> + <actions> + <action type="fix" fixes-bug="50075" context="HWPF">avoid NPE in ListLevel.getNumberText() when numberText is null </action> + <action type="fix" fixes-bug="50067" context="POI_Overall">marked commons-logging and log4j as optional dependencies in POI poms</action> + <action type="add" fixes-bug="49928" context="POI_Overall">allow overridden built-in formats in XSSFCellStyle</action> + <action type="fix" fixes-bug="49919" context="HWPF">support for BorderCode in HWPF</action> + <action type="fix" fixes-bug="49908" context="HWPF">support for processing of symbols in HWPF</action> + <action type="fix" fixes-bug="50022" context="HSSF">support for retrieving pictures from HSSF workbooks</action> + <action type="fix" fixes-bug="50020" context="HSSF">Avoid IllegalStateException when creating Data validation in sheet with macro</action> + <action type="fix" fixes-bug="50033" context="XSSF">Improved rounding in MOD</action> + <action type="add" context="POI_Overall">Generate SHA1 hashes of distribution files, alongside existing MD5 ones</action> + </actions> + </release> + + <release version="3.7-beta3" date="2010-09-24"> + <actions> + <action type="fix" fixes-bug="48325" context="HSSF">If a HSSF header or footer lacks left/right/centre information, assume it is a centre one</action> + <action type="fix" fixes-bug="49966" context="XSSF">Correctly remove calcChain entries for XSSF cells that stop holding formulas</action> + <action type="add" fixes-bug="47582" context="XSSF">XSSFCellStyle support for creating a style in one workbook based on a style from a different one</action> + <action type="fix" fixes-bug="49931" context="HSSF">Avoid concurrency problems when re-ordering multiple HSSF header records for a PageSettingsBlock</action> + <action type="fix" fixes-bug="49765" context="XWPF">Fix XWPFDocument.addPicture so that it correctly sets up relationships</action> + <action type="fix" fixes-bug="48018" context="HWPF">Improve HWPF handling of lists in documents read and then saved, by preserving order better</action> + <action type="fix" fixes-bug="49820" context="HWPF">Fix HWPF paragraph levels, so that outline levels can be properly fetched</action> + <action type="fix" fixes-bug="47271" context="HWPF">Avoid infinite loops on broken HWPF documents with a corrupt CHP style with a parent of itself</action> + <action type="fix" fixes-bug="49936" context="HWPF">Handle HWPF documents with problematic HeaderStories better</action> + <action type="fix" fixes-bug="49933" context="HWPF">Support sections in Word 6 and Word 95 files (HWPFOldDocument)</action> + <action type="fix" fixes-bug="49941" context="HSSF">Correctly handle space preservation of XSSFRichTextRuns when applying fonts to parts of the string</action> + <action type="fix" context="XWPF">Correct XWPFRun detection of bold/italic in a paragraph with multiple runs of different styles</action> + <action type="add" context="XWPF">Link XWPFPicture to XWPFRun, so that embedded pictures can be access from where they live in the text stream</action> + <action type="fix" context="XWPF">Improve handling of Hyperlinks inside XWPFParagraph objects through XWPFHyperlinkRun</action> + <action type="fix" context="XWPF">Make XWPFParagraph make more use of XWPFRun, and less on internal StringBuffers</action> + <action type="add" context="XWPF">Add a getBodyElements() method to XWPF IBody, to make access to embedded paragraphs and tables easier</action> + <action type="add" context="XSLF">More XSLFRelation entries for common .pptx file parts</action> + <action type="fix" fixes-bug="49872" context="XSSF">avoid exception in XSSFFormulaEvaluator.evaluateInCell when evaluating shared formulas</action> + <action type="fix" fixes-bug="49895" context="XSSF">avoid corruption of XSSFWorkbook after removing all merged cells from sheet</action> + <action type="fix" fixes-bug="49907" context="HSSF">fixed inconsistent behaviour between HSSF and XSSF when creating consecutive names</action> + <action type="add" context="HWPF">Add getMimeType() method to HWPF Picture, alongside existing file extension</action> + <action type="add" context="POIFS">Add code for reading Ole10Native data</action> + <action type="add" context="HSSF XSSF">Add getMimeType() method to HSSF/XSSF PictureData, alongside existing file extension</action> + <action type="fix" fixes-bug="49887" context="HSSF">allow sheet names longer than 31 chars in XSSF, enforce name uniqueness on the first 31 chars</action> + <action type="fix" fixes-bug="49878" context="XSSF">improved API for hiding sheets</action> + <action type="fix" fixes-bug="49875" context="XSSF">fixed XSSFWorkbook.createSheet to throw exception if sheet name begins or ends with a single quote (')</action> + <action type="fix" fixes-bug="49873" context="XSSF">fixed XSSFFormulaEvaluator to support blank cells</action> + <action type="fix" fixes-bug="49850" context="HWPF">added a getter for _iStartAt in ListFormatOverrideLevel</action> + <action type="fix" fixes-bug="49761" context="HSSF">change cell type to error when setting Double.NaN or Infinities</action> + <action type="fix" fixes-bug="49833" context="XWPF">ensure that CTNumPr is included in poi-ooxml-schemas.jar</action> + <action type="fix" fixes-bug="49841" context="HSSF">fixed LEFT and RIGHT to return #VALUE! when called with a negative operand </action> + <action type="fix" fixes-bug="49783" context="POI_Overall">fixed evaluation of XSSF workbooks containing formulas with reference errors (#REF!)</action> + <action type="fix" fixes-bug="49751" context="HSSF">fixed fetching names of user defined styles in HSSFCellStyle.getUserStyleName()</action> + <action type="add" fixes-bug="48900" context="XSSF">support for protecting a XSSF workbook</action> + <action type="fix" fixes-bug="49725" context="POI_Overall">fixed FormulaParser to correctly process defined names with underscore</action> + <action type="add" fixes-bug="48526" context="XSSF">added implementation for RANDBETWEEN()</action> + <action type="fix" fixes-bug="49725" context="POI_Overall">avoid exception in OperandResolver.parseDouble when input is minus ("-")</action> + <action type="fix" fixes-bug="49723" context="HSSF">fixed OperandResolver to correctly handle inputs with leading decimal place</action> + <action type="add" context="HSSF">initial support for Excel autofilter</action> + </actions> + </release> + + <release version="3.7-beta2" date="2010-08-09"> + <actions> + <action type="add" fixes-bug="47990" context="HSMF">Support for .msg attachments within a MAPIMessage .msg</action> + <action type="fix" context="OPC">Improve handling and warnings when closing OPCPackage objects</action> + <action type="fix" fixes-bug="49702" context="XSSF">Correct XSSFWorkbook.getNumCellStyles to check the right styles list</action> + <action type="add" fixes-bug="49690" context="HSSF">Add WorkbookUtil, which provides a way of generating valid sheet names</action> + <action type="fix" fixes-bug="49694" context="HSSF">Use DataFormatter when autosizing columns, to better match the real display width of formatted cells</action> + <action type="add" fixes-bug="49441" context="HSMF">Allow overriding and guessing of HSMF non-unicode string encodings</action> + <action type="fix" fixes-bug="49689" context="HSSF">Allow the setting of user style names on newly created HSSF cell styles</action> + <action type="add" context="OOXML">Make it easier to tell which content types each POIXMLTextExtractor handles</action> + <action type="fix" fixes-bug="49649" context="HSSF">Added clone support for UserSView* and Feat* families of records</action> + <action type="fix" fixes-bug="49653" context="XSSF">Support for escaped unicode characters in Shared String Table</action> + <action type="fix" fixes-bug="49579" context="HSLF">prevent ArrayIndexOutOfBoundException in UnknownEscherRecord</action> + <action type="fix" fixes-bug="49593" context="XWPF">preserve leading and trailing white spaces in XWPFRun</action> + <action type="add" fixes-bug="49455" context="XWPF">Insert the content of fldSimple fields into the XWPFWordTextExtractor output</action> + <action type="fix" fixes-bug="49640" context="POI_Overall">Fixed parsing formulas containing defined names beginning with an underscore</action> + <action type="add" fixes-bug="49538" context="HSSF">Added implementation for POISSON()</action> + <action type="add" fixes-bug="49524" context="HSSF">Support for setting cell text to be vertically rotated, via style.setRotation(0xff)</action> + <action type="fix" fixes-bug="49609" context="XSSF">Case insensitive matching of OOXML part names</action> + <action type="add" fixes-bug="49581" context="HSSF">Ability to add, modify and remove series from HSSF Charts</action> + <action type="add" fixes-bug="49185" context="HSSF">Support for HSSFNames where the comment is stored in a NameCommentRecord</action> + <action type="fix" fixes-bug="49599" context="HSSF">correct writing of noterecord author text when switching between ascii and unicode</action> + <action type="fix" context="HWPF">improve reading of auto-saved ("complex") documents</action> + <action type="add" context="HWPF">paragraph level as well as whole-file text extraction for word 6/95 files through hwpf</action> + <action type="add" context="HWPF">text extraction support for older word 6 and word 95 files via hwpf</action> + <action type="add" fixes-bug="49508" context="XWPF">allow the addition of paragraphs to xwpf table cells</action> + <action type="fix" fixes-bug="49446" context="XWPF">don't consider 17.16.23 field codes as properly part of the paragraph's text</action> + <action type="fix" context="XSLF">xslfslideshow shouldn't break on .thmx (theme) files. support for them is still very limited though</action> + </actions> + </release> + + <release version="3.7-beta1" date="2010-06-20"> + <actions> + <action type="fix" fixes-bug="49432" context="XSSF">lazy caching of xssfcomment ctcomment objects by reference, to make repeated comment searching faster</action> + <action type="fix" context="HSMF">better handling of outlook messages in hsmf when there's no recipient email address</action> + <action type="fix" context="HSSF">when formatting numbers with dataformatter, handle brackets following colours</action> + <action type="add" fixes-bug="48574" context="XWPF">further xwpf support for tables, paragraphs, including enhanced support for adding new ones</action> + <action type="add" fixes-bug="48245" context="HWPF">tweak hwpf table cell detection to work across more files</action> + <action type="add" fixes-bug="48996" context="POI_Overall">initial support for external name references in hssf formula evaluation</action> + <action type="fix" fixes-bug="46664" context="HSSF">fix up tab ids when adding new sheets, so that print areas don't end up invalid</action> + <action type="fix" fixes-bug="45269" context="HWPF">improve replacetext on hwpf ranges</action> + <action type="fix" fixes-bug="47815" context="HSSF">correct documentation on what happens when you request a string from a non-string formula cell</action> + <action type="fix" fixes-bug="49386" context="HSLF">avoid npe when extracting ooxml file properties which are dates</action> + <action type="fix" fixes-bug="49377" context="POI_Overall">only call decimalformat.setroundingmode on java 1.6 - it's needed to match excel's rendering of numbers</action> + <action type="fix" fixes-bug="49378" context="POI_Overall">correct 1.6ism</action> + <action type="add" context="HSMF">parse the hsmf headers chunk if present, and use it to find dates in text extraction if needed</action> + <action type="fix" fixes-bug="48494" context="HSSF">detect and support time formats like hh:mm;hh:mm</action> + <action type="fix" fixes-bug="48494" context="HSSF">have excelextractor make use of hssfdataformatter, so that numbers and dates come out closer to how excel would render them</action> + <action type="fix" fixes-bug="48494" context="HSSF">have eventbasedexcelextractor make use of hssfdataformatter, so that numbers and dates come out closer to how excel would render them</action> + <action type="fix" fixes-bug="49096" context="HSSF">add clone support to chart begin and end records, to allow cloning of more chart containing sheets</action> + <action type="add" context="HSMF">list attachment names in the output of outlooktextextractor (to get attachment contents, use extractorfactory as normal)</action> + <action type="fix" fixes-bug="48872" context="POI_Overall">allow dateformatter.formatrawcellcontents to handle 1904 as well as 1900 dates</action> + <action type="fix" fixes-bug="48872" context="POI_Overall">handle mmmmm and elapsed time formatting rules in dataformatter</action> + <action type="fix" fixes-bug="48872" context="POI_Overall">handle zero formatting rules, and better color detection in dataformatter</action> + <action type="fix" fixes-bug="48872" context="POI_Overall">support for more kinds of formatting in dataformatter</action> + <action type="fix" fixes-bug="43161" context="HSLF">fixed construction of the dib picture header</action> + <action type="add" fixes-bug="49311" context="POIFS">initial support for reading aes-encrypted/write-protected ooxml files</action> + <action type="fix" fixes-bug="48718" context="XSSF">make the creation of multiple, un-modified fonts in a row in xssf match the old hssf behaviour</action> + <action type="fix" fixes-bug="44916" context="HSSF">allow access to the hssfpatriarch from hssfsheet once created</action> + <action type="add" fixes-bug="48779" context="XSSF">allow you to get straight from a cellstyle to a color, irrespective of if the color is indexed or inline-defined</action> + <action type="add" fixes-bug="48924" context="HWPF">allow access of the hwpf dateandtime underlying date values</action> + <action type="add" fixes-bug="48926" context="HWPF">initial support for the hwpf revision marks authors list</action> + <action type="fix" fixes-bug="49160" context="POI_Overall">ensure that ctdigsigblob is included in poi-ooxml jar</action> + <action type="fix" fixes-bug="49189" context="XWPF">detect w:tab and w:cr entries in xwpf paragraphs, even when the xsd is silly and maps them to ctempty</action> + <action type="fix" fixes-bug="49273" context="XSSF">correct handling for font character sets with indicies greater than 127</action> + <action type="add" fixes-bug="49334" context="HSSF">track the valuerangerecords of charts in hssfchart, to allow the basic axis operations</action> + <action type="add" fixes-bug="49242" context="HSSF">track the linkdatarecords of charts in hssfchart</action> + <action type="add" context="XSSF">improved performance of xssfworkbook.write </action> + <action type="fix" fixes-bug="48846" context="HSSF">avoid npe when finding cell comments</action> + <action type="fix" fixes-bug="49325" context="XSSF">ensure that ctphoneticpr is included in poi-ooxml jar</action> + <action type="fix" fixes-bug="49191" context="XSSF">fixed tests failing in non-english locales</action> + <action type="add" fixes-bug="48432" context="XSSF">support for xssf themes</action> + <action type="add" fixes-bug="49244" context="XSSF">support for data validation for ooxml format</action> + <action type="add" fixes-bug="49066" context="HSSF">worksheet/cell formatting, with view and html converter</action> + <action type="fix" fixes-bug="49020" context="XSSF">workaround excel outputting invalid xml in button definitions by not closing br tags</action> + <action type="fix" fixes-bug="49050" context="HSSF">improve performance of abstractescherholderrecord when there are lots of continue records</action> + <action type="fix" fixes-bug="49194" context="XSSF">correct text size limit for ooxml .xlsx files</action> + <action type="fix" fixes-bug="49254" context="XSSF">fix cellutils.setfont to use the correct type internally</action> + <action type="fix" fixes-bug="49139" context="POIFS">properly support 4k big block size in poifs</action> + <action type="fix" fixes-bug="48936" context="XSSF">avoid writing malformed cdata blocks in sharedstrings.xml</action> + <action type="add" fixes-bug="49026" context="POI_Overall">added implementation for text() </action> + <action type="add" fixes-bug="49025" context="POI_Overall">added implementation for trunc() </action> + <action type="fix" fixes-bug="49147" context="POI_Overall">properly close internal inputstream in extractorfactory#createextractor(file)</action> + <action type="fix" fixes-bug="49138" context="POI_Overall">fixed locale-sensitive formatters in packagepropertiespart</action> + <action type="fix" fixes-bug="49153" context="POI_Overall">ensure that ctvectorvariant is included in poi-ooxml-schemas.jar</action> + <action type="add" fixes-bug="49146" context="XWPF">added accessors to coreproperties.keywords </action> + <action type="fix" fixes-bug="48916" context="HSLF">propagate parent to parent-aware records decoded from escher</action> + <action type="fix" fixes-bug="48485" context="HSSF">add extra paper size constans to printsetup, such as a3, b4 and b5</action> + <action type="fix" context="POIFS">make poifs.filesystem.directorynode preserve the original ordering of its files, which hsmf needs to be able to correctly match up chunks</action> + <action type="add" context="HSSF">support evaluation of indirect defined names in indirect</action> + <action type="fix" fixes-bug="43670" context="POI_Overall">improve hdgf chunkv11 separator detection, and short string detection, to solve the "negative length of chunkheader" problem</action> + <action type="add" fixes-bug="48617" context="HSSF">optionally allow the overriding of the locale used by dataformatter to control how the default number and date formats should look</action> + <action type="add" context="XSSF">new event based xssf text extractor (xssfeventbasedexcelextractor)</action> + <action type="add" context="HSSF">extractorfactory can now be told to prefer event based extractors (current excel only) on a per-thread or overall basis</action> + <action type="fix" fixes-bug="48544" context="XSSF">avoid failures in xlsx2csv when shared string table is missing</action> + <action type="fix" fixes-bug="48571" context="POI_Overall">properly close all io streams created in opcpackage</action> + <action type="fix" fixes-bug="48572" context="XSSF">always copy all declared inner classes and interfaces when generating poi-ooxml-schemas</action> + <action type="add" context="HSSF">low level record support for the extrst (phonetic text) part of unicode strings. no usermodel access to it as yet though</action> + <action type="fix" context="HSSF">record.unicodestring has moved to record.common.unicodestring, to live with the other record-part classes, as it isn't a full record</action> + <action type="add" context="OPC">avoid creating temporary files when opening opc packages from input stream</action> + <action type="add" context="HSMF">improved how hsmf handles multiple recipients</action> + <action type="add" context="HPBF">add publishertextextractor support to extractorfactory</action> + <action type="add" context="XSLF">add xslf support for text extraction from tables</action> + <action type="add" context="HSMF">support attachments as embedded documents within the new outlooktextextractor</action> + <action type="add" context="HSMF">add a text extractor (outlooktextextractor) to hsmf for simpler extraction of text from .msg files</action> + <action type="fix" context="HSMF">some improvements to hsmf parsing of .msg files</action> + <action type="fix" context="HSSF">initialise the link type of hssfhyperlink, so that gettype() on it works</action> + <action type="fix" fixes-bug="48425" context="POI_Overall">improved performance of dateutil.iscelldateformatted() </action> + <action type="fix" fixes-bug="47215" context="HSSF">fixed interfaceendrecord to tolerate unexpected record contents </action> + <action type="fix" fixes-bug="48415" context="HSSF">improved javadoc on hsspicture.resize() </action> + <action type="add" context="POI_Overall">added ant target to install artifacts in local repository </action> + <action type="fix" fixes-bug="48026" context="HSSF">fixed pagesettingsblock to allow multiple headerfooterrecord records </action> + <action type="fix" fixes-bug="48202" context="HSSF">fixed cellrangeutil.mergecellranges to work for adjacent cell regions </action> + <action type="fix" fixes-bug="48339" context="HSSF">fixed externalnamerecord to properly distinguish dde data from ole data items </action> + <action type="fix" fixes-bug="47920" context="HSLF">allow editing workbooks embedded into powerpoint files</action> + <action type="add" fixes-bug="48343" context="HSSF">added implementation of subtotal function</action> + <action type="fix" context="OOXML">switch to compiling the ooxml schemas for java 1.5</action> + </actions> + </release> + <release version="3.6" date="2009-12-14"> + <actions> + <action type="fix" fixes-bug="48332" context="HSSF">fixed xssfsheet autosizecolumn() to tolerate empty richtextstring</action> + <action type="fix" fixes-bug="48332" context="HSSF">fixed columninforecord to tolerate missing reserved field</action> + <action type="fix" fixes-bug="47701" context="HSSF">fixed recordformatexception when reading list subrecords (lbsdatasubrecord)</action> + <action type="add" context="XSSF"> memory usage optimization in xssf - avoid creating parentless xml beans</action> + <action type="fix" fixes-bug="47188" context="XSSF">avoid corruption of workbook when adding cell comments </action> + <action type="fix" fixes-bug="48106" context="XSSF">improved work with cell comments in xssf</action> + <action type="add" context="HPSF">add support for creating summaryinformation and documentsummaryinformation properties + on poidocuments that don't have them, via poidocument.createinformationproperties() + </action> + <action type="fix" fixes-bug="48180" context="POI_Overall">be more forgiving of short chart records, which skip some unused fields</action> + <action type="fix" fixes-bug="48274" context="HSSF">fix erronious wrapping of byte colours in hssfpalette.findsimilarcolor</action> + <action type="fix" fixes-bug="48269" context="XSSF">fix fetching of error codes from xssf formula cells</action> + <action type="fix" fixes-bug="48229" context="HSSF">fixed javadoc for hssfsheet.setcolumnwidth and xssfsheet setcolumnwidth </action> + <action type="fix" fixes-bug="47757" context="HSSF">fixed xlsx2csv to avoid exception when processing cells with multiple "t" elements</action> + <action type="add" fixes-bug="48195" context="HSSF">short-circuit evaluation of if() and choose()</action> + <action type="add" fixes-bug="48161" context="HSLF">support for text extraction from ppt master slides</action> + <action type="add" fixes-bug="47970" context="HSSF">added a method to set arabic mode in hssfsheet</action> + <action type="fix" fixes-bug="48134" context="HSSF">release system resources when using picture.resize()</action> + <action type="fix" fixes-bug="48087" context="XSSF">avoid npe in xssfchartsheet when calling methods of the superclass</action> + <action type="fix" fixes-bug="48038" context="HWPF">handle reading hwpf stylesheets from non zero offsets</action> + <action type="add" context="OOXML">when running the "compile-ooxml-xsds" ant task, also generate the source jar for the ooxml schemas</action> + <action type="fix" fixes-bug="45672" context="HSSF">improve handling by missingrecordawarehssflistener of records that cover multiple cells (mulblankrecord and mulrkrecord)</action> + <action type="fix" fixes-bug="48096" context="HSSF">relaxed validation check in recalcidrecord</action> + <action type="fix" fixes-bug="48085" context="HSSF">improved error checking in blockallocationtablereader to trap unreasonable field values</action> + <action type="fix" fixes-bug="47924" context="HSSF">fixed logic for matching cells and comments in hssfcell.getcellcomment()</action> + <action type="add" fixes-bug="47942" context="XWPF">added implementation of protection features to xlsx and docx files</action> + <action type="fix" fixes-bug="48070" context="XSSF">preserve leading and trailing white spaces in xssfrichtextstring</action> + <action type="add" fixes-bug="48044" context="HSSF">added implementation for countblank function</action> + <action type="fix" fixes-bug="48036" context="HSSF">added intersectioneval to allow evaluation of the intersection formula operator</action> + <action type="fix" fixes-bug="47999" context="POI_Overall">avoid un-needed call to the jvm garbage collector when working on ooxml opc packages</action> + <action type="add" fixes-bug="47922" context="HSMF">added example hsmf application that converts a .msg file to text and extracts attachments</action> + <action type="add" fixes-bug="47903" context="POI_Overall">added ant target to compile scratchpad examples</action> + <action type="add" fixes-bug="47839" context="POI_Overall">improved api for ooxml custom properties</action> + <action type="fix" fixes-bug="47862" context="XSSF">fixed xssfsheet.setcolumnwidth to handle columns included in a column span</action> + <action type="fix" fixes-bug="47804" context="XSSF">fixed xssfsheet.setcolumnhidden to handle columns included in a column span</action> + <action type="fix" fixes-bug="47889" context="XSSF">fixed xssfcell.getstringcellvalue() to properly handle cached formula results</action> + </actions> + </release> + <release version="3.5-final" date="2009-09-28"> + <actions> + <action type="fix" fixes-bug="47747" context="HSSF">fixed logic for locating shared formula records</action> + <action type="add" fixes-bug="47809" context="POI_Overall">improved work with user-defined functions</action> + <action type="fix" fixes-bug="47581" context="XSSF">fixed xssfsheet.setcolumnwidth to produce xml compatible with mac excel 2008</action> + <action type="fix" fixes-bug="47734" context="POI_Overall">removed unnecessary svn:executable flag from files in svn trunk</action> + <action type="fix" fixes-bug="47543" context="HSSF">added javadoc how to avoid excel crash when creating too many hssfrichtextstring cells</action> + <action type="fix" fixes-bug="47813" context="XSSF">fixed problems with xssfworkbook.removesheetat when workbook contains chart</action> + <action type="fix" fixes-bug="47737" context="XSSF">adjust sheet indices of named ranges when deleting sheets</action> + <action type="fix" fixes-bug="47770" context="POI_Overall">built-in positive formats don't need starting '('</action> + <action type="add" fixes-bug="47771" context="POI_Overall">added method setfunction(boolean) for defined names</action> + <action type="add" fixes-bug="47768" context="HSSF">implementation of excel "days360" and "npv" functions</action> + <action type="fix" fixes-bug="47751" context="HSSF">do not allow hssf's cell text longer than 32,767 characters</action> + <action type="add" fixes-bug="47757" context="HSSF">added an example demonstrating how to convert an xlsx workbook to csv</action> + <action type="fix" fixes-bug="44770" context="HSLF">fixed ppt parser to tolerate comment2000 containers with missing comment text</action> + <action type="fix" fixes-bug="47773" context="XWPF">fix for extraction paragraphs and sections from headers/footers with xwpfwordextractor</action> + <action type="fix" fixes-bug="47727" context="XWPF">support for extraction of header / footer images in hwpf</action> + <action type="fix" context="POI_Overall">moved all test data to a top-level directory</action> + <action type="add" fixes-bug="47721" context="HSSF">Added implementation for INDIRECT()</action> + <action type="add" fixes-bug="45583" context="HWPF">Avoid exception when reading ClipboardData packet in OLE property sets</action> + <action type="add" fixes-bug="47652" context="HSSF">Added support for reading encrypted workbooks</action> + <action type="add" fixes-bug="47604" context="XSSF">Implementation of an XML to XLSX Importer using Custom XML Mapping</action> + <action type="fix" fixes-bug="47620" context="XSSF">Avoid FormulaParseException in XSSFWorkbook.setRepeatingRowsAndColumns when removing repeated rows and columns</action> + <action type="fix" fixes-bug="47606" context="XSSF">Fixed XSSFCell to correctly parse column indexes greater than 702 (ZZ)</action> + <action type="fix" fixes-bug="47598" context="HSSF">Improved formula evaluator number comparison</action> + <action type="fix" fixes-bug="47571" context="XWPF">Fixed XWPFWordExtractor to extract inserted/deleted text</action> + <action type="fix" fixes-bug="47548" context="HSSF">Fixed RecordFactoryInputStream to properly read continued DrawingRecords</action> + <action type="fix" fixes-bug="46419" context="XSSF">Fixed compatibility issue with OpenOffice 3.0</action> + <action type="fix" fixes-bug="47559" context="XSSF"> + Fixed compatibility issue with Excel 2008 Mac sp2. Please see + <a href="site:spreadsheet"> the HSSF+XSSF project page</a> + for more information. + </action> + <action type="fix" fixes-bug="47540" context="XSSF">Fix for saving custom and extended OOXML properties</action> + <action type="fix" fixes-bug="47535" context="HWPF">Fixed WordExtractor to tolerate files with empty footnote block</action> + <action type="fix" fixes-bug="47517" context="POI_Overall">Fixed ExtractorFactory to support .xltx and .dotx files</action> + <action type="add" fixes-bug="45556" context="POI_Overall">Support for extraction of footnotes from docx files</action> + <action type="add" fixes-bug="45555" context="POI_Overall">Support for extraction of endnotes from docx files</action> + <action type="add" fixes-bug="47520" context="XSSF">Initial support for custom XML mappings in XSSF</action> + <action type="fix" fixes-bug="47460" context="XSSF">Fixed NPE when retrieving core properties from a newly created workbook</action> + <action type="fix" fixes-bug="47498" context="HSSF">Fixed HyperlinkRecord to properly handle URL monikers</action> + <action type="fix" fixes-bug="47504" context="XSSF">Fixed XSSFWorkbook to read files with hyperlinks to document locations</action> + <action type="fix" fixes-bug="47479" context="HSSF">Fix BoolErrRecord to tolerate incorrect format written by OOO</action> + <action type="fix" fixes-bug="47448" context="HSSF">Allow HSSFEventFactory to handle non-zero padding at the end of the workbook stream</action> + <action type="add" fixes-bug="47456" context="HSLF">Support for getting OLE object data in PowerPointExtractor</action> + <action type="fix" fixes-bug="47411" context="XSSF">Explicitly set the 1900 date system when creating XSSF workbooks</action> + <action type="add" fixes-bug="47400" context="HWPF">Support for text extraction of footnotes, endnotes and comments in HWPF</action> + <action type="fix" fixes-bug="47415" context="HSSF">Fixed PageSettingsBlock to allow multiple PLS records</action> + <action type="fix" fixes-bug="47412" context="POI_Overall">Fixed concurrency issue with EscherProperties.initProps()</action> + <action type="fix" fixes-bug="47143" context="HSSF">Fixed OOM in HSSFWorkbook#getAllPictures when reading .xls files containing metafiles</action> + <action type="add" context="HSSF">Added implementation for ISNA()</action> + <action type="add" fixes-bug="46793" context="HSLF">fixed SimpleShape#getLineWidth to handle default line width </action> + <action type="add" fixes-bug="47356" context="HWPF">removed unused private fields in HWPF BorderCode</action> + <action type="add" fixes-bug="47355" context="HWPF">Improved HWPF TableCell to expose TableCellDescriptor</action> + <action type="fix" fixes-bug="46610" context="HWPF">Improved HWPF to better handle unicode</action> + <action type="fix" fixes-bug="47261" context="HSLF">Fixed SlideShow#removeSlide to remove references to Notes</action> + <action type="fix" fixes-bug="47375" context="HSSF">Fixed HSSFHyperlink to correctly set inter-sheet and file links</action> + <action type="fix" fixes-bug="47384" context="HSSF">Fixed ExternalNameRecord to handle unicode names</action> + <action type="fix" fixes-bug="47372" context="HSSF">Fixed locale-sensitive unit tests to pass when running on non-US locale</action> + </actions> + </release> + <release version="3.5-beta6" date="2009-06-22"> + <actions> + <action type="fix" fixes-bug="47363" context="HSSF">Fixed HSSFSheet to allow addition of data validations after sheet protection</action> + <action type="fix" fixes-bug="47294" context="XSSF">Fixed XSSFWorkbook#setRepeatingRowsAndColumns to tolerate sheet names with quotes</action> + <action type="fix" fixes-bug="47309" context="HSSF">Fixed logic in HSSFCell.getCellComment to handle sheets with more than 65536 comments</action> + <action type="fix" fixes-bug="46776" context="HSSF">Added clone() method to MulBlankRecord to fix crash in Sheet.cloneSheet()</action> + <action type="fix" fixes-bug="47244" context="HSSF">Fixed HSSFSheet to handle missing header / footer records</action> + <action type="fix" fixes-bug="47312" context="HSSF">Fixed formula parser to properly reject cell references with a '0' row component</action> + <action type="fix" fixes-bug="47199" context="HSSF">Fixed PageSettingsBlock/Sheet to tolerate margin records after other non-PSB records</action> + <action type="fix" fixes-bug="47069" context="HSSF">Fixed HSSFSheet#getFirstRowNum and HSSFSheet#getLastRowNum to return correct values after removal of all rows</action> + <action type="fix" fixes-bug="47278" context="XSSF">Fixed XSSFCell to avoid generating xsi:nil entries in shared string table</action> + <action type="fix" fixes-bug="47206" context="XSSF">Fixed XSSFCell to properly read inline strings</action> + <action type="add" fixes-bug="47250" context="HSSF">Fixed FontRecord to expect unicode flags even when name length is zero</action> + <action type="add" fixes-bug="47198" context="HSSF">Fixed formula evaluator comparison of -0.0 and 0.0</action> + <action type="add" fixes-bug="47229" context="HSSF">Fixed ExternalNameRecord to handle DDE links</action> + <action type="add" fixes-bug="46287" context="HSSF">Control of header and footer extraction in ExcelExtractor / XSSFExcelExtractor</action> + <action type="add" fixes-bug="46554" context="POI_Overall">New ant target "jar-examples"</action> + <action type="add" fixes-bug="46161" context="XSSF">Support in XSSF for setGroupColumnCollapsed and setGroupRowCollapsed</action> + <action type="add" fixes-bug="46806" context="XSSF">Allow columns greater than 255 and rows greater than 0x100000 in XSSF formulas</action> + <action type="add" fixes-bug="41711" context="HSLF">Base class for "old version" exceptions, and new HSLF detection + use of old versions exception</action> + <action type="fix" fixes-bug="47179" context="POIFS">Fix string encoding issues with HSMF chunks on non-windows platforms</action> + <action type="add" fixes-bug="47183" context="POIFS">Attachment support for HSMF</action> + <action type="fix" fixes-bug="47154" context="HSSF">Handle the cell format @ as the same as General</action> + <action type="fix" fixes-bug="47048" context="HSSF">Fixed evaluation of defined names with the 'complex' flag set</action> + <action type="fix" fixes-bug="46953" context="HSSF">More tweaks to PageSettingsBlock parsing logic in Sheet constructor</action> + <action type="fix" fixes-bug="47089" context="XSSF">Fixed XSSFWorkbook.createSheet to properly increment sheetId</action> + <action type="fix" fixes-bug="46568" context="POI_Overall">Fixed XSLFPowerPointExtractor to properly process line breaks</action> + <action type="fix" fixes-bug="39056" context="POIFS">Fixed POIFSFileSystem to set CLSID of root when constructing instances from InputStream</action> + <action type="fix" fixes-bug="47054" context="HSSF">Fixed cloneStyleFrom to avoid exception when cloning styles of the same family</action> + <action type="fix" fixes-bug="46186" context="HSSF">Fixed Sheet to read GutsRecord in the Sheet(RecordStream rs)</action> + <action type="fix" fixes-bug="46714" context="HSSF">Automatically call sheet.setAlternativeExpression when sheet.setRowSumsBelow is called </action> + <action type="fix" fixes-bug="46279" context="XSSF">Allow 255 arguments for excel functions in XSSF </action> + <action type="fix" fixes-bug="47028" context="XSSF">Fixed XSSFCell to preserve cell style when cell value is set to blank</action> + <action type="fix" fixes-bug="47026" context="XSSF">Avoid NPE in XSSFCell.setCellType() when workbook does not have SST</action> + <action type="fix" fixes-bug="46987" context="HSSF">Allow RecordFactory to handle non-zero padding at the end of the workbook stream</action> + <action type="fix" fixes-bug="47034" context="HSSF">Fix reading the name of a NameRecord when the name is very long</action> + <action type="fix" fixes-bug="47001" context="HSSF">Fixed WriteAccessRecord and LinkTable to handle unusual format written by Google Docs</action> + <action type="fix" fixes-bug="46973" context="HSSF">Fixed defined names to behave better when refersToFormula is unset</action> + <action type="fix" fixes-bug="46832" context="XSSF">Allow merged regions with columns greater than 255 or rows bigger than 65536 in XSSF</action> + <action type="fix" fixes-bug="46951" context="HSSF">Fixed formula parser to better handle range operators and whole row/column refs</action> + <action type="fix" fixes-bug="46948" context="HSSF">Fixed evaluation of range operator to allow for area-ref operands</action> + <action type="fix" fixes-bug="46918" context="HSSF">Fixed ExtendedPivotTableViewFieldsRecord(SXVDEX) to allow shorter format</action> + <action type="fix" fixes-bug="46898" context="XSSF">Fixed formula evaluator to not cache intermediate circular-reference error results</action> + <action type="fix" fixes-bug="46917" context="HSSF">Fixed PageItemRecord(SXPI) to allow multiple field infos</action> + <action type="fix" fixes-bug="46904" context="HSSF">Fix POIFS issue with duplicate block 0 references on very old BIFF5/BIFF7 files</action> + <action type="fix" fixes-bug="46840" context="HSSF">PageSettingsBlock should include HEADERFOOTER record</action> + <action type="fix" fixes-bug="46885" context="XSSF">update cell type when setting cached formula result in XSSFCell</action> + <action type="add" context="XSSF">added modifiers for anchor type to XSSFClientAnchor</action> + <action type="add" fixes-bug="46772" context="XSSF">support built-in data formats in XSSFDataFormat</action> + <action type="fix" fixes-bug="46719" context="XSSF">fixed XSSFSheet.shiftRows to correctly preserve row heights</action> + <action type="fix" fixes-bug="46715" context="XSSF">preserve custom column widths across re-serialization of XSSFWorkbook</action> + <action type="add" fixes-bug="46703" context="HSSF">added setDisplayZeros / isDisplayZeros to common interface org.apache.poi.ss.usermodel.Sheet</action> + <action type="add" fixes-bug="46708" context="XSSF">added getMergedRegion(int) to common interface org.apache.poi.ss.usermodel.Sheet</action> + <action type="fix" context="SS_Common">fixed Sheet.autoSizeColumn() to use cached formula values when processing formula cells </action> + <action type="fix" context="SS_Common">Fixed formula parser to handle names with backslashes</action> + <action type="add" fixes-bug="46660" context="HSSF">added Workbook getHidden() and setHidden(boolean)</action> + <action type="fix" fixes-bug="46693" context="HSSF">Fixed bugs serialization bugs in records: CHARTFORMAT, SHTPROPS, SXVD and SXVDEX</action> + <action type="fix" fixes-bug="46627" context="HSLF">Fixed offset of added images if Pictures stream contains pictures with zero length</action> + </actions> + </release> + <release version="3.5-beta5" date="2009-02-19"> + <actions> + <action type="fix" fixes-bug="46536" context="XSSF">When shifting rows, update formulas on that sheet to point to the new location of those rows</action> + <action type="fix" fixes-bug="46663" context="XSSF">Fixed XSSFSheet.shiftRows to properly update references of the shifted cells</action> + <action type="fix" fixes-bug="46535" context="XSSF">Remove reference from calculation chain when a formula is deleted</action> + <action type="fix" fixes-bug="46654" context="HSSF">HSSFRow/RowRecord to properly update cell boundary indexes</action> + <action type="fix" fixes-bug="46643" context="HSSF">Fixed formula parser to encode range operator with tMemFunc</action> + <action type="fix" fixes-bug="46647" context="HSSF">Fixed COUNTIF NE operator and other special cases involving type conversion</action> + <action type="add" fixes-bug="46635" context="HSLF">Added a method to remove slides</action> + <action type="fix" fixes-bug="40520" context="HSSF">Fixed HSSFFont.applyFont() to properly apply font to overlapping regions</action> + <action type="fix" fixes-bug="46545" context="HSSF">Fixed ObjRecord to ignore excessive padding written by previous POI versions</action> + <action type="fix" fixes-bug="46613" context="HSSF">Fixed evaluator to perform case insensitive string comparisons</action> + <action type="add" fixes-bug="46544" context="HSSF">command line interface for hssf ExcelExtractor</action> + <action type="fix" fixes-bug="46547" context="HSSF">Allow addition of conditional formatting after data validation</action> + <action type="fix" fixes-bug="46548" context="HSSF">Page Settings Block fixes - continued PLS records and PSB in sheet sub-streams</action> + <action type="add" fixes-bug="46523" context="HSSF">added implementation for SUMIF function</action> + <action type="add" context="HSSF">Support for reading HSSF column styles</action> + <action type="fix" context="OOXML">Hook up POIXMLTextExtractor.getMetadataTextExtractor() to the already written POIXMLPropertiesTextExtractor</action> + <action type="fix" fixes-bug="46472" context="HPSF">Avoid NPE in HPSFPropertiesExtractor when no properties exist</action> + <action type="fix" fixes-bug="46479" context="HSSF">fixed bugs related to cached formula values and HSSFFormulaEvaluator.evaluateInCell()</action> + <action type="add" fixes-bug="45031" context="HSSF">added implementation for CHOOSE() function</action> + <action type="fix" fixes-bug="46361" context="HDF">resolve licensing issues around the HDGF resource file, chunks_parse_cmds.tbl</action> + <action type="add" fixes-bug="46410" context="HSSF">added implementation for TIME() function</action> + <action type="add" fixes-bug="46320" context="HSSF">added HSSFPictureData.getFormat()</action> + <action type="fix" fixes-bug="46445" context="HSSF">fixed HSSFSheet.shiftRow to move hyperlinks</action> + <action type="fix" context="SS_Common">fixed formula parser to correctly resolve sheet-level names</action> + <action type="fix" fixes-bug="46433" context="XSSF">support for shared formulas in XSSF</action> + <action type="add" fixes-bug="46299" context="XWPF">support for carriage return and line break in XWPFRun</action> + <action type="add" fixes-bug="46300" context="XWPF">support for line spacing in XWPFParagraph</action> + <action type="add" fixes-bug="46308" context="XWPF">initial support for creation of XWPFTable</action> + <action type="add" context="HSSF">Added getters to parent objects: HSSFSheet.getWorkbook(), HSSFRow.getSheet() and HSSFCell.getRow()</action> + <action type="fix" fixes-bug="46385" context="HSSF">(also patch 46362) fix serialization of StyleRecord with unicode name</action> + <action type="fix" fixes-bug="46368" context="HSSF">Fix HSSFRichTextRun and strings longer than 32768 characters</action> + <action type="add" context="HSSF">Support sheet-level names</action> + <action type="fix" context="XSSF">Fixed XSSFCell to properly handle cell references with column numbers up to XFD</action> + <action type="fix" fixes-bug="44914" context="HSSF">Fixed warning message "WARN. Unread n bytes of record 0xNN"</action> + <action type="add" fixes-bug="46156" context="HSSF">Improved number to text conversion to be closer to that of Excel</action> + <action type="fix" fixes-bug="46312" context="HSSF">Fixed ValueRecordsAggregate to handle removal of new empty row</action> + <action type="add" fixes-bug="46269" context="HSSF">Improved error message when attempting to read BIFF2 file</action> + <action type="fix" fixes-bug="46206" context="HSSF">Fixed Sheet to tolerate missing DIMENSION records</action> + <action type="add" fixes-bug="46301" context="HSSF">added pivot table records: SXDI, SXVDEX, SXPI, SXIDSTM, SXVIEW, SXVD, SXVS, et al</action> + <action type="fix" fixes-bug="46280" context="HSSF">Fixed RowRecordsAggregate etc to properly skip PivotTable records</action> + </actions> + </release> + <release version="3.5-beta4" date="2008-11-29"> + <actions> + <action type="fix" fixes-bug="46213" context="HSSF">Fixed FormulaRecordAggregate to gracefully ignore extra StringRecords</action> + <action type="fix" fixes-bug="46174" context="HSSF">Fixed HSSFName to handle general formulas (not just area references)</action> + <action type="add" fixes-bug="46189" context="HSSF">added chart records: CHARTFRTINFO, STARTBLOCK, ENDBLOCK, STARTOBJECT, ENDOBJECT, and CATLAB</action> + <action type="fix" fixes-bug="46199" context="HSSF">More tweaks to EmbeddedObjectRefSubRecord</action> + <action type="add" context="SS_Common">Changes to formula evaluation allowing for reduced memory usage</action> + <action type="fix" fixes-bug="45290" context="POIFS">Support odd files where the POIFS header block comes after the data blocks, and is on the data blocks list</action> + <action type="fix" fixes-bug="46184" context="HSSF">More odd escaped date formats</action> + <action type="add" context="HSSF">Include the sheet number in the output of XLS2CSVmra</action> + <action type="fix" fixes-bug="46043" context="HWPF">correctly write out HPSF properties with HWPF</action> + <action type="add" fixes-bug="45973" context="POI_Overall">added CreationHelper.createFormulaEvaluator(), implemeted both for HSSF and XSSF</action> + <action type="fix" fixes-bug="46182" context="HSLF">fixed Slideshow.readPictures() to skip pictures with invalid headers</action> + <action type="fix" fixes-bug="46137" context="POIFS">Handle odd files with a ContinueRecord after EOFRecord</action> + <action type="fix" context="SS_Common">Fixed problem with linking shared formulas when ranges overlap</action> + <action type="fix" fixes-bug="45784" context="HSSF">More fixes to SeriesTextRecord</action> + <action type="fix" fixes-bug="46033" context="HSLF">fixed TableCell to correctly set text type</action> + <action type="fix" fixes-bug="46122" context="HSLF">fixed Picture.draw to skip rendering if picture data was not found</action> + <action type="fix" fixes-bug="15716" context="HSSF">memory usage optimisation - converted Ptg arrays into Formula objects</action> + <action type="add" fixes-bug="46065" context="HSSF">added implementation for VALUE function</action> + <action type="add" fixes-bug="45966" context="HSSF">added implementation for FIND function</action> + <action type="fix" fixes-bug="45778" context="HSSF">fixed ObjRecord to read ftLbsData properly</action> + <action type="fix" fixes-bug="46053" context="HSSF">fixed evaluation cache dependency analysis when changing blank cells</action> + </actions> + </release> + <release version="3.5-beta3" date="2008-09-26"> + <actions> + <action type="fix" fixes-bug="45518" context="POI_Overall">Fix up ColumnHelper to output valid col tags, by making 1 based and 0 based bits clearer, and using the right ones</action> + <action type="fix" fixes-bug="45676" context="POI_Overall">Handle very long cells in the XSSF EventUserModel example</action> + <action type="add" context="OOXML">Initial ExtractorFactory support for building TextExtractors for embedded documents</action> + </actions> + </release> + <release version="3.5-beta2" date="2008-08-20"> + <actions> + <action type="add" context="XSSF">Support stripping XSSF header and footer fields (eg page number) out of header and footer text if required</action> + <action type="add" context="OOXML">Add POIXMLPropertiesTextExtractor, which provides to the OOXML file formats a similar function to HPSF's HPSFPropertiesExtractor</action> + <action type="add" fixes-bug="45539" context="POI_Overall">Improve XWPFWordExtractor to extract headers and footers</action> + <action type="fix" context="XWPF">Improve how XWPF handles paragraph text</action> + <action type="add" context="XWPF">Support in XWPF handles headers and footers</action> + <action type="add" fixes-bug="45592" context="HWPF">Improve XWPF text extraction to include tables always, and picture text where possible</action> + <action type="add" fixes-bug="45545" context="POI_Overall">Improve XSLF usermodel support, and include XSLF comments in extracted text</action> + <action type="add" fixes-bug="45540" context="POI_Overall">Fix XSSF header and footer support, and include headers and footers in the output of XSSFExcelExtractor</action> + <action type="add" fixes-bug="45431" context="XSSF">Support for .xlsm files, sufficient for simple files to be loaded by excel without warning</action> + <action type="add" context="HSSF">New class org.apache.poi.hssf.record.RecordFormatException, which DDF uses instead of the HSSF version, and the HSSF version inherits from</action> + <action type="add" fixes-bug="45431" context="XSSF">Partial support for .xlm files. Not quite enough for excel to load them though</action> + <action type="fix" fixes-bug="45430" context="HSSF">Correct named range sheet reporting when no local sheet id is given in the xml</action> + </actions> + </release> + <release version="3.5-beta1" date="2008-07-18"> + <actions> + <action type="add" fixes-bug="45018" context="POI_Overall">Support for fetching embedded documents from within an OOXML file</action> + <action type="add" context="XSSF">Port support for setting a policy on missing / blank cells when fetching, to XSSF too</action> + <action type="add" context="OOXML">Common text extraction factory, which returns the correct POITextExtractor for the supplied data</action> + <action type="add" context="OOXML">Text Extraction support for the new OOXML files (.xlsx, .docx and .pptx)</action> + <action type="add" context="XSSF">Initial support for processing OOXML Excel files (.xlsx), both directly through XSSF, and also through the new common UserModel</action> + <action type="add" context="HSLF XSLF">Created a common interface for handling PowerPoint files, irrespective of if they are .ppt or .pptx</action> + <action type="add" context="HSSF XSSF">Created a common interface for handling Excel files, irrespective of if they are .xls or .xlsx</action> + </actions> + </release> + <release version="3.2-FINAL" date="2008-10-19"> + <actions> + <action type="fix" fixes-bug="45866" context="HSSF">allowed for change of unicode compression across Continue records</action> + <action type="fix" fixes-bug="45964" context="HSSF">support for link formulas in Text Objects</action> + <action type="fix" fixes-bug="43354" context="HSSF">support for evaluating formulas with missing args</action> + <action type="fix" fixes-bug="45912" context="HSSF">fixed ArrayIndexOutOfBoundsException in EmbeddedObjectRefSubRecord</action> + <action type="fix" fixes-bug="45889" context="HSLF">fixed ArrayIndexOutOfBoundsException when constructing HSLF Table with a single row </action> + <action type="add" context="HSLF">Initial support for creating hyperlinks in HSLF</action> + <action type="fix" fixes-bug="45876" context="HSSF">fixed BoundSheetRecord to allow sheet names longer than 31 chars</action> + <action type="add" fixes-bug="45890" context="HSSF">fixed HSSFSheet.shiftRows to also update conditional formats</action> + <action type="add" fixes-bug="45865" context="HSSF">modified Formula Parser/Evaluator to handle cross-worksheet formulas</action> + <action type="add" context="SS_Common">Optimised the FormulaEvaluator to take cell dependencies into account</action> + <action type="add" fixes-bug="16936" context="HSSF">Initial support for whole-row cell styling</action> + <action type="add" context="HSSF">Update hssf.extractor.ExcelExtractor to optionally output blank cells too</action> + <action type="add" context="HSSF">Include the sheet name in the output of examples.XLS2CSVmra</action> + <action type="fix" fixes-bug="45784" context="HSSF">Support long chart titles in SeriesTextRecords</action> + <action type="fix" fixes-bug="45777" context="HSSF">Throw an exception if HSSF Footer or Header is attempted to be set too long, rather than having it break during writing out</action> + <action type="add" fixes-bug="45844" context="HSLF">Additional diagnostics for HSLF SlideShowRecordDumper</action> + <action type="fix" fixes-bug="45829" context="HSSF">HSSFPicture.getImageDimension() failed when DPI of image is zero</action> + <action type="fix" fixes-bug="45815" context="HSLF">Bit mask values in StyleTextPropAtom were not preserved across read-write</action> + <action type="add" fixes-bug="45814" context="HSLF">Specify RecordType for slide show Handout (4041)</action> + <action type="fix" fixes-bug="45805" context="HSSF">Fixed 16-bit signed/unsigned bug in HSSFSheet.getColWidth etc</action> + <action type="fix" fixes-bug="45780" context="HSSF">Fixed HSSFSheet.shiftRows to also update Area refs</action> + <action type="fix" fixes-bug="45804" context="POI_Overall">Update HSMF to handle Outlook 3.0 msg files, which have a different string chunk type</action> + <action type="add" context="HSSF">Expose the name of Named Cell Styles via HSSFCellStyle (normally held on the parent style though)</action> + <action type="fix" fixes-bug="45978" context="HSSF">Fixed IOOBE in Ref3DPtg.toFormulaString() due eager initialisation of SheetReferences</action> + <action type="add" context="HSSF">Made HSSFFormulaEvaluator no longer require initialisation with sheet or row</action> + <action type="add" context="HSSF">Extended support for cached results of formula cells</action> + <action type="fix" fixes-bug="45639" context="HSSF">Fixed AIOOBE due to bad index logic in ColumnInfoRecordsAggregate</action> + <action type="fix" context="HSSF">Fixed special cases of INDEX function (single column/single row, errors)</action> + <action type="add" fixes-bug="45761" context="HSSF">Support for Very Hidden excel sheets in HSSF</action> + <action type="add" fixes-bug="45738" context="HWPF">Initial HWPF support for Office Art Shapes</action> + <action type="fix" fixes-bug="45720" context="HSSF">Fixed HSSFWorkbook.cloneSheet to correctly clone sheets with drawings</action> + <action type="fix" fixes-bug="45728" context="HSLF">Fix for SlideShow.reorderSlide in HSLF</action> + <action type="add" context="HSLF">Initial support for embedded movies and controls in HSLF</action> + <action type="fix" fixes-bug="45358" context="HSSF">signed/unsigned error when parsing 3-d area refs, performance problem evaluating area refs, and ClassCastExcecption in IF()</action> + <action type="add" context="HPBF">Support for HPBF Publisher hyperlinks, including during text extraction</action> + <action type="fix" fixes-bug="26321,44958" context="HSSF">preserve position of ArrayRecords and TableRecords among cell value records</action> + <action type="fix" context="HWPF">Impove empty header or footer handling in HWPF HeaderStories</action> + <action type="fix" context="HSSF">Avoid NPE in hssf.usermodel.HeaderFooter when stripping fields out</action> + <action type="fix" context="HSSF">Avoid NPE in EscherBSERecord on older escher records</action> + <action type="add" context="HPBF">Basic text extraction support in HPBF</action> + <action type="add" context="HPBF">Initial, low level support for Publisher files, in the form of HPBF</action> + <action type="fix" fixes-bug="45699" context="HSSF">Fix RowRecordsAggregate to tolerate intervening MERGEDCELLS records</action> + <action type="fix" fixes-bug="45698" context="HSSF">Fix LinkTable to tolerate multiple EXTERNSHEET records</action> + <action type="fix" fixes-bug="45682" context="HSSF">Fix for cloning of CFRecordsAggregate</action> + <action type="add" context="HSSF">Initial support for evaluating external add-in functions like YEARFRAC</action> + <action type="fix" fixes-bug="45672" context="HSSF">Fix for MissingRecordAwareHSSFListener to prevent multiple LastCellOfRowDummyRecords when shared formulas are present</action> + <action type="fix" fixes-bug="45645" context="HSSF">Fix for HSSFSheet.autoSizeColumn() for widths exceeding Short.MAX_VALUE</action> + <action type="add" fixes-bug="45623" context="HSSF">Support for additional HSSF header and footer fields, including bold and full file path</action> + <action type="add" fixes-bug="45623" context="HSSF">Support stripping HSSF header and footer fields (eg page number) out of header and footer text if required</action> + <action type="add" fixes-bug="45622" context="HWPF">Support stripping HWPF fields (eg macros) out of text, via Range.stripFields(text)</action> + <action type="add" context="HPSF">New HPSF based TextExtractor for document metadata, org.apache.poi.hpsf.extractor.HPSFPropertiesExtractor</action> + <action type="fix" context="HSLF">Properly update the array of Slide's text runs in HSLF when new text shapes are added</action> + <action type="fix" fixes-bug="45590" context="HSLF">Fix for Header/footer extraction for .ppt files saved in Office 2007</action> + <action type="fix" context="HWPF">Big improvement in how HWPF handles unicode text, and more sanity checking of text ranges within HWPF</action> + <action type="add" context="HWPF">Include headers and footers int he extracted text from HWPF's WordExtractor</action> + <action type="add" context="HWPF">Added support to HWPF for headers and footers</action> + <action type="fix" context="HWPF">Improve how HWPF deals with unicode internally. Should avoid some odd behaviour when manipulating unicode text</action> + <action type="add" fixes-bug="45577" context="HSSF">Added implementations for Excel functions NOW and TODAY</action> + <action type="fix" fixes-bug="45582" context="HSSF">Fix for workbook streams with extra bytes trailing the EOFRecord</action> + <action type="add" fixes-bug="45537" context="HSLF">Include headers and footers (of slides and notes) in the extracted text from HSLF</action> + <action type="fix" fixes-bug="45472" context="HSSF">Fixed incorrect default row height in OpenOffice 2.3</action> + <action type="fix" fixes-bug="44692" context="HSSF">HSSFPicture.resize() stretched image when there was a text next to it</action> + <action type="add" fixes-bug="45543" context="POI_Overall">Optionally extract comment text with PowerPointExtractor, and initial hslf model support for comments</action> + <action type="fix" fixes-bug="45538" context="POI_Overall">Include excel headers and footers in the output of ExcelExtractor</action> + <action type="fix" fixes-bug="44894" context="HSSF">refactor duplicate logic from EventRecordFactory to RecordFactory</action> + <action type="add" context="HSLF">Support for Headers / Footers in HSLF</action> + <action type="fix" fixes-bug="44953" context="HSSF">Extensive fixes for data validation</action> + <action type="fix" fixes-bug="45519" context="HSSF">Fixed to keep datavalidation records together</action> + <action type="add" context="HSSF">Support for creating new HSLF CurrentUserAtoms</action> + <action type="add" fixes-bug="45466" context="HSSF">Partial support for removing excel comments (won't work for all excel versions yet)</action> + <action type="fix" fixes-bug="45437" context="HWPF">Detect encrypted word documents, and throw an EncryptedDocumentException instead of a OOM</action> + <action type="add" fixes-bug="45404" context="HSSF">New class, hssf.usermodel.HSSFDataFormatter, for formatting numbers and dates in the same way that Excel does</action> + <action type="fix" fixes-bug="45414" context="HSSF">Don't add too many UncalcedRecords to sheets with charts in them</action> + <action type="fix" fixes-bug="45398" context="HSSF">Support detecting date formats containing "am/pm" as date times</action> + <action type="fix" fixes-bug="45410" context="HSSF">Removed dependency from contrib on commons beanutils,collections and lang</action> + <action type="add" context="HSSF">New helper, HSSFOptimiser, which handles removing duplicated font and style records, to avoid going over the limits in Excel</action> + <action type="fix" fixes-bug="45322" context="HSSF">Fixed NPE in HSSFSheet.autoSizeColumn() when cell number format was not found</action> + <action type="add" fixes-bug="45380" context="HSSF">Missing return keyword in ArrayPtg.toFormulaString()</action> + <action type="add" fixes-bug="44958" context="HSSF">Record level support for Data Tables. (No formula parser support though)</action> + <action type="add" fixes-bug="35583" context="POI_Overall">Include a version class, org.apache.poi.Version, to allow easy introspection of the POI version</action> + <action type="add" context="HSSF">Allow the cloning of one HSSFCellStyle onto another, including cloning styles from one HSSFWorkbook onto another</action> + <action type="fix" fixes-bug="45289" context="HSSF">finished support for special comparison operators in COUNTIF</action> + <action type="fix" fixes-bug="45126" context="HSSF">Avoid generating multiple NamedRanges with the same name, which Excel dislikes</action> + <action type="fix" context="HSSF">Fix cell.getRichStringCellValue() for formula cells with string results</action> + <action type="fix" fixes-bug="45365" context="HSSF">Handle more excel number formatting rules in FormatTrackingHSSFListener / XLS2CSVmra</action> + <action type="fix" fixes-bug="45373" context="HSSF">Improve the performance of HSSFSheet.shiftRows</action> + <action type="fix" fixes-bug="45367" context="HSSF">Fixed bug when last row removed from sheet is row zero</action> + <action type="fix" fixes-bug="45348" context="HSSF">Tweaks to RVA formula logic</action> + <action type="fix" fixes-bug="45354" context="HSSF">Fixed recognition of named ranges within formulas</action> + <action type="fix" fixes-bug="45338" context="HSSF">Fix HSSFWorkbook to give you the same HSSFFont every time, and then fix it to find newly added fonts</action> + <action type="fix" fixes-bug="45336" context="HSSF">Fix HSSFColor.getTripletHash()</action> + <action type="fix" fixes-bug="45334" context="HSSF">Fixed formula parser to handle dots in identifiers</action> + <action type="fix" fixes-bug="45252" context="HWPF">Improvement for HWPF Range.replaceText()</action> + <action type="fix" fixes-bug="45001" context="HWPF">Further fix for HWPF Range.delete() and unicode characters</action> + <action type="add" fixes-bug="45175" context="HWPF">Support for variable length operands in org.apache.poi.hwpf.sprm.SprmOperation</action> + <action type="fix" context="HSSF">Avoid spurious missing lines with the MissingRecordAware event code, and odd files that contain RowRecords in the middle of the cell Records</action> + <action type="add" context="HSSF">Support for parsing formulas during EventUserModel processing, via the new EventWorkbookBuilder</action> + </actions> + </release> + <release version="3.1-final" date="2008-06-29"> + <actions> + <action type="fix" fixes-bug="30978" context="HSSF">Fixed re-serialization of tRefErr3d and tAreaErr3d</action> + <action type="fix" fixes-bug="45234" context="HSSF">Removed incorrect shared formula conversion in CFRuleRecord</action> + <action type="fix" fixes-bug="45001" context="HWPF">Improved HWPF Range.replaceText()</action> + <action type="fix" fixes-bug="44692" context="HSSF">Fixed HSSFPicture.resize() to properly resize pictures if the underlying columns/rows have modified size</action> + <action type="add" context="HSLF">Support custom image renderers in HSLF</action> + <action type="fix" context="HSLF">Correctly increment the reference count of a blip when a picture is inserted</action> + <action type="fix" fixes-bug="45110" context="HSLF">Fixed TextShape.resizeToFitText() to properly resize TextShape</action> + <action type="fix" fixes-bug="45091" context="HSSF">Fixed serialization of RefN~ tokens. Simplified Ptg class hierarchy</action> + <action type="fix" fixes-bug="45133" context="HSSF">Fixed OBJ Record (5Dh) to pad the sub-record data to a 4-byte boundary</action> + <action type="fix" fixes-bug="45145" context="HSSF">Fixed Sheet to always enforce RowRecordsAggregate before ValueRecordsAggregate</action> + <action type="fix" fixes-bug="45123" context="HSSF">Fixed SharedFormulaRecord.convertSharedFormulas() to propagate token operand classes</action> + <action type="fix" fixes-bug="45087" context="HSSF">Correctly detect date formats like [Black]YYYY as being date based</action> + <action type="add" fixes-bug="45060" context="HSSF">Improved token class transformation during formula parsing</action> + <action type="add" fixes-bug="44840" context="HSSF">Improved handling of HSSFObjectData, especially for entries with data held not in POIFS</action> + <action type="add" fixes-bug="45043" context="HSSF">Support for getting excel cell comments when extracting text</action> + <action type="add" context="HSSF">Extend the support for specifying a policy to HSSF on missing / blank cells when fetching, to be able to specify the policy at the HSSFWorkbook level</action> + <action type="fix" fixes-bug="45025" context="HSSF">improved FormulaParser parse error messages</action> + <action type="fix" fixes-bug="45046" context="HSSF">allowed EXTERNALBOOK(0x01AE) to be optional in the LinkTable</action> + <action type="fix" fixes-bug="45066" context="HSSF">fixed sheet encoding size mismatch problems</action> + <action type="add" fixes-bug="45003" context="POIFS">Support embedded HDGF visio documents</action> + <action type="fix" fixes-bug="45001" context="HWPF">Partial fix for HWPF Range.insertBefore() and Range.delete() with unicode characters</action> + <action type="fix" fixes-bug="44977" context="HSSF">Support for AM/PM in excel date formats</action> + <action type="add" context="HSSF">Support for specifying a policy to HSSF on missing / blank cells when fetching</action> + <action type="add" fixes-bug="44937" context="HWPF">Partial support for extracting Escher images from HWPF files</action> + <action type="fix" fixes-bug="44824" context="HWPF">Avoid an infinite loop when reading some HWPF pictures</action> + <action type="fix" fixes-bug="44898" context="POIFS">Correctly handle short last blocks in POIFS</action> + </actions> + </release> + <release version="3.1-beta2" date="2008-05-26"> + <actions> + <action type="fix" fixes-bug="44306" context="HSSF">fixed reading/writing of AttrPtg(type=choose) and method toFormulaString() for CHOOSE formulas</action> + <action type="fix" fixes-bug="24207" context="HSSF">added HSSFName.isDeleted() to check if the name points to cell that no longer exists</action> + <action type="fix" fixes-bug="40414" context="HSSF">fixed selected/active sheet after removing sheet from workbook</action> + <action type="fix" fixes-bug="44523" context="HSSF">fixed workbook sheet selection and focus</action> + <action type="fix" fixes-bug="45000" context="HWPF">Fixed NPE in ListLevel when numberText is null</action> + <action type="fix" fixes-bug="44985" context="HSLF">Properly update TextSpecInfoAtom when the parent text is changed</action> + <action type="fix" fixes-bug="41187" context="HSSF">fixed HSSFSheet to properly read xls files without ROW records</action> + <action type="fix" fixes-bug="44950" context="HSSF">fixed HSSFFormulaEvaluator.evaluateInCell() and Area3DEval.getValue() also added validation for number of elements in AreaEvals</action> + <action type="fix" fixes-bug="42570" context="HSSF">fixed LabelRecord to use empty string instead of null when the length is zero</action> + <action type="fix" fixes-bug="42564" context="HSSF">fixed ArrayPtg to use ConstantValueParser. Fixed a few other ArrayPtg encoding issues</action> + <action type="fix" fixes-bug="28754" context="HSSF">Follow-on from 28754 - StringPtg.toFormulaString() should escape double quotes</action> + <action type="fix" fixes-bug="44929" context="POI_Overall">Improved error handling in HSSFWorkbook when attempting to read a BIFF5 file</action> + <action type="fix" fixes-bug="44675" context="HSSF">Parameter operand classes (function metadata) required to encode SUM() etc properly. Added parse validation for number of parameters</action> + <action type="fix" fixes-bug="44921" context="HSSF">allow Ptg.writeBytes() to be called on relative ref Ptgs (RefN* and AreaN*)</action> + <action type="fix" fixes-bug="44914" context="HSSF">Fix/suppress warning message "WARN. Unread n bytes of record 0xNN"</action> + <action type="fix" fixes-bug="44892" context="HSSF">made HSSFWorkbook.getSheet(String) case insensitive</action> + <action type="fix" fixes-bug="44886" context="HSSF">Correctly process PICT metafile in EscherMetafileBlip</action> + <action type="fix" fixes-bug="44893" context="HSSF">Take into account indentation in HSSFSheet.autoSizeColumn</action> + </actions> + </release> + <release version="3.1-beta1" date="2008-04-28"> + <actions> + <action type="fix" fixes-bug="44857" context="HSSF">Avoid OOM on unknown escher records when EscherMetafileBlip is incorrect</action> + <action type="add" context="HSLF">Support for getting embedded sounds from slide show </action> + <action type="add" context="HSLF">Initial support for rendering slides into images</action> + <action type="add" context="HSLF">Support for getting OLE object data from slide show </action> + <action type="add" context="HSLF">Implemented more methods in PPGraphics2D</action> + <action type="add" context="HSLF">Added Freeform shape which can contain both lines and Bezier curves</action> + <action type="fix" fixes-bug="41071" context="POI_Overall">Improved text extraction in HSLF</action> + <action type="add" fixes-bug="30311" context="HSSF">Conditional Formatting - improved API, added HSSFSheetConditionalFormatting</action> + <action type="fix" context="HSSF">Update the formula parser code to use a HSSFWorkbook, rather than the low level model.Workbook, to make things cleaner and make supporting XSSF formulas in future much easier</action> + <action type="fix" context="POIFS">Fix the logger used by POIFSFileSystem, so that commons-logging isn't required when not used</action> + <action type="add" context="HSLF">Update HSLFSlideShow and HSSFWorkbook to take advantage of POIFS updates, and allow reading embedded documents</action> + <action type="add" context="POIFS">Improve how POIFS works with directory entries, and update HWPFDocument to support reading an embedded word document</action> + <action type="add" context="HSSF">Initial support for getting and changing chart and series titles</action> + <action type="add" context="HSSF">Implement a proxy HSSFListener which tracks the format records, and lets you lookup the format string for a given cell. Convert the xls to csv example to use it</action> + <action type="fix" fixes-bug="44792" context="HSSF">fixed encode/decode problems in ExternalNameRecord and CRNRecord</action> + <action type="fix" fixes-bug="43670,44501" context="POI_Overall HDGF">Fix how HDGF deals with trailing data in the list of chunk headers</action> + <action type="add" fixes-bug="30311" context="HSSF">More work on Conditional Formatting</action> + <action type="fix" context="HSSF">refactored all junits' usage of HSSF.testdata.path to one place</action> + <action type="fix" fixes-bug="44739" context="HSSF">Small fixes for conditional formatting (regions with max row/col index)</action> + <action type="add" fixes-bug="44694" context="HPSF">HPSF: Support for property sets without sections</action> + <action type="add" context="HSLF">Implement Sheet.removeShape(Shape shape) in HSLF</action> + <action type="add" fixes-bug="44675,44695,44691" context="HSSF">Various fixes: Recognising var-arg built-in functions #<bug num="44675"/>, ExternalNameRecord serialisation bug #<bug num="44695"/>, PMT() bug #<bug num="44691"/></action> + <action type="add" fixes-bug="30311" context="HSSF">More work on Conditional Formatting</action> + <action type="add" context="HSSF">Move the Formula Evaluator code out of scratchpad</action> + <action type="add" context="HSSF">Move the missing record aware eventusermodel code out of scratchpad</action> + <action type="add" fixes-bug="44652,44603" context="HWPF">Improved handling of Pictures in Word Documents</action> + <action type="fix" fixes-bug="44636" context="HSSF">Fix formula parsing of RefVPtg, which was causing #VALUE to be shown on subsequent edits</action> + <action type="fix" fixes-bug="44627" context="POI_Overall">Improve the thread safety of POILogFactory</action> + <action type="add" fixes-bug="30311" context="HSSF">Initial support for Conditional Formatting</action> + <action type="fix" fixes-bug="44609" context="HSSF">Handle leading spaces in formulas, such as '= 4'</action> + <action type="add" fixes-bug="44608" context="HSSF">Support for PercentPtg in the formula evaluator</action> + <action type="fix" fixes-bug="44606" context="HSSF">Support calculated string values for evaluated formulas</action> + <action type="add" context="HSSF">Add accessors to horizontal and vertical alignment in HSSFTextbox</action> + <action type="add" fixes-bug="44593" context="HSSF">Improved handling of short DVRecords</action> + <action type="add" fixes-bug="28627,44580" context="HDF HWPF">Fix Range.delete() in HWPF</action> + <action type="add" fixes-bug="44539" context="HSSF">Support for area references in formulas of rows >= 32768</action> + <action type="add" fixes-bug="44536" context="HSSF">Improved support for detecting read-only recommended files</action> + <action type="fix" fixes-bug="43901" context="HSSF">Correctly update the internal last cell number when adding and removing cells (previously sometimes off-by-one)</action> + <action type="fix" fixes-bug="44504" context="HSSF">Added initial support for recognising external functions like YEARFRAC and ISEVEN (using NameXPtg), via LinkTable support</action> + <action type="fix" fixes-bug="44504" context="HSSF">Improvements to FormulaParser - operators, precedence, error literals, quotes in string literals, range checking on IntPtg, formulas with extra un-parsed stuff at the end, improved parse error handling</action> + <action type="fix" fixes-bug="44504" context="HSSF">Fixed number conversion inconsistencies in many functions, and improved RefEval</action> + <action type="fix" fixes-bug="44504" context="HSSF">Added initial support for recognising external functions like YEARFRAC and ISEVEN (using NameXPtg), via LinkTable support</action> + <action type="fix" fixes-bug="44504" context="HSSF">Improvements to FormulaParser - operators, precedence, error literals, quotes in string literals, range checking on IntPtg, formulas with extra un-parsed stuff at the end, improved parse error handling</action> + <action type="fix" fixes-bug="44504" context="HSSF">Fixed number conversion inconsistencies in many functions, and improved RefEval</action> + <action type="fix" fixes-bug="44508" context="HSSF">Fix formula evaluation with evaluateInCell on boolean formulas</action> + <action type="fix" fixes-bug="44510" context="HSSF">Fix how DVALRecord works with dropdowns</action> + <action type="fix" fixes-bug="44495" context="HSSF">Handle named cell ranges in formulas that have lower case parts</action> + <action type="fix" fixes-bug="44491" context="POI_Overall">Don't have the new-style "HPSF properties are always available" affect the old-style use of HPSF alongside HSSF</action> + <action type="fix" fixes-bug="44471" context="HSSF">Crystal Reports generates files with short StyleRecords, which isn't allowed in the spec. Work around this</action> + <action type="fix" fixes-bug="44495" context="HSSF">Handle named cell ranges in formulas that have lower case parts</action> + <action type="fix" fixes-bug="44491" context="POI_Overall">Don't have the new-style "HPSF properties are always available" affect the old-style use of HPSF alongside HSSF</action> + <action type="fix" fixes-bug="44471" context="HSSF">Crystal Reports generates files with short StyleRecords, which isn't allowed in the spec. Work around this</action> + <action type="add" fixes-bug="44450" context="HSSF">Support for Lookup, HLookup and VLookup functions</action> + <action type="fix" fixes-bug="44449" context="HSSF">Avoid getting confused when two sheets have shared formulas for the same areas, and when the shared formula is set incorrectly</action> + <action type="fix" fixes-bug="44366" context="POIFS">InputStreams passed to POIFSFileSystem are now automatically closed. A warning is generated for people who might've relied on them not being closed before, and a wrapper to restore the old behaviour is supplied</action> + <action type="add" fixes-bug="44371" context="HSSF">Support for the Offset function</action> + <action type="fix" fixes-bug="38921" context="HSSF">Have HSSFPalette.findSimilar() work properly</action> + <action type="fix" fixes-bug="44456" context="HSSF">Fix the contrib SViewer / SViewerPanel to not fail on sheets with missing rows</action> + <action type="fix" fixes-bug="44403" context="HSSF">Further support for unusual, but valid, arguments to the Mid function</action> + <action type="fix" fixes-bug="44410" context="HSSF">Support for whole-column ranges, such as C:C, in formula strings and the formula evaluator</action> + <action type="fix" fixes-bug="44421" context="HSSF">Update Match function to properly support Area references</action> + <action type="fix" fixes-bug="44417" context="HSSF">Improved handling of references for the need to quote the sheet name for some formulas, but not when fetching a sheet by name</action> + <action type="fix" fixes-bug="44413" context="HSSF">Fix for circular references in INDEX, OFFSET, VLOOKUP formulas, where a cell is actually allowed to reference itself</action> + <action type="fix" fixes-bug="44403" context="HSSF">Fix for Mid function handling its arguments wrong</action> + <action type="add" fixes-bug="44364" context="HSSF">Support for Match, NA and SumProduct functions, as well as initial function error support</action> + <action type="fix" fixes-bug="44375" context="HPSF">Cope with a broken dictionary in Document Summary Information stream. RuntimeExceptions that occured when trying to read bogus data are now caught. Dictionary entries up to but not including the bogus one are preserved, the rest is + ignored</action> + <action type="fix" fixes-bug="38641" context="HSSF">Handle timezones better with cell.setCellValue(Calendar), so now 20:00-03:00, 20:00+00:00 and 20:00+03:00 will all be recorded as 20:00, and not 17:00 / 20:00 / 23:00 (pass a Date not a Calendar for old behaviour)</action> + <action type="fix" fixes-bug="44373" context="HSSF">Have HSSFDateUtil.isADateFormat recognize more formats as being dates</action> + <action type="add" fixes-bug="37923" context="HSSF">Support for Excel hyperlinks</action> + <action type="add" context="HSSF">Implement hashCode() and equals(obj) on HSSFFont and HSSFCellStyle</action> + <action type="fix" fixes-bug="44345" context="HSSF">Implement CountA, CountIf, Index, Rows and Columns functions</action> + <action type="fix" fixes-bug="44336" context="HSSF">Properly escape sheet names as required when figuring out the text of formulas</action> + <action type="add" fixes-bug="44326" context="POI_Overall">Improvements to how SystemOutLogger and CommonsLogger log messages with exceptions, and avoid an infinite loop with certain log messages with exceptions</action> + <action type="add" context="HSSF">Support for a completed Record based "pull" stream, via org.apache.poi.hssf.eventusermodel.HSSFRecordStream, to complement the existing "push" Event User Model listener stuff</action> + </actions> + </release> + <release version="3.0.2-FINAL" date="2008-02-04"> + <actions> + <action type="fix" fixes-bug="44297" context="HSSF">IntPtg must operate with unsigned short. Reading signed short results in incorrect formula calculation</action> + <action type="fix" fixes-bug="44296" context="HSLF">Fix for reading slide background images</action> + <action type="fix" fixes-bug="44293" context="HSSF">Avoid swapping AreaPtgs from relative to absolute</action> + <action type="fix" fixes-bug="44292" context="HWPF">Correctly process the last paragraph in a word file</action> + <action type="fix" fixes-bug="44254" context="HSSF">Avoid some unread byte warnings, and properly understand DVALRecord</action> + <action type="add" context="HSSF">Add another formula evaluation method, evaluateFormulaCell(cell), which will re-calculate the value for a formula, without affecting the formula itself</action> + <action type="fix" fixes-bug="41726" context="HSSF">Fix how we handle signed cell offsets in relative areas and references</action> + <action type="add" fixes-bug="44233" context="HSSF">Support for getting and setting a flag on the sheet, which tells excel to re-calculate all formulas on it at next reload</action> + <action type="fix" fixes-bug="44201" context="HSSF">Enable cloning of sheets with data validation rules</action> + <action type="fix" fixes-bug="44200" context="HSSF">Enable cloning of sheets with notes</action> + <action type="add" fixes-bug="43008" context="HSSF">Add a moveCell method to HSSFRow, and deprecate setCellNum(), which didn't update things properly</action> + <action type="fix" fixes-bug="43058" context="HSSF">Support setting row grouping on files from CR IX, which lack GutsRecords</action> + <action type="fix" fixes-bug="31795" context="HSSF">Support cloning of sheets with certain drawing objects on them</action> + <action type="fix" fixes-bug="43902" context="HSSF">Don't consider merged regions when auto-sizing columns</action> + <action type="fix" fixes-bug="42464" context="HSSF">Avoid "Expected ExpPtg to be converted from Shared to Non-Shared Formula" on large, formula heavy worksheets</action> + <action type="add" fixes-bug="42033" context="HSSF">Add support for named ranges with unicode names</action> + <action type="add" fixes-bug="34023" context="HSSF">When shifting rows, update formulas on that sheet to point to the new location of those rows</action> + <action type="add" context="HSSF">Support getting all the cells referenced by an AreaReference, not just the corner ones</action> + <action type="add" fixes-bug="43510" context="HSSF">Add support for named ranges in formulas, including non-contiguous named ranges</action> + <action type="add" fixes-bug="43937" context="HSSF">Add support for hiding and un-hiding sheets, and checking their current hidden status</action> + <action type="fix" fixes-bug="44167" context="HSSF">Fix for non-contiguous named ranges</action> + <action type="fix" fixes-bug="44070" context="HSSF">Fix for shifting comments when shifting rows</action> + </actions> + </release> + <release version="3.0.2-BETA2" date="2008-01-12"> + <actions> + <action type="add" context="HSLF">Support for tables in HSLF</action> + <action type="fix" fixes-bug="43781" context="HSLF">Fix for extracting text from TextBoxes HSLF in</action> + <action type="fix" context="HSSF">Improve JavaDocs relating to hssf font and fill colourings</action> + <action type="add" fixes-bug="44095,44097,44099" context="HSSF">Support for Mid, Replace and Substitute excel functions</action> + <action type="add" fixes-bug="44055" context="POI_Overall">Support for getting the from field from HSMF messages</action> + <action type="add" fixes-bug="43551" context="HSSF">Support for 1904 date windowing in HSSF (previously only supported 1900 date windowing)</action> + <action type="add" fixes-bug="41064" context="POIFS">Support for String continue records</action> + <action type="add" fixes-bug="27511" context="POI_Overall">Support for data validation, via DVRecord and DVALRecord</action> + </actions> + </release> + <release version="3.0.2-BETA1" date="2007-12-04"> + <actions> + <action type="fix" fixes-bug="43877" context="HSSF">Fix for handling mixed OBJ and CONTINUE records</action> + <action type="fix" fixes-bug="39512" context="HSSF">Fix for handling mixed OBJ and CONTINUE records</action> + <action type="fix" fixes-bug="43837" context="HSSF">Support for unicode NameRecords</action> + <action type="fix" fixes-bug="43807" context="HSSF">Throw an IllegalArgumentException if asked to create a merged region with invalid columns or rows, rather than writing out a corrupt file</action> + <action type="fix" fixes-bug="43837" context="HSSF">Support for unicode NameRecords</action> + <action type="add" fixes-bug="43721" context="HSSF">Support for Chart Title Format records</action> + <action type="fix" fixes-bug="42794" context="HSSF">Fix for BOF records from things like Access</action> + <action type="fix" fixes-bug="43648" context="HSSF">Fix for IntPtg and short vs int</action> + <action type="fix" fixes-bug="43751" context="HSSF">Fix for handling rotated text in HSSFSheet.autoSizeColumn</action> + <action type="add" context="SS_Common">Include an Excel text extractor, and put all existing text extractors under a common superclass</action> + <action type="add" context="HDGF">Improvements to the LZW compression engine used by HDGF</action> + <action type="add" context="HSSF">HSSFPicture.resize() - a handy method to reset a picture to its original width and height</action> + <action type="add" context="HSSF">Add a getSheetIndex(HSSFSheet) method to HSSFWorkbook, and allow a HSSFSheet to get at its parent HSSFWorkbook</action> + <action type="add" context="HSSF">Move POIDocument out of Scratchpad, and update HSSFWorkbook to use it</action> + <action type="fix" fixes-bug="43399" context="HSSF">Fix for Cell References for rows > 32678</action> + <action type="fix" fixes-bug="43410" context="HSSF">Improved Formula Parser support for numbers and ranges</action> + <action type="add" context="HSLF">When writing HSLF files out, optionally preserve all OLE2 nodes (default is just the HSLF related nodes)</action> + <action type="add" fixes-bug="43323" context="HSLF">Support for adding Pictures to ShapeGroups in HSLF</action> + <action type="add" fixes-bug="43222" context="HSSF">Support for getting OLE object data from HSSFWorkbook</action> + <action type="add" fixes-bug="43247" context="HSLF">Support for getting OLE object data from slideshows</action> + <action type="add" fixes-bug="43125" context="HSSF">Support for reading EMF, WMF and PICT images via HSSFWorkbook.getAllPictures()</action> + <action type="fix" fixes-bug="43088" context="HSSF">Fix for reading files with long cell comments and text boxes</action> + <action type="fix" fixes-bug="42844" context="HSSF">Fix for the EventUserModel and records that aren't immediately followed by their ContinueRecords</action> + <action type="fix" fixes-bug="43055" context="HSSF">Fix for saving Crystal Reports xls files when preserving nodes</action> + <action type="fix" fixes-bug="43116" context="HSSF">Fix for Escher layer handling of embedded OLE2 documents</action> + <action type="fix" fixes-bug="43108" context="HSSF">Where permissions deny fetching System Properties, use sensible defaults</action> + <action type="fix" fixes-bug="43093" context="HSSF">Fix formula evaluator support for Area3D references to other sheets</action> + <action type="fix" context="HSSF">Improvements to HSSFDateUtils.isADateFormat, and have HSSFDateUtil.isCellDateFormatted use this</action> + <action type="fix" fixes-bug="42999" context="HSSF">Fix for HSSFPatriarch positioning problems</action> + <action type="add" context="HSSF">Support for write-protecting a HSSF workbook</action> + <action type="add" context="HSSF">Support for querying, setting and un-setting protection on sheets in a HSSF workbook</action> + <action type="add" context="HSMF">Initial HSMF (outlook) support</action> + <action type="fix" context="POI_Overall">Tidy up the javadocs</action> + </actions> + </release> + + <release version="3.0.1-FINAL" date="2007-07-05"> + <actions> + <action type="fix" context="POI_Overall">Administrative updates to the Maven POMs, and the release artifact build process</action> + <action type="fix" fixes-bug="23951" context="HSSF">Fix for HSSF setSheetOrder and tab names</action> + <action type="fix" fixes-bug="42524" context="HSLF">Better HSLF support for problem shape groups</action> + <action type="fix" fixes-bug="42520" context="HSLF">Better HSLF support for corrupt picture records</action> + <action type="add" context="HSSF">Initial support for a "missing record aware" HSSF event model</action> + <action type="add" context="HSLF">Additional HSLF support for Title and Slide Master Sheets</action> + <action type="fix" fixes-bug="42474" context="HSLF">Improved HSLF note to slide matching, and a NPE</action> + <action type="fix" fixes-bug="42481" context="HSLF">Tweak some HSLF exceptions, to make it clearer what you're catching</action> + <action type="fix" fixes-bug="42667" context="HSLF">Fix for HSLF writing of files with tables</action> + <action type="add" context="HSSF">Improved way of detecting HSSF cells that contain dates, isADateFormat</action> + <action type="add" context="HDGF">Initial, read-only support for Visio documents, as HDGF</action> + </actions> + </release> + + <release version="3.0-FINAL" date="2007-05-18"> + <actions> + <action type="fix" fixes-bug="39977" context="POI_Overall">Fix POM for Maven users</action> + <action type="fix" fixes-bug="38976" context="HSSF">Add createPicture to HSSFShapeGroup</action> + <action type="add" context="OOXML">Detect Office 2007 XML documents, and throw a meaningful exception</action> + <action type="add" context="HSLF">Additional HSLF support for PowerPoint</action> + <action type="add" context="HWPF">Initial support for HWPF image extraction</action> + </actions> + </release> + + <release version="3.0-alpha3" date="2006-12-12"> + <actions> + <action type="add" context="HSLF">Additional HSLF support for PowerPoint</action> + </actions> + </release> + + <release version="3.0-alpha2" date="2006-06-16"> + <actions> + <action type="add" context="HSSF">HSSF Formula support</action> + <action type="add" context="HSLF">Additional HSLF support for PowerPoint</action> + <action type="fix" fixes-bug="39389" context="HSSF">Extended Ascii support for WingDings</action> + </actions> + </release> + + <release version="3.0-alpha1" date="2005-06-04"> + <actions> + <action type="fix" context="HSSF">Bugzilla Bug 29976 HSSF hyperlink formula size problem</action> + <action type="add" context="HSSF">Image writing support</action> + <action type="add" context="HSLF">HSLF - Initial PowerPoint Support. Includes: Support for text extraction across the whole file; Support for getting individual slides, and their notes, and extracting text from those; Initial support for changing (but not adding) text</action> + </actions> + </release> + +</changes> diff --git a/src/documentation/content/xdocs/devel/history/changes-pre3x.xml b/src/documentation/content/xdocs/devel/history/changes-pre3x.xml new file mode 100644 index 0000000000..2068fcbb15 --- /dev/null +++ b/src/documentation/content/xdocs/devel/history/changes-pre3x.xml @@ -0,0 +1,326 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE changes PUBLIC "-//APACHE//DTD Changes POI//EN" "changes-poi.dtd"> + +<changes> + <contexts> + <context id="OOXML" title="OOXML"/> + <context id="OPC" title="OPC"/> + <context id="POI_Overall" title="POI Overall"/> + <context id="HSSF" title="Horrible SpreadSheet Format"/> + <context id="XSSF" title="ooXml SpreadSheet Format"/> + <context id="SXSSF" title="Streaming ooXml SpreadSheet Format"/> + <context id="SS_Common" title="SpreadSheet Common"/> + <context id="HSLF" title="Horrible SlideShow Format"/> + <context id="XSLF" title="ooXml SlideShow Format"/> + <context id="SL_Common" title="SlideShow Common"/> + <context id="HWPF" title="Horrible WordProcessor Format"/> + <context id="XWPF" title="ooXml WordProcessor Format"/> + <context id="HDF" title="Horrible Document Format"/> + <context id="HPSF" title="Horrible PropertySet Format"/> + <context id="HDGF" title="Horrible Dreadful Graph Format"/> + <context id="XDGF" title="ooXml Dreadful Graph Format"/> + <context id="DDF" title="Dreadful Drawing Format"/> + <context id="XDDF" title="ooXml Dreadful Drawing Format"/> + <context id="HMEF" title="Horrible Mail Encoder Format"/> + <context id="HSMF" title="Horrible Senseless Format"/> + <context id="HPBF" title="Horrible Peep Book Format"/> + <context id="HWMF" title="Horrible Wannabe Metafile Format"/> + <context id="HEMF" title="Horrible Ermahgerd Metafile Format"/> + <context id="POIFS" title="Poor Obfuscation Implementation FileSystem"/> + </contexts> + + <section id="current_release"> + <title>Current releases</title> + <p>The change log for the <a href="site:changes">current release</a> can be found in the home section.</p> + </section> + + + <release version="2.5.1-FINAL" date="2004-02-29"> + <actions> + <action type="add" context="HSSF">Outlining support</action> + <action type="fix" fixes-bug="27574" context="HSSF">HSSFDateUtil.getExcelDate() is one hour off when DST changes</action> + <action type="fix" fixes-bug="26465" context="HSSF">wrong lastrow entry</action> + <action type="fix" fixes-bug="28203" context="HSSF">Unable to open read-write excel file including forms</action> + </actions> + </release> + + <release version="2.5-FINAL" date="2004-02-29"> + <actions> + <action type="add" context="DDF">Add support for the Escher file format</action> + <action type="fix" fixes-bug="27005" context="HSSF">java.lang.IndexOutOfBoundsException during Workbook.cloneSheet()</action> + </actions> + </release> + + <release version="2.0-FINAL" date="2004-01-26"> + <actions> + <action type="update" context="POI_Overall">No changes</action> + </actions> + </release> + + <release version="2.0-RC2" date="2004-01-11"> + <actions> + <action type="fix" fixes-bug="25695" context="HSSF">HSSFCell.getStringCellValue() on cell which has string formula will return swap bye unicode characters</action> + <action type="fix" context="POI_Overall">Updated website for upcoming release</action> + <action type="fix" fixes-bug="25457" context="HSSF">Formula Parser fixes with tests, by Peter M Murray Bug 25457</action> + <action type="fix" context="HSSF">Fixed cloning merge regions</action> + <action type="fix" context="HSSF">The cloned reference for merged cells did not create a new collection, so deletes cascaded to the original</action> + <action type="fix" fixes-bug="24519" context="HSSF">Call to getCustomPalette() from a newly created workbook now works</action> + <action type="fix" fixes-bug="24397" context="POI_Overall">Some compilation got ambiguous classes. Explicitly imports the classes. Patch supplied by Jean-Pierre Paris</action> + </actions> + </release> + + <release version="2.0-RC1" date="2003-11-02"> + <actions> + <action type="fix" fixes-bug="12561" context="HSSF" importance="minor">HSSFWorkbook throws Exceptions</action> + <action type="fix" fixes-bug="12730" context="HSSF" importance="normal">values dont get copied to another sheet</action> + <action type="fix" fixes-bug="13224" context="POI_Overall" importance="major">Exception thrown when cell has =Names call</action> + <action type="fix" fixes-bug="13796" context="HSSF" importance="normal">Error Reading Formula Record (optimized if, external link)</action> + <action type="fix" fixes-bug="13921" context="HSSF" importance="normal">Sheet name cannot exceed 31 characters and cannot contain :</action> + <action type="fix" fixes-bug="14330" context="HSSF" importance="normal">Error reading FormulaRecord</action> + <action type="fix" fixes-bug="14460" context="HSSF" importance="normal">Name in Formula - ArrayOutOfBoundsException</action> + <action type="fix" fixes-bug="15228" context="HSSF" importance="critical">ArrayIndexoutofbounds Exception. POI - Version 1.8</action> + <action type="fix" fixes-bug="16488" context="HSSF" importance="major">Unable to open written spreadsheet in Excel, but can in Open</action> + <action type="fix" fixes-bug="16559" context="HSSF" importance="normal">testCustomPalette.xls crashes Excel 97</action> + <action type="fix" fixes-bug="16560" context="HSSF" importance="normal">testBoolErr.xls crashes Excel '97</action> + <action type="fix" fixes-bug="17374" context="HSSF" importance="minor">HSSFFont - BOLDWEIGHT_NORMAL</action> + <action type="fix" fixes-bug="18800" context="HSSF" importance="major">The sheet made by HSSFWorkbook#cloneSheet() doesn't work cor</action> + <action type="fix" fixes-bug="18846" context="POI_Overall" importance="minor">[RFE]Refactor the transformation between byte array a</action> + <action type="fix" fixes-bug="19599" context="HSSF" importance="minor">java.lang.IllegalArgumentException</action> + <action type="fix" fixes-bug="19961" context="HSSF" importance="normal">Sheet.getColumnWidth() returns wrong value</action> + <action type="fix" fixes-bug="21066" context="HSSF" importance="blocker">Can not modify a blank spreadsheet</action> + <action type="fix" fixes-bug="21444" context="HSSF" importance="enhancement">Macro functions</action> + <action type="fix" fixes-bug="21447" context="HSSF" importance="normal">[RFE]String Formula Cells</action> + <action type="fix" fixes-bug="21674" context="HSSF" importance="enhancement">Documentation changes for @(Greater|Less|Not)EqualPt</action> + <action type="fix" fixes-bug="21863" context="POI_Overall" importance="enhancement">build.xml fixes</action> + <action type="fix" fixes-bug="22195" context="POIFS" importance="normal">[RFE] Support for Storage Class ID</action> + <action type="fix" fixes-bug="22742" context="HSSF" importance="critical">Failed to create HSSFWorkbook!</action> + <action type="fix" fixes-bug="22922" context="HSSF" importance="critical">HSSFSheet.shiftRows() throws java.lang.IndexOutOfBoundsExcep</action> + <action type="fix" fixes-bug="22963" context="HPSF" importance="normal">org.apache.poi.hpsf.SummaryInformation.getEditTime() should</action> + <action type="fix" fixes-bug="24149" context="POIFS" importance="major">Error passing inputstream to POIFSFileSystem</action> + <action type="fix" fixes-bug="21722" context="HSSF" importance="normal">Add a ProtectRecord to Sheets and give control over</action> + <action type="fix" fixes-bug="9576" context="HSSF" importance="normal">DBCELL, INDEX EXTSST (was Acess 97 import)</action> + <action type="fix" fixes-bug="13478" context="POIFS" importance="blocker">[RFE] POIFS, RawDataBlock: Missing workaround for lo</action> + <action type="fix" fixes-bug="14824" context="HSSF" importance="normal">Unable to modify empty sheets</action> + <action type="fix" fixes-bug="12843" context="HSSF" importance="critical">Make POI handle chinese better</action> + <action type="fix" fixes-bug="15353" context="HSSF" importance="normal">[RFE] creating a cell with a hyperlink</action> + <action type="fix" fixes-bug="15375" context="HSSF" importance="blocker">Post 1.5.1 POI causes spreadsheet to become unopenable</action> + </actions> + </release> + + <release version="2.0-pre3" date="2003-07-29"> + <actions> + <action type="add" context="HPSF">HPSF is now able to read properties which are given in the property set stream but which don't have a value ("variant" type VT_EMPTY). The getXXX() methods of the PropertySet class return null if their return type is a reference (like a string) or 0 + if the return type is numeric. Details about the return types and about how to distinguish between a property value of zero and a property value that is not present can be found in the API documentation</action> + <action type="fix" context="HSSF">Gridlines can now be turned on and off</action> + <action type="fix" context="HSSF">NamePTG refactoring/fixes</action> + <action type="fix" context="HSSF">minor fixes to ExternSheet and formula strings</action> + <action type="fix" context="HSSF">Sheet comparisons now ignore case</action> + </actions> + </release> + + <release version="2.0-pre2" date="2003-07-06"> + <actions> + <action type="fix" context="HSSF">A nasty concurrency problem has been fixed. Any users working in a multithreaded environment should seriously consider upgrading to this release</action> + <action type="update" context="HSSF">The EXTSST record has been implemented. This record is used by excel for optimized reading of strings</action> + <action type="update" context="HSSF">When rows are shifted, the merged regions now move with them. If a row contains 2 merged cells, the resulting shifted row should have those cells merged as well</action> + <action type="fix" context="HSSF">There were some issues when removing merged + regions (specifically, removing all of them and then adding some more) and have been resolved. + </action> + <action type="fix" context="HSSF">When a sheet contained shared formulas (when a formula is + dragged across greater than 6 cells), the clone would fail. We now support cloning of + sheets that contain this Excel optimization. + </action> + <action type="add" context="HSSF">Support added for reading formulas with UnaryPlus and UnaryMinus operators</action> + </actions> + </release> + <release version="2.0-pre1" date="2003-05-17"> + <actions> + <action type="add" context="HSSF">Patch applied for deep cloning of worksheets was provided</action> + <action type="add" context="HSSF">Patch applied to allow sheet reordering</action> + <action type="add" context="HSSF">Added additional print area setting methods using row/column numbers</action> + <action type="fix" context="HDF">Negative Array size fix</action> + <action type="update" context="HSSF">Added argument pointers to support the IF formula</action> + <action type="update" context="HSSF">Formulas: Added special character support for string literals, specifically for SUMIF formula support and addresses a bug as well</action> + <action type="fix" context="POIFS">BlockingInputStream committed to help ensure reads</action> + <action type="fix" context="HSSF">Fixed problem with NaN values differing from the investigated value from file reads in FormulaRecords</action> + <action type="fix" context="HSSF">Patch for getColumnWidth in HSSF</action> + <action type="add" context="HDF">Patch for dealing with mult-level numbered lists in HDF</action> + <action type="fix" context="HSSF">Due to named reference work, several named-ranged bugs were closed</action> + <action type="fix" context="HSSF">Patch applied to prevent sheet corruption after a template modification</action> + <action type="update" context="HSSF">Shared Formulas now Supported</action> + <action type="update" context="HSSF">Added GreaterEqual, LessEqual and NotEqual to Formula Parser</action> + <action type="update" context="HSSF">Added GreaterThan and LessThan functionality to formulas</action> + <action type="fix" context="POI_Overall">Patches for i10n</action> + <action type="update" context="POI_Overall">POI Build System Updated</action> + <action type="fix" context="HSSF">font names can now be null</action> + </actions> + </release> + <release version="1.10-dev" date="2003-02-19"> + <actions> + <action type="add" context="HSSF">Support for zoom level</action> + <action type="add" context="HSSF">Freeze and split pane support</action> + <action type="add" context="HSSF">Row and column headers on printouts</action> + </actions> + </release> + <release version="1.8-dev" date="2002-09-20"> + <actions> + <action type="add" context="HSSF">Custom Data Format Support</action> + <action type="add" context="HSSF">Enhanced Unicode Support for Russian and Japanese</action> + <action type="add" context="HSSF">Enhanced formula support including read-only for + "optimized if" statements. + </action> + <action type="add" context="HSSF">Support for cloning objects</action> + <action type="add" context="HSSF">Fixes for header/footer</action> + <action type="add" context="POI_Overall">Spanish Documentation translations</action> + <action type="add" context="HSSF">Support for preserving VBA macros</action> + </actions> + </release> + <release version="1.7-dev" date="Release date not recorded"> + <actions> + <action type="update" context="POI_Overall">Removed runtime dependency on commons logging</action> + <action type="update" context="HSSF">Formula support</action> + </actions> + </release> + <release version="1.5.1" date="2002-06-16"> + <actions> + <action type="update" context="POI_Overall">Removed depedency on commons logging. Now define poi.logging system property to enable logging to standard out</action> + <action type="fix" context="HSSF">Fixed SST string handling so that spreadsheets with rich text or extended text will be read correctly</action> + </actions> + </release> + <release version="1.5" date="2002-05-06"> + <actions> + <action type="update" context="POI_Overall">New project build</action> + <action type="update" context="POI_Overall">New project documentation system based on Cocoon</action> + <action type="update" context="POI_Overall">Package rename</action> + <action type="fix" context="POI_Overall">Various bug fixes</action> + <action type="add" context="HSSF">Early stages of HSSF development (not ready for development)</action> + <action type="add" context="HSSF">Initial low level record support for charting (not complete)</action> + </actions> + </release> + <release version="1.2.0" date="2002-01-19"> + <actions> + <action type="update" context="POI_Overall">Changes not recorded</action> + </actions> + </release> + <release version="1.1.0" date="2002-01-04"> + <actions> + <action type="update" context="HSSF">Created new event model</action> + <action type="update" context="HSSF">Optimizations made to HSSF including aggregate records for values, rows, etc.</action> + <action type="update" context="POI_Overall">predictive sizing, offset based writing (instead of lots of array copies)</action> + <action type="update" context="POI_Overall">minor re-factoring and bug fixes</action> + </actions> + </release> + <release version="1.0.2" date="2002-01-11"> + <actions> + <action type="update" context="POI_Overall">Changes not recorded</action> + </actions> + </release> + <release version="1.0.1" date="2002-01-04"> + <actions> + <action type="update" context="POI_Overall">Changes not recorded</action> + </actions> + </release> + <release version="1.0.0" date="2001-12-30"> + <actions> + <action type="update" context="POI_Overall">Minor documentation updates</action> + </actions> + </release> + <release version="0.14.0" date="2001-12-22"> + <actions> + <action type="update" context="HSSF">Added DataFormat helper class and exposed set and get format on HSSFCellStyle</action> + <action type="update" context="HSSF">Fixed column width apis (unit wise) and various javadoc on the subject</action> + <action type="update" context="HSSF">Fix for Dimensions record (again)... (one of these days I'll write a unit test for this ;-p).</action> + <action type="update" context="HSSF">Some optimization on sheet creation</action> + </actions> + </release> + <release version="0.13.0" date="2001-12-16"> + <actions> + <action type="update" context="POI_Overall">Changes not recorded</action> + </actions> + </release> + <release version="0.12.0" date="2001-12-12"> + <actions> + <action type="update" context="HSSF">Added MulBlank, Blank, ColInfo</action> + <action type="update" context="POI_Overall">Added log4j facility and removed all sys.out type logging</action> + <action type="update" context="HSSF">Added support for adding font's, styles and corresponding high level api for styling cells</action> + <action type="update" context="HSSF">added support for changing row height, cell width and default row height/cell width.</action> + <action type="update" context="HSSF">Added fixes for internationalization (UTF-16 should work now from HSSFCell.setStringValue, etc when the encoding is set)</action> + <action type="update" context="HSSF">added support for adding/removing and naming sheets</action> + </actions> + </release> + <release version="0.11.0" date="2001-12-08"> + <actions> + <action type="update" context="HSSF">Bugfix release. We were throwing an exception when reading RKRecord objects.</action> + </actions> + </release> + <release version="0.10.0" date="2001-12-02"> + <actions> + <action type="update" context="HSSF">Got continuation records to work (read/write)</action> + <action type="update" context="HSSF">Added various pre-support for formulas</action> + <action type="update" context="POI_Overall">Massive API reorganization, repackaging</action> + <action type="update" context="POI_Overall">Better API support for modification</action> + </actions> + </release> + <release version="0.7 (and interim releases)" date="2001-11-17"> + <actions> + <action type="update" context="HSSF">Added encoding flag to high and low level api to use utf-16 + when needed (HSSFCell.setEncoding()) + </action> + <action type="update" context="HSSF">added read only support for Label records (which are + reinterpreted as LabelSST when written) + </action> + <action type="update" context="HSSF">Broken continuation record implementation (oops)</action> + <action type="update" context="POIFS HSSF">BiffViewer class added for validating POI and/or HSSF Output.</action> + </actions> + </release> + <release version="0.6" date="2001-11-11"> + <actions> + <action type="update" context="POIFS">Support for read/write and modify</action> + <action type="update" context="HSSF">Read only support for MulRK records (converted to Number when writing)</action> + </actions> + </release> + <release version="0.5" date="2001-11-05"> + <actions> + <action type="update" context="POI_Overall">Changes not recorded</action> + </actions> + </release> + <release version="0.4" date="2001-10-31"> + <actions> + <action type="update" context="POI_Overall">Changes not recorded</action> + </actions> + </release> + <release version="0.3" date="2001-10-26"> + <actions> + <action type="update" context="POI_Overall">Changes not recorded</action> + </actions> + </release> + <release version="0.2" date="2001-09-24"> + <actions> + <action type="update" context="POI_Overall">Changes not recorded</action> + </actions> + </release> + <release version="0.1" date="2001-08-28"> + <actions> + <action type="update" context="POI_Overall">First ever public release</action> + </actions> + </release> + +</changes> diff --git a/src/documentation/content/xdocs/devel/history/index.xml b/src/documentation/content/xdocs/devel/history/index.xml new file mode 100644 index 0000000000..e3b31b83d5 --- /dev/null +++ b/src/documentation/content/xdocs/devel/history/index.xml @@ -0,0 +1,163 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - Project History</title> + <authors> + <person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/> + </authors> + </header> + + <body> + + <section><title>Apache POI™ - The name</title> + <p>Refer to the <a href="https://en.wikipedia.org/wiki/Apache_POI#History_and_roadmap">explanation on Wikipedia</a> + for some folklore about how the name "POI" came into existence. + </p> + </section> + + <section><title>Apache POI™ - Brief Project History</title> + + <p>The POI project was dreamed up back around April 2001, when + Andrew Oliver landed a short term contract to do Java-based + reporting to Excel. He'd done this project a few times before + and knew right where to look for the tools he needed. + Ironically, the API he used to use had skyrocketed from around + $300 ($US) to around $10K ($US). He figured it would take two + people around six months to write an Excel port so he + recommended the client fork out the $10K. + </p> + + <p>Around June 2001, Andrew started thinking how great it would + be to have an open source Java tool to do this and, while he + had some spare time, he started on the project and learned + about OLE 2 Compound Document Format. After hitting some real + stumpers he realized he'd need help. He posted a message to + his local Java User's Group (JUG) and asked if anyone else + would be interested. He lucked out and the most talented Java + programmer he'd ever met, Marc Johnson, joined the project. He + ran rings around Andrew at porting OLE 2 CDF and rewrote his + skeletal code into a more sophisticated library. It took Marc + a few iterations to get something they were happy with. + </p> + + <p>While Marc worked on that, Andrew ported XLS to Java, based + on Marc's library. Several users wrote in asking to read XLS + (not just write as had originally been planned) and one user + had special requests for a different use for POIFS. Before + long, the project scope had tripled. POI 1.0 was released a + month later than planned, but with far more features. Marc + quickly wrote the serializer framework and HSSF Serializer in + record time and Andrew banged out more documentation and worked + on making people aware of the project + </p> + + <p> Shortly before the release, POI was fortunate to come into + contact with Nicola -Ken- Barrozzi who gave them samples for + the HSSF Serializer and help uncover its unfortunate bugs + (which were promptly fixed). More recently, Ken ported most + of the POI project documentation to XML from Andrew's crappy + HTML docs he wrote with Star Office. + </p> + + <p> Around the same time as the release, Glen Stampoultzis + joined the project. Glen was ticked off at Andrew's flippant attitude + towards adding graphing to HSSF. Glen got so ticked off he decided to + grab a hammer and do it himself. Glen has already become an integral + part of the POI development community; his contributions to HSSF have + already started making waves. + </p> + + <p>Somewhere in there we decided to finally submit the project + to <a href="https://cocoon.apache.org/">The Apache + Cocoon Project</a>, only to discover the project had + outgrown fitting nicely into just Cocoon long ago. + Furthermore, Andrew started eyeing other projects he'd like to + see POI functionality added to. So it was decided to donate + the Serializers and Generators to Cocoon, other POI + integration components to other projects, and the POI APIs + would become part of Jakarta. It was a bumpy road but it + looks like everything turned out since you're reading this! + </p> + + <p>In Early 2007, we graduated from + <a href="https://jakarta.apache.org/">Jakarta</a>, and became + our own Top Level Project (TLP) within Apache.</p> + </section> + +<!-- + <section><title>What's next for Poi</title> + <p>First we'll tackle this from a project standpoint: Well, we + made an offer to Microsoft and Actuate (tongue in cheek + ... well mostly) that we'd quit the project and retire if + they'd simply write us each a really large check. I've yet to + get a phone call or email so I'm assuming they're not going to + pay us to go away. + </p> + <p>Next, we've got some work to do here at Jakarta to finish + integrating POI into the community. Furthermore, we're + still transitioning the Serializer to Cocoon. + </p> + <p>HSSF, during the 2.0 cycle, will undergo a few + optimizations. We'll also be adding new features like a full + implementation of Formulas and custom text formats. We're + hoping to be able to generate smaller files by adding + write-support for RK, MulRK and MulBlank records. I'm also + going to work on a Cocoon 2 Generator. Currently, reading is + not very efficient in HSSF. This is mainly because in order to + write or modify, one needs to be able to update upstream + pointers to downstream data. To do this you have to have + everything between in memory. A Generator would allow SAX + events to be processed instead. (This will be based on the low + level structures). One of the great things about this is that, + you'll not only have a more efficient way to read the file, + you'll have a great way to use spreadsheets as XML data + sources. + </p> + <p>The HSSF Serializer, will further separate into a general + framework for creating serializers for other formats and the + HSSF Serializer specific implementation. (This is largely + already true). We'll also be adding support for features + already supported by HSSF (styles, fonts, text formats). We're + hoping to add support for formulas during this cycle. + </p> + <p>We're beginning to expand our scope yet again. If we could + do all of this for XLS files, what about Doc files or PowerPoint + files? We're thinking that our next component (HWPF - Manipulates + Word Processor Format) should follow the same pattern. We're hoping + that new blood will join the team and allow us to tackle this + even faster (in part because POIFS is already finished). But + maybe what we need most is you! </p> + </section> --> + + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> + + +</document> diff --git a/src/documentation/content/xdocs/devel/index.xml b/src/documentation/content/xdocs/devel/index.xml new file mode 100644 index 0000000000..4b3acd2783 --- /dev/null +++ b/src/documentation/content/xdocs/devel/index.xml @@ -0,0 +1,168 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - How To Build</title> + <authors> + <person email="user@poi.apache.org" name="Glen Stampoultzis" id="GS"/> + <person email="tetsuya@apache.org" name="Tetsuya Kitahata" id="TK"/> + <person email="dfisher@jmlafferty.com" name="David Fisher" id="DF"/> + </authors> + </header> + <body> + <section> + <title>JDK Version</title> + <p> + POI 4.0 and later require JDK version 1.8 or later. JDK version 11 is required to compile module support. + </p> + <p> + POI 3.11 and later 3.x versions require JDK version 1.6 or later. + </p> + <p> + POI 3.5 to 3.10 required the JDK version 1.5 or later. + Versions prior to 3.5 required JDK 1.4+. + </p> + </section> + <section> + <title>Install Apache Forrest</title> + <p> + The POI build system requires + <a href="https://forrest.apache.org/">Apache Forrest</a> + to build the documentation. + </p> + <p> + Specifically, the build has been tested to work with Forrest 0.9. When building with Forrest, + it is recommended to use Java 8. + </p> + <p> + Remember to set the FORREST_HOME environment variable. + </p> + </section> + <section> + <title>Building Targets with Gradle</title> + <p> + The main Apache POI build was traditionally done with <a href="https://ant.apache.org/">Apache Ant</a>. + In 2021, we moved to using <a href="https://gradle.org/">Gradle</a>. + After <a href="git.html">checking out</a> the POI code, you will find <strong>gradlew</strong> and + <strong>gradlew.bat</strong>. These command files are used for running Gradle on Linux/Mac and Windows respectively. + Gradlew checks if you the right version of Gradle installed and will install it if you don't. + </p> + <p> + Note that our source releases no longer contain gradlew or gradlew.bat. You can install the Gradle tool + yourself and use it to build POI. + </p> + <p> + The main targets of interest to our users are: + </p> + <table> + <tr> + <th>Gradle Target</th> + <th>Description</th> + </tr> + <tr> + <td>clean</td> + <td>Erase all build work products (ie. everything in the + build directory</td> + </tr> + <tr> + <td>test</td> + <td>Run all unit tests from main, ooxml and scratchpad</td> + </tr> + <tr> + <td>jar</td> + <td>Produce jar files</td> + </tr> + <tr> + <td>jenkins</td> + <td> + Runs the tests which Jenkins, our Continuous Integration system, does. This includes the unit tests and various code quality checks. + Also, packages up the jars and build distributions. + </td> + </tr> + </table> + <p> + To run the tests from just one test class, use a command like: + </p> + <p> + ./gradlew poi-ooxml:test --tests *TestXSSFBugs + </p> + <p> + gradlew poi-ooxml:test --tests *TestXSSFBugs + </p> + <p> + The example command runs tests in the poi-ooxml sub-project that match the name '*TestXSSFBugs'. + The '*' wildcard is useful to avoid typing the full Java package name. + </p> + </section> + <section> + <title>Working with Eclipse</title> + <p> + Apache POI no longer includes a pre-defined Eclipse project file. When importing the POI project, + your IDE should recognise that there is Gradle support and offer to do the build using that. + </p> + <p> + First make sure that Java is set up properly and that you can execute the 'javac' executable in your shell. + </p> + <p> + Next, open Eclipse and create a copy of the Git repository, + and import the project into Eclipse. + </p> + <p> + Note: when executing junit tests from within Eclipse, you might need to set the system + property "POI.testdata.path" to the actual location of the 'test-data' directory to make + the test framework find the required test-files. A simple value of 'test-data' usually works. + </p> + </section> + <section> + <title>Working with IntelliJ Idea</title> + <p> + Import the Gradle project into your IDE. Execute a build to get all the dependencies and generated code + in place. + </p> + <p> + Note: when executing junit tests from within IntelliJ, you might need to set the system + property "POI.testdata.path" to the actual location of the 'test-data' directory to make + the test framework find the required test-files. A simple value of 'test-data' usually works. + </p> + </section> + <section> + <title>Setting environment variables</title> + <p>Linux: + <a href="https://help.ubuntu.com/community/EnvironmentVariables">help.ubuntu.com</a>, + <a href="http://unix.stackexchange.com/questions/117467/how-to-permanently-set-environmental-variables">unix.stackexchange.com</a> + </p> + <p>Windows: + <a href="https://en.wikipedia.org/wiki/Environment_variable#DOS.2C_OS.2F2_and_Windows">en.wikipedia.org</a> + </p> + </section> + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> + + diff --git a/src/documentation/content/xdocs/devel/nightly.xml b/src/documentation/content/xdocs/devel/nightly.xml new file mode 100644 index 0000000000..cbc29e2cc4 --- /dev/null +++ b/src/documentation/content/xdocs/devel/nightly.xml @@ -0,0 +1,57 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - Nightly Builds</title> + </header> + <body> + <section id="nightly"> + <title>Nightly Builds</title> + <p>The POI nightly builds are run on the <a href="https://ci-builds.apache.org/job/POI/">Jenkins</a> + continuous integration server.<br/> + <strong>These builds should not be used in production</strong>: they are mostly intended for use by + developers to help with resolving bugs and evaluating new features or users who want to try out the + latest version. + </p> + <ul> + <li> + <a href="https://ci-builds.apache.org/job/POI/job/POI-DSL-1.8/lastSuccessfulBuild/artifact/build/dist/"> + Last Successful Jenkins build for POI-trunk + </a> + </li> + <li> + <a href="https://sonarcloud.io/dashboard?id=poi-parent">Sonar statistics for the nightly</a> + </li> + </ul> + </section> + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> + + diff --git a/src/documentation/content/xdocs/devel/plan/index.xml b/src/documentation/content/xdocs/devel/plan/index.xml new file mode 100644 index 0000000000..f68075670e --- /dev/null +++ b/src/documentation/content/xdocs/devel/plan/index.xml @@ -0,0 +1,74 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Planning Documentation</title> + <subtitle>Overview</subtitle> + <authors> + <person name="David Crossley" email="crossley@apache.org"/> + <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/> + </authors> + </header> + + <body> + <section><title>Overview</title> + + <p>This is a collection of notes to assist with long-term planning and + development. + </p> + + <p>There is much discussion of issues and research topics (RT) threads on + the <code>dev</code> mailing list (and elsewhere). However, details + get lost in the sheer volume. This is the place to document the summary of + discussions on some key topics. Some new and complex capabilities will take + lots of design and specification before they can be implemented. + </p> + + <p>Another use for this collection of notes is as a place to quickly store + a snippet from an email discussion or even a link to a discussion thread. + The concepts can then be fleshed-out over time. + </p> + + <p>Anyone can participate in this process. Please get involved in discussion + on <code>dev</code> and contribute patches for these summary planning + documents via the normal <a href="site:guidelines">contribution</a> + process. + </p> + + <p>These planning documents are intended to be concise notes only. They are + also ever-evolving, because as issues are addressed these notes will be + revised. + </p> + </section> + + <section><title>Topics and Issues</title> + + <ul> + <li><a href="site:vision20">POI Version 2.0 Vision</a> + </li> + <li><a href="site:vision10">POI Version 1.0 Vision</a> + </li> + </ul> + </section> + + </body> +</document> diff --git a/src/documentation/content/xdocs/devel/plan/vision10.xml b/src/documentation/content/xdocs/devel/plan/vision10.xml new file mode 100644 index 0000000000..40c9a791b1 --- /dev/null +++ b/src/documentation/content/xdocs/devel/plan/vision10.xml @@ -0,0 +1,521 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>POI 1.0 Vision Document</title> + <authors> + <person name="Andrew C. Oliver" email="acoliver@apache.org"/> + <person name="Marcus W. Johnson" email="mjohnson@apache.org"/> + </authors> + </header> + + <body> + + <section><title>Preface</title> + <p> + (21-Jan-02) While this document is just full of useful project + introductory information and I do suggest those interested in getting + involved in the project read it, it is woefully out of date. + </p> + <p> + We deliberately allowed this document to run out of date because it + is a good reflection of what the original vision was for POI 1.0. + You'll note that some of the terminology is not used in quite the same + way any longer. I've made some minor corrections where reading this + confused me. An example: in some places this document may refer to + POI API instead of POIFS API. When this vision was written we had + an incomplete understanding of the project. + </p> + <p> + Lastly, the scope of the project expanded dramatically near the end + of the 1.0 cycle. Our vision at the time was to focus merely on the + Excel port (having no idea how the project would grow or be received) + and provide the OLE 2 Compound Document port for others to port later + formats. We now plan to spearhead these ports under the umbrella of + the POI project. So, you've been warned. Read on, but just realize + that we had a fuzzy view of things to come, and hindsight is 20-20. + </p> + <p> + If I recall major holes were: a complete understanding of the format + of OLE 2 Compound Document format, Excel file format, and exactly how + Cocoon 2 Serializers worked. (that just about covers the whole range + huh?) + </p> + </section> + + <section><title>1. Introduction</title> + <section><title>1.1 Purpose of this document</title> + <p> + The purpose of this document is to + collect, analyze and define high-level requirements, user needs and + features of the HSSF Serializer for Cocoon 2 and related libraries. + The HSSF Serializer is a java class supporting the Serializer + interface from the Cocoon 2 project and outputting in a compatible + format of that used by the spreadsheet program Microsoft Excel '97. + The HSSF Serializer will be responsible for converting XML + spreadsheet-like documents into Excel-compatible XLS spreadsheets. + </p> + </section> + + + <section><title>1.2 Project Overview</title> + <p> + Many web apps today hit a brick wall + when it comes to the user request that they be able to easily + manipulate their reports and data extracts in the popular Microsoft + Excel spreadsheet format. This often causes inferior technologies to be + chosen for the project simply because they easily support this + format. This project seeks to extend existing XML, Java and Apache + Cocoon 2 project technologies by: + </p> + + <ul> + <li> + providing an extensible library + (POIFS) which reads/writes in a compatible format to OLE 2 Compound + Document Format (aka Structured Storage Format) for easy + implementation of other document types; + </li> + <li> + providing a library (HSSF) for + manipulating spreadsheet data and outputting it in a compatible + format to Microsoft Excel XLS format; + </li> + <li> + and providing a Cocoon 2 + Serializer (HSSFSerializer) for serializing XML documents as + Excel-compatible spreadsheets. + </li> + </ul> + + </section> + </section> + <section><title>2. User Description</title> + <section><title>2.1 User/Market Demographics</title> + <p> + There are a number of enthusiastic + users of XML, UNIX and Java technology. Secondly, the Microsoft + solution for outputting Office Document formats often involves + actually manipulating the software as an OLE Server. This method + provides extremely low performance, extremely high overhead and is + only capable of handling one document at a time. + </p> + <ol> + <li> + Our intended audience for the HSSF + Serializer portion of this project are developers writing reports or + data extracts in XML format. + </li> + <li> + Our intended audience for the HSSF + library portion of this project is ourselves as we are developing + the Serializer and anyone who needs to write to Excel spreadsheets + in a non-XML Java environment or who has specific needs not + addressed by the Serializer. + </li> + <li> + Our intended audience for the + "POIFS" OLE 2 Compound Document format reader/writer is + ourselves as we are writing the HSSF library and secondly, anyone + wishing to provide other libraries for reading/writing OLE 2 + Compound Document Format in Java. + </li> + </ol> + </section> + <section><title>2.2. User environment</title> + <p> + The users of this software shall be + developers in a Java environment on any Operating System or power + users who are capable of XML document generation/deployment. + </p> + </section> + <section><title>2.3. Key User Needs</title> + <p> + The OLE 2 Compound Document format is + undocumented for all practical purposes and cryptic for all + impractical purposes. Developer needs in this area include + documentation and an easy to use library for reading and writing in + this format without requiring the developer to have intimate + knowledge of the format. + </p> + <p> + There is currently no good way to write + to Microsoft Excel documents from Java or from a non-Microsoft + Windows based platform for that matter. Developers need an easy to + use library that supports a reasonable feature set and allows + separation of data from formatting/stylistic concerns. + </p> + <p> + There is currently no good way to + transform XML data to Microsoft Excel. Apache's Cocoon 2 project + supplies a complete framework for XML, but nothing for outputting in + Excel's XLS format. Developers and power users alike need a simple + method to output XML documents to Excel through server-side + processing. + </p> + + + </section> + </section> + <section><title>3. Project Overview</title> + <section><title>3.1. Project Perspective</title> + <p> + The produced code shall be licensed by + the Apache License as used by the Cocoon 2 project and maintained on + a project page until such time as the Cocoon 2 developers accept it + as a donation (at which time the copyright will be turned over to + them). + </p> + </section> + <section><title>3.2. Project Position Statement</title> + <p> + For developers on a Java and/or XML + environment this project will provide all the tools necessary for + outputting XML data in the Microsoft Excel format. This project seeks + to make the use of Microsoft Windows based servers unnecessary for + file format considerations and to fully document the OLE 2 Compound + Document format. The project aims not only to provide the tools for + serializing XML to Excel's file format and the tools for writing to + that file format from Java, but also to provide the tools for later + projects to convert other OLE 2 Compound Document formats to pure + Java APIs. + </p> + </section> + <section><title>3.3. Summary of Capabilities</title> + <p> + HSSF Serializer for Apache Cocoon 2 + </p> + <table> + <tr> + <td> + Benefit + </td> + <td> + Supporting Features + </td> + </tr> + <tr> + <td> + Standard XML tag language for sheet data + </td> + <td> + Serializer will transform documents utilizing a defined tag + language + </td> + </tr> + <tr> + <td> + Utilize XML to output in Excel + </td> + <td> + Serializer will output in Excel + </td> + </tr> + <tr> + <td> + Java API to output in Excel on any platform + </td> + <td> + The project will develop an API that outputs in Excel using + pure Java. + </td> + </tr> + <tr> + <td> + Make it easy for developers to port other OLE 2 Compound + Document-based formats to Java. + </td> + <td> + The POIFS library will contain both a high-level abstraction + along with low-level constructs. The project will fully document + the OLE 2 Compound Document Format. + </td> + </tr> + </table> + </section> + <section><title>3.4. Assumptions and Dependencies</title> + <ul> + <li> + The HSSF Serializer will run on + any Java 2 supporting platform with Apache Cocoon 2 installed along + with the HSSF and POIFS APIs. + </li> + <li> + The HSSF API requires a Java 2 + implementation and the POI API. + </li> + <li> + The POIFS API requires a Java 2 + implementation. + </li> + </ul> + </section> + </section> + <section><title>4. Project Features</title> + <p> + The POIFS API will include: + </p> + <ul> + <li> + Low level structures representing + the structures in a POI filesystems. + </li> + <li> + A low-level API for + creating/manipulating POI filesystems. + </li> + <li> + A set of high level interfaces + abstracting the user from the POI filesystem constructs and + representing it as a standard filesystem (Files, directories, etc) + </li> + </ul> + <p> + The HSSF API will include: + </p> + <ul> + <li> + Low level structures representing + the structures in an Excel file. + </li> + <li> + A low-level API for creating and + manipulating Excel files and writing them into POI filesystems. + </li> + <li> + A high level model and style + interface for manipulating spreadsheet data without knowing anything + about the Excel format itself. + </li> + </ul> + <section><title>4.1 POI Filesystem API</title> + <p> + The POI Filesystem API includes: + </p> + <ul> + <li>An implementation of Big Blocks</li> + <li>An implementation of Small Blocks</li> + <li>An implementation of Header Blocks</li> + <li>An implementation of Block Allocation Tables</li> + <li>An implementation of Property Sets</li> + <li>An implementation of the POI + filesystem including functions to get and set the above constructs; + compound functions for reading/writing files/directories. + </li> + <li>An abstraction of the POI + filesystem providing interfaces representing Files, Directories, + FileSystems in normal terminology and encapulating the above + constructs. + </li> + <li>Full documentation of the POI file + format. + </li> + <li>Full documentation of the APIs and + interfaces provided through Javadoc, user documentation (aimed at + developers using the APIs) + </li> + <li>Examples aimed at teaching the + user to write code using POI. (titled: recipes for POI) + </li> + <li>Performance specifications. + (Example POI filesystems rated by some measure of complexity along + with system specifications and execution times for given operations) + </li> + </ul> + </section> + <section><title>4.2 HSSF API</title> + <p> + The HSSF API includes: + </p> + <ul> + <li>An implementation of Record + (binary 2 byte type followed by 2 byte size (n) followed by n bytes)</li> + <li>Implementations of many standard + record types mapping the data bytes to fields along with methods to + reserialize those fields</li> + <li>An implementation of the HSSF File + including functions to get/set the above constructs, create a blank + file with the minimum required record types and mappings between + getting/setting data and style in a workbook to the creation of + record types, and read HSSF files.</li> + <li>An abstraction of the HSSF file + format providing interfaces representing the HSSF File, HSSF + Workbook, HSSF Sheet, HSSF Column, HSSF Formulas in a manner + separating the data from the styling and encapsulating the above + constructs.</li> + <li>Full documentation of the HSSF + file format (which will be a subset of the Excel '97 File format). + This must be done with care for legal reasons.</li> + <li>Full documentation of the APIs and + interfaces provided through Javadoc, user documentation (aimed at + developers using the APIs).</li> + <li>Examples aimed at teaching + developers to use the APIs. + </li> + <li>Performance specifications. + (Example files rated by some measure of complexity along with system + specifications and execution times for given operations - possibly + the same files used for POI's tests)</li> + </ul> + </section> + <section><title>4.3 HSSF Serializer</title> + <p> + The HSSF Serializer subproject: + </p> + <ul> + <li>A class supporting the Cocoon 2 + Serializer Interface.</li> + <li>An interface between the SAX + events and the HSSF APIs.</li> + <li>A specified tag language for using + with the Serializer.</li> + <li>Documentation on the tag language + for the HSSF Serializer</li> + <li>Normal javadocs.</li> + <li>Example XML files</li> + <li>Performance specifications. + (Example XML docs and stylesheets rated by some measure of + complexity along with system specifications and execution times)</li> + </ul> + </section> + </section> + <section><title>5. Other Product Requirements</title> + <section><title>5.1. Applicable Standards</title> + <p> + All Java code will be 100% pure Java. + </p> + </section> + <section><title>5.2. System Requirements</title> + <p> + The minimum system requirements for POIFS are: + </p> + <ul> + <li>64 Mbytes memory</li> + <li>Java 2 environment</li> + <li>Pentium or better processor (or equivalent on other platforms)</li> + </ul> + <p> + The minimum system requirements for HSSF are: + </p> + <ul> + <li>64 Mbytes memory</li> + <li>Java 2 environment</li> + <li>Pentium or better processor (or equivalent on other platforms)</li> + <li>POIFS API</li> + </ul> + <p> + The minimum system requirements for the HSSF Serializer are: + </p> + <ul> + <li>64 Mbytes memory</li> + <li>Java 2 environment</li> + <li>Pentium or better processor (or equivalent on other platforms)</li> + <li>Cocoon 2</li> + <li>HSSF API</li> + <li>POI API</li> + </ul> + </section> + <section><title>5.3. Performance Requirements</title> + <p> + All components must perform well enough + to be practical for use in a webserver environment (especially + Cocoon2/Tomcat/Apache combo) + </p> + </section> + <section><title>5.4. Environmental Requirements</title> + <p> + The software will run primarily in + developer environments. We should make some allowances for + not-highly-technical users to write XML documents for the HSSF + Serializer. All other components will assume intermediate Java 2 + knowledge. No XML knowledge will be required except for using the + HSSF Serializer. As much documentation as is practical shall be + required for all components as XML is relatively new, and the + concepts introduced for writing spreadsheets and to POI filesystems + will be brand new to Java and many Java developers. + </p> + </section> + </section> + <section><title>6. Documentation Requirements</title> + <section><title>6.1 POI Filesystem</title> + <p> + The filesystem as read and written by + POI shall be fully documented and explained so that the average Java + developer can understand it. + </p> + </section> + <section><title>6.2. POI API</title> + <p> + The POI API will be fully documented + through Javadoc. A walkthrough of using the high level POI API shall + be provided. No documentation outside of the Javadoc shall be + provided for the low-level POI APIs. + </p> + </section> + <section><title>6.3. HSSF File Format</title> + <p> + The HSSF File Format as implemented by + the HSSF API will be fully documented. No documentation will be + provided for features that are not supported by HSSF API that are + supported by the Excel 97 File Format. Care will be taken not to + infringe on any "legal stuff". + </p> + </section> + <section><title>6.4. HSSF API</title> + <p> + The HSSF API will be documented by + javadoc. A walkthrough of using the high level HSSF API shall be + provided. No documentation outside of the Javadoc shall be provided + for the low level HSSF APIs. + </p> + </section> + + <section><title>6.5. HSSF Serializer</title> + <p> + The HSSF Serializer will be documented + by javadoc. + </p> + </section> + + <section><title>6.6 HSSF Serializer Tag language</title> + <p> + The XML tag language along with + function and usage shall be fully documented. Examples will be + provided as well. + </p> + </section> + </section> + <section><title>7. Terminology</title> + <section><title>7.1 Filesystem</title> + <p> + filesystem shall refer only to the POI formatted archive. + </p> + </section> + <section><title>7.2 File</title> + <p> + file shall refer to the embedded data stream within a + POI filesystem. This will be the actual embedded document. + </p> + </section> + </section> +</body> +</document> diff --git a/src/documentation/content/xdocs/devel/plan/vision20.xml b/src/documentation/content/xdocs/devel/plan/vision20.xml new file mode 100644 index 0000000000..f348541880 --- /dev/null +++ b/src/documentation/content/xdocs/devel/plan/vision20.xml @@ -0,0 +1,594 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>POI 2.0 Vision Document</title> + <authors> + <person name="Andrew C. Oliver" email="acoliver2@users.sourceforge.net"/> + <person name="Marcus W. Johnson" email="mjohnson@apache.org"/> + <person name="Glen Stampoultzis" email="user@poi.apache.org"/> + <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/> + </authors> + </header> + + <body> + + <section><title>Preface</title> + <p> + This is the POI 2.0 cycle vision document. Although the vision + has not changed and this document is certainly not out of date and + the vision has not changed, the structure of the project has + changed a bit. We're not going to change the vision document to + reflect this (however proper that may be) because it would only + involve deletion. There is no purpose in providing less + information provided we give clarification. + </p> + <p> + This document was created before the POI components for + <a href="https://xml.apache.org/cocoon">Apache Cocoon</a> + were accepted into the Cocoon project itself. It was also + written before POI was accepted into Jakarta. So while the + vision hasn't changed some of the components are actually now + part of other projects. We'll still be working on them on the + same timeline roughly (minus the overhead of coordination with + other groups), but they are no longer technically part of the + POI project itself. + </p> + </section> + + <section><title>1. Introduction</title> + <section><title>1.1 Purpose of this document</title> + <p> + The purpose of this document is to + collect, analyze and define high-level requirements, user needs, + and features of the second release of the POI project software. + The POI project currently consists of the following components: + the HSSF Serializer, the HSSF library and the POIFS library. + </p> + <ul> + <li> + The HSSF Serializer is a set of Java classes whose main + class supports the Serializer interface from the Cocoon + 2 project and outputs the serialized data in a format + compatible with the spreadsheet program Microsoft Excel + '97. + </li> + <li> + The HSSF library is a set of classes for reading and + writing Microsoft Excel 97 file format using pure Java. + </li> + <li> + The POIFS library is a set of classes for reading and + writing Microsoft's OLE 2 Compound Document format using + pure Java. + </li> + </ul> + <p>By the completion of this release cycle the POI project will also + include the HSSF Generator and the HWPF library. + </p> + <ul> + <li>The HSSF Generator will be responsible for using HSSF to read + in the XLS (Excel 97) file format and create SAX events. The HSSF + Generator will support the applicable interfaces specified by the + Apache Cocoon 2 project. + </li> + <li>The HWPF library will provide a set of high level interfaces + for reading and writing Microsoft Word 97 file format using pure + Java.</li> + </ul> + + </section> + + + <section><title>1.2 Project Overview</title> + <p> + The first release of the POI project + was an astounding success. This release seeks to build on that + success by: + </p> + <ul> + <li> + Refactoring POIFS into input and + output classes as well as an event-driven API for reading. + </li> + <li> + Refactor HSSF for greater + performance as well as an event-driven API for reading + </li> + <li> + Extend HSSF by adding the ability to read and write formulas. + </li> + <li> + Extend HSSF by adding the ability to read and write + user-defined styles. + </li> + <li> + Create a Cocoon 2 Generator for HSSF using the same tags + as the HSSF Serializer. + </li> + <li> + Create a new library (HWPF) for reading and writing + Microsoft Word DOC format. + </li> + <li> + Refactor the HSSFSerializer into a separate extensible + POIFSSerializer and HSSFSerializer + </li> + <li> + Providing the create excel charts. (write only) + </li> + </ul> + </section> + </section> + <section><title>2. User Description</title> + <section><title>2.1 User/Market Demographics</title> + <p> + There are a number of enthusiastic + users of XML, UNIX and Java technology. Furthermore, the Microsoft + solution for outputting Office Document formats often involves + actually manipulating the software as an OLE Server. This method + provides extremely low performance, extremely high overhead and is + only capable of handing one document at a time. + </p> + <ol> + <li> + Our intended audience for the HSSF + Serializer portion of this project are developers writing reports or + data extracts in XML format. + </li> + <li> + Our intended audience for the HSSF + library portion of this project is ourselves as we are developing + the HSSF serializer and anyone who needs to read and write Excel + spreadsheets in a non-XML Java environment, or who has specific + needs not addressed by the Serializer + </li> + <li> + Our intended audience for the + POIFS library is ourselves as we are developing the HSSF and HWPF + libraries and anyone wishing to provide other libraries for + reading/writing other file formats utilizing the OLE 2 Compound + Document Format in Java. + </li> + <li> + Our intended audience for the HSSF + generator are developers who need to export Excel spreadsheets to + XML in a non-proprietary environment. + </li> + <li> + Our intended audience for the HWPF + library is ourselves, as we will be developing a HWPF Serializer in a + later release, and anyone wishing to add .DOC file processing and + creation to their projects. + </li> + </ol> + </section> + <section><title>2.2. User environment</title> + <p> + The users of this software shall be + developers in a Java environment on any operating system, or power + users who are capable of XML document generation/deployment. + </p> + </section> + <section><title>2.3. Key User Needs</title> + <p> + The HSSF library currently requires a + full object representation to be created before reading values. This + results in very high memory utilization. We need to reduce this + substantially for reading. It would be preferable to do this for + writing, but it may not be possible due to the constraints imposed by + the file format itself. Memory utilization during read is our top + user complaint. + </p> + <p> + The POIFS library currently requires a + full object representation to be created before reading values. This + results in very high memory utilization. We need to reduce this + substantially for reading. + </p> + <p> + The HSSF library currently ignores + formula cells and identifies them as "UnknownRecord" at the + lower level of the API. We must provide a way to read and write + formulas. This is now the top requested feature. + </p> + <p> + The HSSF library currently does not support + charts. This is a key requirement of some users who wish to use HSSF + in a reporting engine. + </p> + <p> + The HSSF Serializer currently does not + provide serialization for cell styling. User's will want stylish + spreadsheets to result from their XML. + </p> + <p> + There is currently no way to generate + the XML from an XLS that is consistent with the format used by the + HSSF Serializer. + </p> + <p> + There should be a way to read and write + the DOC file format using pure Java. + </p> + + </section> + </section> + <section><title>3. Project Overview</title> + <section><title>3.1. Project Perspective</title> + <p> + The produced code shall be licensed by + the Apache License as used by the Cocoon 2 project (APL 1.1) and + maintained on at <a href="http://poi.sourceforge.net/">http://poi.sourceforge.net</a> + and <a href="http://sourceforge.net/projects/poi">http://sourcefoge.net/projects/poi</a>. + It is our hope to at some point integrate with the various Apache + projects (xml.apache.org and jakarta.apache.org), at which point we'd + turn the copyright over to them. + </p> + </section> + <section><title>3.2. Project Position Statement</title> + <p> + For developers on a Java and/or XML + environment this project will provide all the tools necessary for + outputting XML data in the Microsoft Excel format. This project seeks + to make the use of Microsoft Windows based servers unnecessary for + file format considerations and to fully document the OLE 2 Compound + Document format. The project aims not only to provide the tools for + serializing XML to Excel and Word file formats and the tools for + writing to those file formats from Java, but also to provide the + tools for later projects to convert other OLE 2 Compound Document + formats to pure Java APIs. + </p> + </section> + <section><title>3.3. Summary of Capabilities</title> + <p> + HSSF Serializer for Apache Cocoon 2 + </p> + <table> + <tr> + <th> + Benefit + </th> + <th> + Supporting Features + </th> + </tr> + <tr> + <td> + Ability to serialize styles from XML spreadsheets. + </td> + <td> + HSSFSerializer will support styles. + </td> + </tr> + <tr> + <td> + Ability to read and write formulas in XLS files. + </td> + <td> + HSSF will support reading/writing formulas. + </td> + </tr> + <tr> + <td> + Ability to output in MS Word on any platform using Java. + </td> + <td> + The project will develop an API that outputs in Word format + using pure Java. + </td> + </tr> + <tr> + <td> + Enhance performance for reading and writing XLS files. + </td> + <td> + HSSF will undergo a number of performance enhancements. HSSF + will include a new event-based API for reading XLS files. POIFS + will support a new event-based API for reading OLE2 CDF files. + </td> + </tr> + <tr> + <td> + Ability to generate XML from XLS files + </td> + <td> + The project will develop an HSSF Generator. + </td> + </tr> + <tr> + <td> + The ability to generate charts + </td> + <td> + HSSF will provide low level support for chart records as well + as high level API support for generating charts. The ability + to read chart information will not initially be provided. + </td> + </tr> + + </table> + </section> + <section><title>3.4. Assumptions and Dependencies</title> + <ul> + <li> + The HSSF Serializer and Generator + will support the Gnumeric 1.0 XML tag language. + </li> + <li> + The HSSF Generator and HSSF + Serializer will be mutually validating. It should be possible to + have an XLS file created by the Serializer run through the Generator + and the output back through the Serializer (via the Cocoon pipeline) + and get the same file or a reasonable facsimile (no one cares if it + differs by the order of the binary records in some minor but + non-visually recognizable manner). + </li> + <li> + The HSSF Generator will run on any + Java 2 supporting platform with Apache Cocoon 2 installed along with + the HSSF and POIFS APIs. + </li> + <li> + The HSSF Serializer will run on + any Java 2 supporting platform with Apache Cocoon 2 installed along + with the HSSF and POIFS APIs. + </li> + <li> + The HWPF API requires a Java 2 + implementation and the POIFS API. + </li> + <li> + The HSSF API requires a Java 2 + implementation and the POIFS API. + </li> + <li> + The POIFS API requires a Java 2 + implementation. + </li> + + </ul> + </section> + </section> + <section><title>4. Project Features</title> + <p> + Enhancements to the POIFS API will + include: + </p> + <ul> + <li> + An event driven API for reading + POIFS Filesystems. + </li> + <li> + A low-level API for + creating/manipulating POI filesystems. + </li> + <li> + Code improvements supporting + greater separation between read and write structures. + </li> + </ul> + <p> + Enhancements to the HSSF API will + include: + </p> + <ul> + <li> + An event driven API for reading + XLS files. + </li> + <li> + Performance improvements. + </li> + <li> + Formula support (read/write) + </li> + <li> + Support for user-defined data + formats + </li> + <li> + Better documentation of the file + format and structure. + </li> + <li> + An API for creation of charts. + </li> + </ul> + <p> + The HSSF Generator will include: + </p> + <ul> + <li> + A set of classes supporting the + Cocoon 2 Generator interfaces providing a method for reading XLS + files and outputting SAX events. + </li> + <li> + The same tag format used by the + HSSFSerializer in any given release. + </li> + </ul> + <p> + The HWPF API will include: + </p> + <ul> + <li> + An event driven API for reading + DOC files. + </li> + <li> + A set of high and low level APIs + for reading and writing DOC files. + </li> + <li> + Documentation of the DOC file + format or enhancements to existing documentation. + </li> + </ul> + </section> + <section><title>5. Other Product Requirements</title> + <section><title>5.1. Applicable Standards</title> + <p> + All Java code will be 100% pure Java. + </p> + </section> + <section><title>5.2. System Requirements</title> + <p> + The minimum system requirements for the POIFS API are: + </p> + <ul> + <li>64 Mbytes memory</li> + <li>Java 2 environment</li> + <li>Pentium or better processor (or equivalent on other platforms)</li> + </ul> + <p> + The minimum system requirements for the HSSF API are: + </p> + <ul> + <li>64 Mbytes memory</li> + <li>Java 2 environment</li> + <li>Pentium or better processor (or equivalent on other platforms)</li> + <li>POIFS API</li> + </ul> + <p> + The minimum system requirements for the HWPF API are: + </p> + <ul> + <li>64 Mbytes memory</li> + <li>Java 2 environment</li> + <li>Pentium or better processor (or equivalent on other platforms)</li> + <li>POIFS API</li> + </ul> + + <p> + The minimum system requirements for the HSSF Serializer are: + </p> + <ul> + <li>64 Mbytes memory</li> + <li>Java 2 environment</li> + <li>Pentium or better processor (or equivalent on other platforms)</li> + <li>Cocoon 2</li> + <li>HSSF API</li> + <li>POI API</li> + </ul> + </section> + <section><title>5.3. Performance Requirements</title> + <p> + All components must perform well enough + to be practical for use in a webserver environment (especially + the "killer trio": Cocoon2/Tomcat/Apache combo) + </p> + </section> + <section><title>5.4. Environmental Requirements</title> + <p> + The software will run primarily in + developer environments. We should make some allowances for + not-highly-technical users to write XML documents for the HSSF + Serializer. All other components will assume intermediate Java 2 + knowledge. No XML knowledge will be required except for using the + HSSF Serializer. As much documentation as is practical shall be + required for all components as XML is relatively new, and the + concepts introduced for writing spreadsheets and to POI filesystems + will be brand new to Java and many Java developers. + </p> + </section> + </section> + <section><title>6. Documentation Requirements</title> + <section><title>6.1 POI Filesystem</title> + <p> + The filesystem as read and written by + POI shall be fully documented and explained so that the average Java + developer can understand it. + </p> + </section> + <section><title>6.2. POI API</title> + <p> + The POI API will be fully documented + through Javadoc. A walkthrough of using the high level POI API shall + be provided. No documentation outside of the Javadoc shall be + provided for the low-level POI APIs. + </p> + </section> + <section><title>6.3. HSSF File Format</title> + <p> + The HSSF File Format as implemented by + the HSSF API will be fully documented. No documentation will be + provided for features that are not supported by HSSF API that are + supported by the Excel 97 File Format. Care will be taken not to + infringe on any "legal stuff". Additionally, we are + collaborating with the fine folks at OpenOffice.org on + *free* documentation of the format. + </p> + </section> + <section><title>6.4. HSSF API</title> + <p> + The HSSF API will be documented by + javadoc. A walkthrough of using the high level HSSF API shall be + provided. No documentation outside of the Javadoc shall be provided + for the low level HSSF APIs. + </p> + </section> + <section><title>6.5 HWPF API</title> + <p> + The HWPF API will be documented by + javadoc. A walkthrough of using the high level HWPF API shall be + provided. No documentation outside of the Javadoc shall be provided + for the low level HWPF APIs. + </p> + </section> + <section><title>6.6 HSSF Serializer</title> + <p> + The HSSF Serializer will be documented + by javadoc. + </p> + </section> + <section><title>6.7 HSSF Generator</title> + <p> + The HSSF Generator will be documented + by javadoc. + </p> + </section> + <section><title>6.8 HSSF Serializer Tag language</title> + <p> + The XML tag language along with + function and usage shall be fully documented. Examples will be + provided as well. + </p> + </section> + </section> + <section><title>7. Terminology</title> + <section><title>7.1 Filesystem</title> + <p> + filesystem shall refer only to the POI formatted archive. + </p> + </section> + <section><title>7.2 File</title> + <p> + file shall refer to the embedded data stream within a + POI filesystem. This will be the actual embedded document. + </p> + </section> + </section> +</body> +</document> diff --git a/src/documentation/content/xdocs/devel/references/3rdparty.xml b/src/documentation/content/xdocs/devel/references/3rdparty.xml new file mode 100644 index 0000000000..7a85232327 --- /dev/null +++ b/src/documentation/content/xdocs/devel/references/3rdparty.xml @@ -0,0 +1,86 @@ +<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ====================================================================
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ ====================================================================
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd">
+
+<document>
+ <header>
+ <title>Third Party Contributions</title>
+ <authors>
+ <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
+ </authors>
+ </header>
+
+ <body>
+
+ <section><title>How to Contribute</title>
+ <p>
+ See <a href="contrib.xml">How to contribute to Poi</a>.
+ </p>
+
+ </section>
+
+ <section><title>Contributed Components</title>
+ <p>
+ These are not necessarily deemed to be high enough quality to be included in the
+ core distribution, but they have been tested under <a href="contrib.xml">
+ several key environments</a>, they are provided under the same license
+ as Poi, and they are included in the POI distribution under the
+ <code>contrib/</code> directory.
+ </p>
+
+ <p>
+ <strong>None as yet!</strong> - although you can expect that some of the links
+ listed below will eventually migrate to the "contributed components" level, and
+ then maybe even into the main distribution.
+ </p>
+ </section>
+
+ <section><title>Patch Queue</title>
+ <p><a href="patches.html">Submissions of modifications</a>
+ to POI which are awaiting review. Anyone can
+ comment on them on the dev mailing list - code reviewers are needed!
+ <strong>Use these at your own risk</strong> - although POI has no guarantee
+ either, these patches have not been reviewed, let alone accepted.
+ </p>
+ </section>
+
+ <section><title>Other Extensions</title>
+ <p>The other extensions listed here are <strong>not endorsed</strong> by the POI
+ project either - they are provided as a convenience only. They may or may not work,
+ they may or may not be open source, etc.
+ </p>
+
+ <p>To have a link added to this table, see <a href="contrib.xml">How to contribute
+ to POI</a>.</p>
+
+ <table>
+ <tr>
+ <th>Name and Link</th>
+ <th>Type</th>
+ <th>Description</th>
+ <th>Status</th>
+ <th>Licensing</th>
+ <th>Contact</th>
+ </tr>
+ </table>
+
+ </section>
+</body>
+</document>
diff --git a/src/documentation/content/xdocs/devel/references/index.xml b/src/documentation/content/xdocs/devel/references/index.xml new file mode 100644 index 0000000000..bbb9f51673 --- /dev/null +++ b/src/documentation/content/xdocs/devel/references/index.xml @@ -0,0 +1,66 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Live Sites using Poi</title> + <authors> + <person name="Donald Ball" email="balld@webslingerZ.com"/> + <person name="Stefano Mazzocchi" email="stefano@apache.org"/> + <person name="Robin Green" email="greenrd@hotmail.com"/> + <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/> + <person name="Glen Stampoultzis" email="user@poi.apache.org"/> + <person name="Rainer Klute" email="klute@rainer-klute.org"/> + </authors> + </header> + + <body> + <section><title>References</title> + + <section><title>Live Sites using POI</title> + <p>Currently we don't have any sites listed that use POI, but we're + sure they're out there. Help us change this. If you've written a site + that utilises POI let us know.</p> + <!-- + <ul> + <li><a href=""></a></li> + </ul> + --> + </section> + + <section><title>Products/Projects using POI</title> + <p>Publicly available products/projects using POI include:</p> + <ul> + <li><a href="http://jtimetracker.sourceforge.net/">JTimeTracker</a></li> + </ul> + </section> + + <section><title>File Format Descriptions</title> + <p>POI depends on publicly available documents describing various + file formats. The list below contains links to some of them.</p> + <ul> + <li><a href="http://www.wotsit.org/">Wotsit's Format</a></li> + </ul> + </section> + + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/devel/references/logocontest.xml b/src/documentation/content/xdocs/devel/references/logocontest.xml new file mode 100644 index 0000000000..efd84f1255 --- /dev/null +++ b/src/documentation/content/xdocs/devel/references/logocontest.xml @@ -0,0 +1,194 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title></title> + <authors> + <person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/> + <person id="GS" name="Glen Stampoultzis" email="user@poi.apache.org"/> + </authors> + </header> + + <body> + <section><title>POI logos</title> + <p> + Here are the current logo submissions. Thanks to the artists! + </p> + <section><title>Michael Mosmann</title> + <p> + <img alt="logo" src="images/logoMichaelMosmann.png"/> + </p> + </section> + <section><title>Loc Lefvre</title> + <p> + <img alt="logo" src="images/logoLoicLefevre.png"/> + <img alt="logo" src="images/logoLoicLefevre2.png"/> + </p> + </section> + <section><title>Glen Stampoultzis</title> + <p> + <img alt="logo" src="images/logoGlenStampoutlzis.png"/> + </p> + </section> + <section><title>Marcus Gustafsson</title> + <p> + <img alt="logo" src="images/logoGustafsson1.png"/> + <img alt="logo" src="images/logoGustafsson2.png"/> + </p> + </section> + <section><title>Adrianus Handoyo</title> + <p> + <img alt="logo" src="images/logoAdria1.png"/> + <img alt="logo" src="images/logoAdria2.png"/> + <img alt="logo" src="images/logoAdria3.png"/> + </p> + </section> + <section><title>RussellBeattie</title> + <p> + <img alt="logo" src="images/logoRussellBeattie1.png"/> + <img alt="logo" src="images/logoRussellBeattie2.png"/> + <img alt="logo" src="images/logoRussellBeattie3.png"/> + </p> + <p> + <img alt="logo" src="images/logoRussellBeattie4.png"/> + <img alt="logo" src="images/logoRussellBeattie5.png"/> + </p> + </section> + <section><title>Daniel Fernandez</title> + <p> + <img alt="logo" src="images/logoDanielFernandez.png"/> + </p> + </section> + <section><title>Andrew Clements</title> + <p> + <img alt="logo" src="images/logoAndrewClements.png"/> + <img alt="logo" src="images/logoAndrewClements2.png"/> + </p> + </section> + <section><title>Wendy Wise</title> + <p> + <img alt="logo" src="images/logoWendyWise.png"/> + <img alt="logo" src="images/logoWendyWise2.png"/> + </p> + </section> + <section><title>Nikhil Karmokar</title> + <p> + <img alt="logo" src="images/logoKarmokar1.png"/> + <img alt="logo" src="images/logoKarmokar1s.png"/> + </p> + <p> + <img alt="logo" src="images/logoKarmokar2.png"/> + <img alt="logo" src="images/logoKarmokar2s.png"/> + </p> + <p> + <img alt="logo" src="images/logoKarmokar3.png"/> + <img alt="logo" src="images/logoKarmokar3s.png"/> + </p> + <p> + <img alt="logo" src="images/logoKarmokar4.png"/> + <img alt="logo" src="images/logoKarmokar4s.png"/> + </p> + <p> + <img alt="logo" src="images/logoKarmokar5.png"/> + <img alt="logo" src="images/logoKarmokar5s.png"/> + </p> + <p> + <img alt="logo" src="images/logoKarmokar6.png"/> + <img alt="logo" src="images/logoKarmokar6s.png"/> + </p> + </section> + <section><title>Lieven Janssen</title> + <p> + <img alt="logo" src="images/logoJanssen1.png"/> + <img alt="logo" src="images/logoJanssen2.png"/> + </p> + </section> + <section><title>RaPi GmbH</title> + <p> + Contact Person: Fancy at: fancy at my-feiqi.com + </p> + <p> + <img alt="logo" src="images/logoRaPiGmbH1.png"/> + <img alt="logo" src="images/logoRaPiGmbH2.png"/> + </p> + <p> + <img alt="logo" src="images/logoRaPiGmbH5.png"/> + </p> + <p> + <img alt="logo" src="images/logoRaPiGmbH6.png"/> + </p> + <p> + <img alt="logo" src="images/logoRaPiGmbH7.png"/> + </p> + <p> + <img alt="logo" src="images/logoRaPiGmbH8.png"/> + </p> + <p> + <img alt="logo" src="images/logoRaPiGmbH9.png"/> + </p> + <p> + <img alt="logo" src="images/logoRaPiGmbH10.png"/> + </p> + <p> + <img alt="logo" src="images/logoRaPiGmbH11.png"/> + </p> + <p> + <img alt="logo" src="images/logoRaPiGmbH12.png"/> + </p> + </section> + <section><title>Randy Stanard</title> + <p> + <img alt="logo" src="images/logoRandyStanard01.png"/> + </p> + <p> + <img alt="logo" src="images/logoRandyStanard02.png"/> + </p> + <p> + <img alt="logo" src="images/logoRandyStanard03.png"/> + </p> + <p> + <img alt="logo" src="images/logoRandyStanard04.png"/> + </p> + <p> + <img alt="logo" src="images/logoRandyStanard05.png"/> + </p> + <p> + <img alt="logo" src="images/logoRandyStanard06.png"/> + </p> + <p> + <img alt="logo" src="images/logoRandyStanard07.png"/> + </p> + <p> + <img alt="logo" src="images/logoRandyStanard08.png"/> + </p> + </section> + </section> + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/devel/resolutions/index.xml b/src/documentation/content/xdocs/devel/resolutions/index.xml new file mode 100644 index 0000000000..6df469cdf3 --- /dev/null +++ b/src/documentation/content/xdocs/devel/resolutions/index.xml @@ -0,0 +1,55 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Resolutions</title> + <subtitle>About this section</subtitle> + <authors> + <person name="Andrew C. Oliver" email="acoliver@apache.org"/> + </authors> + </header> + + <body> + <section><title>About Resolutions</title> + <p> + Every project in Apache has resolutions that they vote on. + Decisions are made, etc. But what happens once those decisions + are made? They are archived in the mail list archive never to + be read again (once its not in the top 10 or so posts). So they + get discussed again and again. + </p> + <p> + Rather than have that big waste of time, we have this section to + record important POI decisions. Once a decision is passed it + need only be linked to this page (either by creating a page for + it or by simply linking it to the archive messages). Wherever + possible a brief about how many votes for and against an maybe + some background should be posted. + </p> + <p> + This section is intended mainly to reduce big waste of time + discussions from taking away from whats important...developing + POI! :-D + </p> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/devel/resolutions/res001.xml b/src/documentation/content/xdocs/devel/resolutions/res001.xml new file mode 100644 index 0000000000..dbc64c10a6 --- /dev/null +++ b/src/documentation/content/xdocs/devel/resolutions/res001.xml @@ -0,0 +1,113 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>POI Resoluton</title> + <subtitle>Resolution 001 - Minimal Coding Standards</subtitle> + <authors> + <person name="Andrew C. Oliver" email="acoliver@apache.org"/> + </authors> + </header> + + <body> + <section><title>Resolution 001 - Minimal Coding Standards</title> + <section><title>Majority Position</title> + <p> + As the POI project has grown the "styles" used have become more + varied, some see this as a bad thing, but in reality it + can be a good thing. Each can learn from the different + styles by working with different code. That being said + there are some universal "good quality" guidelines that + must be adopted on a project of any proportions. + </p> + <p> + Marc Johnson Authored the following resolution: + </p> + <p> + On Tue, 2002-01-08 at 22:23, Marc Johnson wrote: + Standards are wonderful; everyone should have a set. + Here's what I propose for coding standards for POI WRT comments (should I + feel the need, I'll post more of these little gems): + </p> + <ol> + <li> + All classes and interfaces MUST have, right at the + beginning of the file, the Apache Software License + 2.0 License Header. (see /legal/LICENSE). + </li> + <li> + All classes and interfaces MUST include class javadoc. Conventionally, + this goes after the package and imports, and before the start of the class + or interface. + <!-- No more author tags --> + <!-- The class javadoc MUST have at least one @author tag --> + </li> + <li> + All methods that are accessible outside the class MUST have javadoc + comments. In other words, if it isn't private, it MUST have javadoc + comments. Simple getters can consist of a simple @return tag; simple setters + can consist of a simple @param tag. Anything else requires some verbiage + plus all the standard javadoc tags as appropriate. You MUST include @throws + or @throws for any non-runtime exceptions, and you SHOULD document any + runtime exceptions you expect to throw. @throws/@throws tags SHOULD + include an explanation of why that exception would be thrown. If your method + might return null, you MUST say so. An accompanying explanation of the + circumstances for doing so would be nice. + </li> + </ol> + </section> + <section><title>Amendments (informal by extension and not by vote)</title> + <section><title>License</title> + <p> + As opposed to the formerly used POI License (which was + based on the Apache Public License), now that POI is + part of Apache, use the standard Apache Software + License 2.0 header. As per standard Apache Software + Foundation policy, the full (long) version of the + header should be used. + </p> + </section> + <section><title>2 cents</title> + <p> + Tip: No laughing or joking allowed in conversations regarding coding + standards. + Any mail on coding standards will be treated very seriously, + and sent here with a RTFM. + </p> + </section> + </section> + <section><title>Dissent</title> + <p> + The motion was passed unanimously with no negative or + neutral votes. + </p> + </section> + <section><title>Comments</title> + <p> + Andy didn't feel like going through his mail and sucking + out the comments.. If there is anything you feel should + be added here do it yourself ;-). + </p> + </section> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/devel/who.xml b/src/documentation/content/xdocs/devel/who.xml new file mode 100644 index 0000000000..d95768a0a8 --- /dev/null +++ b/src/documentation/content/xdocs/devel/who.xml @@ -0,0 +1,134 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - Who We Are</title> + <authors> + <person name="Apache POI Developers" email="dev@poi.apache.org"/> + </authors> + </header> + + <body> + + <section><title>Apache POI™ - Who we are</title> + <p> + The Apache POI Project operates on a meritocracy: the more you do, the more + responsibility you will obtain. This page lists all of the people who have + gone the extra mile and are Committers. If you would like to get involved, + the first step is to join the <a href="site:mailinglists">mailing lists</a>. + </p> + + <p> + We ask that you please do not send us emails privately asking for support. + We are non-paid volunteers who help out with the project and we do not + necessarily have the time or energy to help people on an individual basis. + The <a href="site:mailinglists">mailing lists</a> have many individuals + who will help answer detailed requests for help. The benefit of + using mailing lists over private communication is that they are a shared + resource where others can also learn from common questions. + </p> + <p> + POI Developers count on feedback from the mailing lists. Many developers do take + an active role on the lists. + </p> + +<!-- <section><title>Advisors</title>--> +<!-- <ul>--> +<!-- <li><a href="http://www.betaversion.org/~stefano/">Stefano Mazzocchi</a> (stefano at apache dot org)--> +<!-- </li>--> +<!-- </ul>--> +<!-- </section>--> + + <section><title>Project Chair</title> + <ul> + <li>Dominik Stadler (centic at apache dot org)</li> + </ul> + </section> + <section><title>Committers</title> + <ul> + <!-- Alphabetical by surname --> + <li>Tim Allison (tallison at apache dot org)</li> + <li><a href="https://people.apache.org/list_B.html#kiwiwings">Andreas Beeker</a> (kiwiwings at apache dot org)</li> + <li>Nick Burch (nick at apache dot org)</li> + <li>Amol S Deshmukh (amol at apache dot org)</li> + <li>David Fisher (wave at apache dot org)</li> + <li>Jason Height (jheight at apache dot org)</li> + <li>Marc Johnson (mjohnson at apache dot org)</li> + <li><a href="http://www.rainer-klute.de/">Rainer Klute</a> (klute at apache dot org)</li> + <li>Yegor Kozlov (yegor at apache dot org)</li> + <li>Shawn Laubach (slaubach at apache dot org)</li> + <li>Josh Micich (josh at apache dot org)</li> + <li>Mark Murphy (jmarkmurphy at apache dot org)</li> + <li>Danny Mui (dmui at apache dot org)</li> + <li><a href="https://people.apache.org/~dnorth/">David North</a> (dnorth at apache dot org)</li> + <li>Javen O'Neal (onealj at apache dot org)</li> + <li>Uwe Schindler (uschindler at apache dot org)</li> + <li>Avik Sengupta (avik at apache dot org)</li> + <li>Dominik Stadler (centic at apache dot org)</li> + <li><a href="http://members.iinet.net.au/~gstamp/glen/">Glen Stampoultzis</a> (glens at apache.org)</li> + <li>Jon Svede (jsvede at apache dot org)</li> + <li>Maxim Valyanskiy (maxcom at apache dot org)</li> + <li>Sergey Vladimirov (sergey at apache dot org)</li> + <li>Greg Woolsey (gwoolsey at apache dot org)</li> + </ul> + </section> + + <section><title>Emeritus Committers</title> + <ul> + <li>Andrew C. Oliver (acoliver at gmail dot com)</li> + <li>Nicola Ken Barozzi (barozzi at nicolaken dot com)</li> + <li>Ryan Ackley (sackley at apache dot org)</li> + <li>Tetsuya Kitahata (ai at spa dot nifty dot com)</li> + </ul> + </section> + </section> + + <section><title>I want some progress on a bug report!</title> + <p> + So you took the time to report a bug, provided information that should make + it possible to reproduce the problem and fix it. Surely the fix is easy and + should take a seasoned developer a few minutes at max to fix! + + So why is there no progress on your bug report? Is there nobody + taking care when your problem is clearly stopping nearly everybody + from using POI? + + We know that the absence of responses on bug-reports can be frustrating, + sometimes bugs lie dormant for a long time for no apparent reason. + + Please always remember: <em>nobody is paid to work on POI</em>, the team is + a bunch of volunteers who look at things in their free time. + + Because of that developers might choose to work on things based on a + different priority than yours! Especially the quality and maturity of + bug reports will affect if somebody decides to look at it. + + So the best way to help a bug report see progress is to provide more information + if available or supply patches together with unit-tests. + + If you can, look at <a href="site:guidelines">Contribution Guidelines</a> + for more information about providing patches. + </p> +</section> + +</body> +</document> diff --git a/src/documentation/content/xdocs/download.xml b/src/documentation/content/xdocs/download.xml new file mode 100644 index 0000000000..e7aee674ed --- /dev/null +++ b/src/documentation/content/xdocs/download.xml @@ -0,0 +1,171 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - Download Release Artifacts</title> + </header> + + <body> + <section> + <title>Available Downloads</title> + <p> + This page provides instructions on how to download and verify the Apache POI release artifacts. There + are different versions available depending on how stable your code should be. + </p> + <ul> + <li> + <a href="#POI-5.4.1">The latest stable release is Apache POI 5.4.1</a> + </li> + <li> + <a href="#archive">Archives of all prior releases</a> + </li> + </ul> + <p> + Apache POI releases are available under the + <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0.</a> + See the NOTICE file contained in each release artifact for applicable copyright attribution notices. + </p> + <p> + To ensure that you have downloaded the true release you should + <a href="#verify">verify the integrity</a> + of the files using the signatures and checksums available from this page. + </p> + </section> + + <!-- latest final release --> + + <section id="POI-5.4.1"><title>6 April 2025 - POI 5.4.1 available</title> + <p>The Apache POI team is pleased to announce the release of 5.4.1. + Featured are a handful of new areas of functionality and numerous bug fixes.</p> + <p>A summary of changes is available in the + <a href="https://www.apache.org/dyn/closer.lua/poi/dev/RELEASE-NOTES-5.4.1.txt">Release Notes</a>. + A full list of changes is available in the <a href="site:changes">change log</a>. + People interested should also follow the <a href="site:mailinglists">dev list</a> + to track progress.</p> + <p> + The POI source release is listed below. + Pre-built versions of all <a href="site:components">POI components</a> + are available in the central Maven repository under Group ID "org.apache.poi" and Version + "5.4.1". + </p> + <section id="POI-5.4.1-src"><title>Source Distribution</title> + <ul> + <li> + <a href="https://www.apache.org/dyn/closer.lua/poi/release/src/apache-poi-src-5.4.1-20250401.tgz">apache-poi-src-5.4.1-20250401.tgz</a> + (116 MB, <a href="https://downloads.apache.org/poi/release/src/apache-poi-src-5.4.1-20250401.tgz.asc">signature (.asc)</a>, + checksum: <a href="https://downloads.apache.org/poi/release/src/apache-poi-src-5.4.1-20250401.tgz.sha512">SHA-512</a>) + </li> + <li> + <a href="https://www.apache.org/dyn/closer.lua/poi/release/src/apache-poi-src-5.4.1-20250401.zip">apache-poi-src-5.4.1-20250401.zip</a> + (120 MB, <a href="https://downloads.apache.org/poi/release/src/apache-poi-src-5.4.1-20250401.zip.asc">signature (.asc)</a>, + checksum: <a href="https://downloads.apache.org/poi/release/src/apache-poi-src-5.4.1-20250401.zip.sha512">SHA-512</a>) + </li> + </ul> + </section> + </section> + + <section id="POI-bin-artifacts"> + <title>Binary Artifacts</title> + <p> + POI 5.2.3 was the last version where we produced a set of poi-bin*.zip and poi-bin*.tgz files. + We will continue to publish jars to Maven Central. If you are not using a build tool like + Apache Maven or Gradle, you can still find these jars by traversing the directories at + <a href="https://repo1.maven.org/maven2/org/apache/poi/">https://repo1.maven.org/maven2/org/apache/poi/</a>. + </p> + <p> + If you want to download a legacy poi-bin archive, see the + <a href="#archive">archives of all prior releases</a>. + </p> + </section> + + <section id="verify"> + <title>Verify</title> + <p> + It is essential that you verify the integrity of the downloaded files using the PGP and SHA2 signatures. + Please read + <a href="https://httpd.apache.org/dev/verification.html">Verifying Apache HTTP Server Releases</a> + for more information on why you should verify our releases. This page provides detailed instructions + which you can use for POI artifacts. + </p> + <p> + The PGP signatures can be verified using PGP or GPG. First download the + <a href="https://downloads.apache.org/poi/KEYS">KEYS</a> + file as well as the .asc signature files for the relevant release packages. Make sure you get these + files from the main distribution directory, rather than from a mirror. + Then <a href="https://www.apache.org/info/verification.html">verify the signatures</a>. + </p> + <p>Batch check of all distribution files:</p> + <source> + find . -name "*.sha256" -type f -execdir sha256sum -c {} \; + find . -name "*.sha512" -type f -execdir sha512sum -c {} \; + find . -name "*.asc" -exec gpg --no-secmem-warning --verify {} \; + </source> + <p>Sample verification of poi-bin-3.5-FINAL-20090928.tgz</p> + <source>% gpg --import KEYS +gpg: key 12DAE9BE: "Glen Stampoultzis <glens at apache dot org>" not changed +gpg: key 4CEED75F: "Nick Burch <nick at gagravarr dot org>" not changed +gpg: key 84B5A42E: "Rainer Klute <rainer.klute at gmx dot de>" not changed +gpg: key F5BB52CD: "Yegor Kozlov <yegor.kozlov at gmail dot com>" not changed +gpg: Total number processed: 4 +gpg: unchanged: 4 +% gpg --verify poi-bin-3.5-FINAL-20090928.tgz.asc poi-bin-3.5-FINAL-20090928.tgz +gpg: Signature made Mon Sep 28 10:28:25 2009 PDT using DSA key ID F5BB52CD +gpg: Good signature from "Yegor Kozlov <yegor.kozlov at gmail dot com>" +gpg: aka "Yegor Kozlov <yegor at dinom dot ru>" +gpg: aka "Yegor Kozlov <yegor at apache dot org>" +Primary key fingerprint: 7D77 0C77 6CE7 754E E6AF 23AA 6934 0A02 F5BB 52CD +% gpg --fingerprint F5BB52CD +pub 1024D/F5BB52CD 2007-06-18 [expires: 2012-06-16] + Key fingerprint = 7D77 0C77 6CE7 754E E6AF 23AA 6934 0A02 F5BB 52CD +uid Yegor Kozlov <yegor.kozlov at gmail dot com> +uid Yegor Kozlov <yegor at dinom dot ru> +uid Yegor Kozlov <yegor at apache dot org> +sub 4096g/7B45A98A 2007-06-18 [expires: 2012-06-16]</source> + </section> + <section id="archive"> + <title>Release Archives</title> + <p> + Apache POI became a top level project in June 2007 and POI 3.0 artifacts were re-released. Prior to that + date POI was a sub-project of + <a href="https://jakarta.apache.org/">Apache Jakarta.</a> + </p> + <ul> + <li> + <a href="https://archive.apache.org/dist/poi/release/src/">Source Artifacts</a> + </li> + <li> + <a href="https://archive.apache.org/dist/poi/release/bin/">Binary Artifacts</a> + </li> + <li> + <a href="https://archive.apache.org/dist/jakarta/poi/release/">Artifacts from prior to 3.0</a> + </li> + </ul> + </section> + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation. All rights reserved.<br/> + Apache POI, POI, Apache, the Apache feather logo, and the Apache POI project logo are trademarks of The + Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/encryption.xml b/src/documentation/content/xdocs/encryption.xml new file mode 100644 index 0000000000..4d0839c926 --- /dev/null +++ b/src/documentation/content/xdocs/encryption.xml @@ -0,0 +1,510 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + + +<document> + <header> + <title>Apache POI™ - Encryption support</title> + <authors> + <person id="maxcom" name="Maxim Valyanskiy" email="maxcom@apache.org"/> + <person id="AB" name="Andreas Beeker" email="kiwiwings@apache.org"/> + </authors> + </header> + + <body> + <section> + <title>Overview</title> + + <p>Apache POI contains support for reading few variants of encrypted office files: </p> + <ul> + <li>Binary formats (.xls, .ppt, .doc, ...)<br/> + encryption is format-dependent and needs to be implemented per format differently.<br/> + Use <a href="apidocs/dev/org/apache/poi/hssf/record/crypto/Biff8EncryptionKey.html"> + Biff8EncryptionKey</a>.<a href="apidocs/dev/org/apache/poi/hssf/record/crypto/Biff8EncryptionKey.html#setCurrentUserPassword(java.lang.String)">setCurrentUserPassword</a>(String password) + to specify the decryption password before opening the file or (where applicable) before saving. + Setting a null password before saving removes the password protection.<br/> + The password is set in a thread local variable. Do not forget to reset it to null after text extraction. + </li> + <li>XML-based formats (.xlsx, .pptx, .docx, ...)<br/> + use the same encryption logic over all formats. When encrypted, the zipped files will be + stored within an OLE file in the EncryptedPackage stream.<br/> + If you plan to use POI to actually generate encrypted documents, be aware not to use anything less than + agile encryption, because <a href="https://eprint.iacr.org/2005/007.pdf">RC4 is not really secure</a> and + <a href="https://blog.cryptographyengineering.com/2011/12/01/how-not-to-use-symmetric-encryption/">ECB chaining is problematic too</a>. + Of course you'll need to make sure, that your clients can read the documents, + i.e. the various free Excel, Powerpoint, Word viewers have limitations in the cipher or hashing parameters.<br/> + If you want to use high encryption parameters, you need to install the "Java Cryptography Extension (JCE) Unlimited + Strength Jurisdiction Policy Files" for your JRE version + (Oracle <a href="http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html">JDK6</a>, + <a href="http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html">JDK7</a>, + <a href="http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html">JDK8</a>, + IBM <a href="https://www.ibm.com/support/knowledgecenter/en/SSYKE2_8.0.0/com.ibm.java.security.component.80.doc/security-component/sdkpolicyfiles.html">JDK8</a>). + </li> + </ul> + + <p>Some "write-protected" files are encrypted with the built-in password "VelvetSweatshop", POI can read that files too.</p> + </section> + + <section> + <title>Supported feature matrix</title> + + <table class="autosize POITable"> + <tr> + <th>Encryption</th> + <th>HSSF</th> + <th>HSLF</th> + <th>HWPF</th> + </tr> + <tr> + <td><a href="https://msdn.microsoft.com/en-us/library/dd949802(v=office.12).aspx">XOR obfuscation *)</a></td> + <td class="feature-yes">Yes (Writing since 3.16)</td> + <td class="feature-na">N/A</td> + <td class="feature-no">No</td> + </tr> + <tr> + <td><a href="https://msdn.microsoft.com/en-us/library/dd909583(v=office.12).aspx">40-bit RC4 encryption</a></td> + <td class="feature-yes">Yes (Writing since 3.16)</td> + <td class="feature-na">N/A</td> + <td class="feature-yes">Yes (since 3.17)</td> + </tr> + <tr> + <td><a href="https://msdn.microsoft.com/en-us/library/dd910113(v=office.12).aspx">Office Binary Document RC4 CryptoAPI Encryption</a></td> + <td class="feature-yes">Yes (Since 3.16)</td> + <td class="feature-yes">Yes</td> + <td class="feature-yes">Yes (since 3.17)</td> + </tr> + <tr> + <th/> + <th>XSSF</th> + <th>XSLF</th> + <th>XWPF</th> + </tr> + <tr> + <td><a href="https://msdn.microsoft.com/en-us/library/dd907466(v=office.12).aspx">Office Binary Document RC4 Encryption **)</a></td> + <td class="feature-yes">Yes</td> + <td class="feature-yes">Yes</td> + <td class="feature-yes">Yes</td> + </tr> + <tr> + <td><a href="https://msdn.microsoft.com/en-us/library/dd906131(v=office.12).aspx">ECMA-376 Standard Encryption</a></td> + <td class="feature-yes">Yes</td> + <td class="feature-yes">Yes</td> + <td class="feature-yes">Yes</td> + </tr> + <tr> + <td><a href="https://msdn.microsoft.com/en-us/library/dd906131(v=office.12).aspx">ECMA-376 Agile Encryption</a></td> + <td class="feature-yes">Yes</td> + <td class="feature-yes">Yes</td> + <td class="feature-yes">Yes</td> + </tr> + <tr> + <td><a href="https://msdn.microsoft.com/en-us/library/ms757845(v=vs.85).aspx">ECMA-376 XML Signature</a></td> + <td class="feature-yes">Yes</td> + <td class="feature-yes">Yes</td> + <td class="feature-yes">Yes</td> + </tr> + </table> + + <p>*) the xor encryption is flawed and works only for very small files - see <a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=59857">#59857</a>. + </p> + + <p>**) the <a href="https://msdn.microsoft.com/en-us/library/cc313071(v=office.12).aspx">MS-OFFCRYPTO</a> + documentation only mentions the RC4 (without CryptoAPI) encryption as a "in place" encryption, but + apparently there's also a container based method with that key generation logic. + </p> + </section> + + <section><title>Binary formats</title> + <p>As mentioned above, use + <a href="apidocs/dev/org/apache/poi/hssf/record/crypto/Biff8EncryptionKey.html"> + Biff8EncryptionKey</a>.<a href="apidocs/dev/org/apache/poi/hssf/record/crypto/Biff8EncryptionKey.html#setCurrentUserPassword(java.lang.String)">setCurrentUserPassword</a>(String password) + to specify the password.</p> + + <section> + <title>XOR/RC4 decryption for xls</title> + <source><![CDATA[ + Biff8EncryptionKey.setCurrentUserPassword("pass"); + POIFSFileSystem fs = new POIFSFileSystem(new File("file.xls"), true); + HSSFWorkbook hwb = new HSSFWorkbook(fs.getRoot(), true); + Biff8EncryptionKey.setCurrentUserPassword(null); + ]]></source> + </section> + + <section> + <title>RC4 CryptoApi support ppt - decryption</title> + <source><![CDATA[ + Biff8EncryptionKey.setCurrentUserPassword("pass"); + POIFSFileSystem fs = new POIFSFileSystem(new File("file.ppt"), true); + HSLFSlideShow hss = new HSLFSlideShow(fs); + ... + // Option 1: remove password + Biff8EncryptionKey.setCurrentUserPassword(null); + OutputStream os = new FileOutputStream("decrypted.ppt"); + hss.write(os); + os.close(); + ... + // Option 2: change encryption settings (experimental) + // need to cache data (i.e. read all data) before changing the key size + PictureData picsExpected[] = hss.getPictures(); + hss.getDocumentSummaryInformation(); + EncryptionInfo ei = hss.getDocumentEncryptionAtom().getEncryptionInfo(); + ((CryptoAPIEncryptionHeader)ei.getHeader()).setKeySize(0x78); + OutputStream os = new FileOutputStream("file_120bit.ppt"); + hss.write(os); + os.close(); + ]]></source> + </section> + </section> + + <section> + <title>XML-based formats - Decryption</title> + + <p>XML-based formats are stored in OLE-package stream "EncryptedPackage". Use org.apache.poi.poifs.crypt.Decryptor + to decode file:</p> + + <source><![CDATA[ + EncryptionInfo info = new EncryptionInfo(filesystem); + Decryptor d = Decryptor.getInstance(info); + + try { + if (!d.verifyPassword(password)) { + throw new RuntimeException("Unable to process: document is encrypted"); + } + + InputStream dataStream = d.getDataStream(filesystem); + + // parse dataStream + + } catch (GeneralSecurityException ex) { + throw new RuntimeException("Unable to process encrypted document", ex); + } + ]]></source> + + <p>If you want to read file encrypted with build-in password, use Decryptor.DEFAULT_PASSWORD.</p> + </section> + + <section> + <title>XML-based formats - Encryption</title> + + <p>Encrypting a file is similar to the above decryption process. Basically you'll need to choose between + <a href="apidocs/dev/org/apache/poi/poifs/crypt/EncryptionMode.html">binaryRC4, standard and agile encryption</a>, + the cryptoAPI mode is used internally and its direct use would result in an incomplete file. + Apart of the CipherMode, the EncryptionInfo class provides further parameters to specify the cipher and + hashing algorithm to be used.</p> + <source><![CDATA[ + try (POIFSFileSystem fs = new POIFSFileSystem()) { + EncryptionInfo info = new EncryptionInfo(EncryptionMode.agile); + // EncryptionInfo info = new EncryptionInfo(EncryptionMode.agile, CipherAlgorithm.aes192, HashAlgorithm.sha384, -1, -1, null); + + Encryptor enc = info.getEncryptor(); + enc.confirmPassword("foobaa"); + + // Read in an existing OOXML file and write to encrypted output stream + // don't forget to close the output stream otherwise the padding bytes aren't added + try (OPCPackage opc = OPCPackage.open(new File("..."), PackageAccess.READ_WRITE); + OutputStream os = enc.getDataStream(fs)) { + opc.save(os); + } + + // Write out the encrypted version + try (FileOutputStream fos = new FileOutputStream("...")) { + fs.writeFilesystem(fos); + } + } + ]]></source> + </section> + + <section> + <title>XML-based formats - Signing (XML Signature)</title> + + <note>As of <a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=64186">#64186</a> the configuration of the + OPCPackage has changed, the examples below have been adopted and reflect the POI 5.0.0 API</note> + + <p>An Office document can be digital signed by a <a href="https://en.wikipedia.org/wiki/XML_Signature">XML Signature</a> + to protect it from unauthorized modifications, i.e. modifications without having the original certificate. + The current implementation is based on the <!--<a href="http://eid-applet.googlecode.com">eID Applet</a>--> + <a href="https://github.com/e-Contract/eid-applet">eID Applet</a> which + is dual-licensed to + <a href="https://github.com/e-Contract/eid-applet/blob/master/README.md#7-license">Apache License 2.0 and LGPL v3.0</a>. + Instead of using the internal <a href="http://www.jsourcecode.com/class.php?proj=jdk%5Copenjdk&jar=openjdk-6-b14&class=org.jcp.xml.dsig.internal.dom.DOMXMLSignatureFactory">JDK API</a> + this version is based on <a href="https://santuario.apache.org">Apache Santuario</a>.</p> + <p>The classes have been tested against the following libraries, which need to be included additionally to the + <a href="site:components">default dependencies</a>:</p> + <ul> + <li>BouncyCastle bcpkix, bcprov and bcutil (tested against 1.81)</li> + <li>Apache Santuario "xmlsec" (tested against 3.0.5)</li> + <li>and slf4j-api (tested against 2.0.x)</li> + </ul> + <p>Depending on the <a href="apidocs/dev/org/apache/poi/poifs/crypt/dsig/SignatureConfig.html">configuration</a> + and the activated <a href="apidocs/dev/org/apache/poi/poifs/crypt/dsig/facets/package-summary.html">facets</a> + various <a href="https://en.wikipedia.org/wiki/XAdES">XAdES levels</a> are supported - the support for higher levels (XAdES-T+) + depend on supporting services and although the code is adopted, the integration is not well tested ... please support us on + integration (testing) with timestamp and revocation (OCSP) services. + </p> + <p>Further test examples can be found in the corresponding <a href="https://github.com/apache/poi/tree/trunk/poi-ooxml/src/test/java/org/apache/poi/poifs/crypt/dsig/TestSignatureInfo.java?view=markup">test class</a>.</p> + + <p>If you want to use a hash algorithm with 64 bytes (currently only applies to SHA512), + <a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=42061">a base64 "feature"</a> in xmlsec + leads to line breaks in the digest values, which won't be accepted by Office. To workaround this, you + need to set the following system property:<br/> + <strong>-Dorg.apache.xml.security.ignoreLineBreaks=true</strong></p> + </section> + + <section> + <title>Validating a signed office document</title> + + <source><![CDATA[ + OPCPackage pkg = OPCPackage.open(..., PackageAccess.READ); + SignatureConfig sic = new SignatureConfig(); + SignatureInfo si = new SignatureInfo(); + si.setOpcPackage(pkg); + si.setSignatureConfig(sic); + boolean isValid = si.verifySignature(); + ... + ]]></source> + </section> + + <section> + <title>Signing an office document</title> + + <section> + <title>Signing a file</title> + <source><![CDATA[ + // loading the keystore - pkcs12 is used here, but of course jks & co are also valid + // the keystore needs to contain a private key and it's certificate having a + // 'digitalSignature' key usage + char password[] = "test".toCharArray(); + File file = new File("test.pfx"); + KeyStore keystore = KeyStore.getInstance("PKCS12"); + FileInputStream fis = new FileInputStream(file); + keystore.load(fis, password); + fis.close(); + + // extracting private key and certificate + String alias = "xyz"; // alias of the keystore entry + Key key = keystore.getKey(alias, password); + X509Certificate x509 = (X509Certificate)keystore.getCertificate(alias); + + // filling the SignatureConfig entries (minimum fields, more options are available ...) + SignatureConfig signatureConfig = new SignatureConfig(); + signatureConfig.setKey(keyPair.getPrivate()); + signatureConfig.setSigningCertificateChain(Collections.singletonList(x509)); + + // adding the signature document to the package + SignatureInfo si = new SignatureInfo(); + OPCPackage pkg = OPCPackage.open(..., PackageAccess.READ_WRITE); + si.setOpcPackage(pkg); + si.setSignatureConfig(signatureConfig); + si.confirmSignature(); + // optionally verify the generated signature + boolean b = si.verifySignature(); + assert (b); + // write the changes back to disc + pkg.close(); + ]]></source> + </section> + + <section> + <title>Signing a stream - in-memory</title> + + <p>When saving a OOXML document, POI creates missing relations on the fly. Therefore calling the signing method before + would result in an invalid signature. Instead of trying to fix all save invocations, the user is asked to save the stream + before in an intermediate byte array (stream) and process this stream instead.</p> + + <source><![CDATA[ + // load the key and setup SignatureConfig ... - see "Signing a file" + + SignatureInfo si = new SignatureInfo(); + si.setSignatureConfig(signatureConfig); + + // populate sample object + XSSFWorkbook wb = new XSSFWorkbook(); + wb.createSheet().createRow(1).createCell(1).setCellValue("Test"); + ByteArrayOutputStream bos = new ByteArrayOutputStream(100000); + wb.write(bos); + wb.close(); + + // process the + OPCPackage pkg = OPCPackage.open(new ByteArrayInputStream(bos.toByteArray())); + + si.setOpcPackage(pkg); + si.confirmSignature(); + bos.reset(); + pkg.save(bos); + pkg.close(); + + // bos now contains the signed ooxml document + ]]></source> + </section> + </section> + + <section> + <title>Encrypting temporary files created when unzipping an OOXML document</title> + + <p>For security-conscious environments where data at rest must be stored encrypted, + the creation of plaintext temporary files is a grey area.</p> + + <p>The code example, written by PJ Fanning, modifies the behavior of SXSSFWorkbook + to extract an OOXML spreadsheet zipped container and write the contents to disk using AES + encryption.</p> + + <p>See <a href="https://github.com/apache/poi/tree/trunk/poi-ooxml/src/main/java/org/apache/poi/poifs/crypt/temp/SXSSFWorkbookWithCustomZipEntrySource.java?view=markup">SXSSFWorkbookWithCustomZipEntrySource.java</a> + and other <a href="https://svn.apache.org/viewvc?view=revision&revision=1768744">files</a> + that are needed for this example.</p> + </section> + + <section> + <title>Debugging XML signature issues</title> + <p>Finding the source of a XML signature problem can be sometimes a pain in the ... neck, because + the hashing of the canonicalized form is more or less done in the background.</p> + + <!-- TODO: find original source --> + <p>One of the tripping hazards are <a href="https://stackoverflow.com/questions/36063375">different + linebreaks in Windows/Unix</a>, therefore use the non-indent form of the xmls. Furthermore the + elements/ancestors containing namespace definitions and the used prefix might also differ.</p> + + <p>The next thing is to compare successful signed documents from Office vs. POIs generated signature, + i.e. unzip both files and look for differences. Usually the package relations (*.rels) will be different, + and the sig1.xml, core.xml and [Content_Types].xml due to different order of the references.</p> + + <p>The package relationships (*.rels) will be specially handled, i.e. they will be filtered and only + a subset will be processed - see <a href="https://www.ecma-international.org/activities/Office%20Open%20XML%20Formats/Draft%20ECMA-376%203rd%20edition,%20March%202011/Office%20Open%20XML%20Part%202%20-%20Open%20Packaging%20Conventions.pdf">13.2.4.24 Relationships Transform Algorithm</a>.</p> + + <p>POI and Santuario (XmlSec) use <a href="https://logging.apache.org/log4j/2.x">Log4J 2.x</a> and + <a href="https://www.slf4j.org/">SLF4J</a> respectively for logging.</p> + + <ul> + <li> + (Since the change to Log4J 2 in POI 5.1.0, this hasn't been tested, and you need to adapt the + logging settings to get all log output of XmlSec and POI) + </li> + <li> + add the following JVM parameters: + <source><![CDATA[ + -Djava.io.tmpdir=<custom temp directory> + -Xbootclasspath/p:<preload dir, which contains /org/apache/xml/security/utils/UnsyncBufferedOutputStream.class> + ]]></source> + </li> + <li> + To check the processed files in the canonicalized form, the below UnsyncBufferedOutputStream class needs + to be injected/replaced. Put the .class file in separate directory and add it to the JVM parameters (see above): + + <source><![CDATA[ + package org.apache.xml.security.utils; + + import java.io.File; + import java.io.FileOutputStream; + import java.io.IOException; + import java.io.OutputStream; + + public class UnsyncBufferedOutputStream extends OutputStream { + static final int size = 8*1024; + static int filecnt = 0; + + private int pointer = 0; + private final OutputStream out; + private final FileOutputStream out2; + + private final byte[] buf; + + public UnsyncBufferedOutputStream(OutputStream out) { + buf = new byte[size]; + this.out = out; + synchronized(UnsyncBufferedOutputStream.class) { + try { + String tmpDir = System.getProperty("java.io.tmpdir"); + if (tmpDir == null) { + tmpDir = "build"; + } + File f = new File(tmpDir, "unsync-"+filecnt+".xml"); + out2 = new FileOutputStream(f); + } catch (IOException e) { + throw new RuntimeException(e); + } finally { + filecnt++; + } + } + } + + public void write(byte[] arg0) throws IOException { + write(arg0, 0, arg0.length); + } + + public void write(byte[] arg0, int arg1, int len) throws IOException { + int newLen = pointer+len; + if (newLen > size) { + flushBuffer(); + if (len > size) { + out.write(arg0, arg1,len); + out2.write(arg0, arg1,len); + return; + } + newLen = len; + } + System.arraycopy(arg0, arg1, buf, pointer, len); + pointer = newLen; + } + + private void flushBuffer() throws IOException { + if (pointer > 0) { + out.write(buf, 0, pointer); + out2.write(buf, 0, pointer); + } + pointer = 0; + + } + + public void write(int arg0) throws IOException { + if (pointer >= size) { + flushBuffer(); + } + buf[pointer++] = (byte)arg0; + + } + + public void flush() throws IOException { + flushBuffer(); + out.flush(); + out2.flush(); + } + + public void close() throws IOException { + flush(); + out.close(); + out2.close(); + } + + } + ]]></source> + </li> + </ul> + </section> + </body> + + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/help/faq.xml b/src/documentation/content/xdocs/help/faq.xml new file mode 100644 index 0000000000..28541a1146 --- /dev/null +++ b/src/documentation/content/xdocs/help/faq.xml @@ -0,0 +1,742 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V2.0//EN" "faq-v20.dtd"> + +<faqs> + <title>Frequently Asked Questions</title> + <faq id="faq-N10006"> + <question> + My code uses some new feature, compiles fine but fails when live with a "MethodNotFoundException" or "IncompatibleClassChangeError" + </question> + <answer> + <p>You almost certainly have an older version of Apache POI + on your classpath. Quite a few runtimes and other packages + will ship older version of Apache POI, so this is an easy problem + to hit without your realising. Some will ship just one old jar, + some may ship a full set of old POI jars.</p> + <p>The best way to identify the offending earlier jar files is + with a few lines of java. These will load a Core POI class, an + OOXML class and a Scratchpad class, and report where they all came + from.</p> + <source><![CDATA[ +ClassLoader classloader = + org.apache.poi.poifs.filesystem.POIFSFileSystem.class.getClassLoader(); +URL res = classloader.getResource( + "org/apache/poi/poifs/filesystem/POIFSFileSystem.class"); +String path = res.getPath(); +System.out.println("POI Core came from " + path); + +classloader = org.apache.poi.ooxml.POIXMLDocument.class.getClassLoader(); +res = classloader.getResource("org/apache/poi/ooxml/POIXMLDocument.class"); +path = res.getPath(); +System.out.println("POI OOXML came from " + path); + +classloader = org.apache.poi.hslf.usermodel.HSLFSlideShow.class.getClassLoader(); +res = classloader.getResource("org/apache/poi/hslf/usermodel/HSLFSlideShow.class"); +path = res.getPath(); +System.out.println("POI Scratchpad came from " + path);]]></source> + </answer> + </faq> + <faq id="faq-N10019"> + <question> + My code uses the scratchpad, compiles fine but fails to run with a "MethodNotFoundException" + </question> + <answer> + <p>You almost certainly have an older version earlier on your + classpath. See the prior answer.</p> + </answer> + </faq> + <faq id="faq-N10025"> + <question> + I'm using the poi-ooxml-lite (previously known as poi-ooxml-schemas) jar, but my code is failing with "java.lang.NoClassDefFoundError: org/openxmlformats/schemas/*something*" + </question> + <answer> + <p>To use the new OOXML file formats, POI requires a jar containing + the file format XSDs, as compiled by + <a href="https://xmlbeans.apache.org/">XMLBeans</a>. These + XSDs, once compiled into Java classes, live in the + <em>org.openxmlformats.schemas</em> namespace.</p> + <p>There are two jar files available, as described in + <a href="site:components">the components overview section</a>. + The <em>full jar of all of the schemas is poi-ooxml-full-XXX.jar (previously known as ooxml-schemas) + (lower versions for older releases, see table below)</em>, + and it is currently around 16mb. The <em>smaller poi-ooxml-lite (previously known as poi-ooxml-schemas) + jar</em> is only about 6mb. This latter jar file only contains the + typically used parts though.</p> + <p>Many users choose to use the smaller poi-ooxml-lite jar to save + space. However, the poi-ooxml-lite jar only contains the XSDs and + classes that are typically used, as identified by the unit tests. + Every so often, you may try to use part of the file format which + isn't included in the minimal poi-ooxml-lite jar. In this case, + you should switch to the full poi-ooxml-full jar. Longer term, + you may also wish to submit a new unit test which uses the extra + parts of the XSDs, so that a future poi-ooxml-lite jar will + include them.</p> + <p>There are a number of ways to get the full poi-ooxml-full jar. + If you are a maven user, see the + <a href="site:components">the components overview section</a> + for the artifact details to have maven download it for you. + If you download the source release of POI, and/or checkout the + source code from <a href="site:git">git</a>, + then you can run the ant task "compile-ooxml-xsds" to have the + OOXML schemas downloaded and compiled for you (This will also + give you the XMLBeans generated source code, in case you wish to + look at this). Finally, you can download the jar by hand from the + <a href="http://mirrors.ibiblio.org/apache/poi/">POI + Maven Repository</a>.</p> + <p>Note that historically, different versions of poi-ooxml-full / ooxml-schemas were + used</p> + + <table class="POITable autosize"> + <tr> + <th>Version of ooxml-schemas</th> + <th>Version of POI</th> + <th>Commment</th> + </tr> + <tr> + <td>ooxml-schemas-1.0.jar</td> + <td>POI 3.5 and 3.6</td> + <td></td> + </tr> + <tr> + <td>ooxml-schemas-1.1.jar</td> + <td>POI 3.7 to POI 3.13</td> + <td>Generics support added, can be used with POI 3.5 and POI 3.6 as well</td> + </tr> + <tr> + <td>ooxml-schemas-1.2.jar</td> + <td>-</td> + <td>Not released</td> + </tr> + <tr> + <td>ooxml-schemas-1.3.jar</td> + <td>POI 3.14 and newer</td> + <td>Visio XML format support added, can be used with POI 3.7 - POI 3.13 as well</td> + </tr> + <tr> + <td>ooxml-schemas-1.4.jar</td> + <td>POI 4.*.*</td> + <td>Provide schema for AlternateContent, can be used with previous versions of POI as well</td> + </tr> + <tr> + <td>poi-ooxml-full jar</td> + <td>POI 5.0.0 and newer</td> + <td>Upgrade to ECMA-376 5th edition - which is not downward compatible</td> + </tr> + </table> + </answer> + </faq> + <faq id="faq-N100B6"> + <question> + Why is reading a simple sheet taking so long? + </question> + <answer> + <p>You've probably enabled logging. Logging is intended only for + autopsy style debugging. Having it enabled will reduce performance + by a factor of at least 100. Logging is helpful for understanding + why POI can't read some file or developing POI itself. Important + errors are thrown as exceptions, which means you probably don't need + logging.</p> + </answer> + </faq> + <faq id="faq-N100C2"> + <question> + What is the HSSF "eventmodel"? + </question> + <answer> + <p>The SS eventmodel package is an API for reading Excel files without loading the whole spreadsheet into memory. It does + require more knowledge on the part of the user, but reduces memory consumption by more than + tenfold. It is based on the AWT event model in combination with SAX. If you need read-only + access, this is the best way to do it.</p> + </answer> + </faq> + <faq id="faq-N100CE"> + <question> + Why can't read the document I created using Star Office 5.1? + </question> + <answer> + <p>Star Office 5.1 writes some records using the older BIFF standard. This causes some problems + with POI which supports only BIFF8.</p> + </answer> + </faq> + <faq id="faq-N100DA"> + <question> + Why am I getting an exception each time I attempt to read my spreadsheet? + </question> + <answer> + <p>It's possible your spreadsheet contains a feature that is not currently supported by POI. + If you encounter this then please create the simplest file that demonstrates the trouble and submit it to + <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bugzilla.</a></p> + </answer> + </faq> + <faq id="faq-N100E9"> + <question> + How do you tell if a spreadsheet cell contains a date? + </question> + <answer> + <p>Excel stores dates as numbers therefore the only way to determine if a cell is + actually stored as a date is to look at the formatting. There is a helper method + in HSSFDateUtil that checks for this. + Thanks to Jason Hoffman for providing the solution.</p> + <source><![CDATA[ +case HSSFCell.CELL_TYPE_NUMERIC: + double d = cell.getNumericCellValue(); + // test if a date! + if (HSSFDateUtil.isCellDateFormatted(cell)) { + // format in form of M/D/YY + cal.setTime(HSSFDateUtil.getJavaDate(d)); + cellText = + (String.valueOf(cal.get(Calendar.YEAR))).substring(2); + cellText = cal.get(Calendar.MONTH)+1 + "/" + + cal.get(Calendar.DAY_OF_MONTH) + "/" + + cellText; + }]]></source> + </answer> + </faq> + <faq id="faq-N100F9"> + <question> + I'm trying to stream an XLS file from a servlet and I'm having some trouble. What's the problem? + </question> + <answer> + <p> + The problem usually manifests itself as the junk characters being shown on + screen. The problem persists even though you have set the correct mime type. + </p> + <p> + The short answer is, don't depend on IE to display a binary file type properly if you stream it via a + servlet. Every minor version of IE has different bugs on this issue. + </p> + <p> + The problem in most versions of IE is that it does not use the mime type on + the HTTP response to determine the file type; rather it uses the file extension + on the request. Thus you might want to add a + <strong>.xls</strong> to your request + string. For example + <em>http://yourserver.com/myServelet.xls?param1=xx</em>. This is + easily accomplished through URL mapping in any servlet container. Sometimes + a request like + <em>http://yourserver.com/myServelet?param1=xx&dummy=file.xls</em> is also + known to work. + </p> + <p> + To guarantee opening the file properly in Excel from IE, write out your file to a + temporary file under your web root from your servlet. Then send an http response + to the browser to do a client side redirection to your temp file. (Note that using a + server side redirect using RequestDispatcher will not be effective in this case) + </p> + <p> + Note also that when you request a document that is opened with an + external handler, IE sometimes makes two requests to the webserver. So if your + generating process is heavy, it makes sense to write out to a temporary file, so that multiple + requests happen for a static file. + </p> + <p> + None of this is particular to Excel. The same problem arises when you try to + generate any binary file dynamically to an IE client. For example, if you generate + pdf files using + <a href="https://xml.apache.org/fop">FOP</a>, you will come across many of the same issues. + </p> + <!-- Thanks to Avik for the answer --> + </answer> + </faq> + <faq id="faq-N10123"> + <question> + I want to set a cell format (Data format of a cell) of an excel sheet as ###,###,###.#### or ###,###,###.0000. Is it possible using POI ? + </question> + <answer> + <p> + Yes. You first need to get a DataFormat object from the workbook and call getFormat with the desired format. Some examples are <a href="../components/spreadsheet/quick-guide.html#DataFormats">here</a>. + </p> + </answer> + </faq> + <faq id="faq-N10133"> + <question> + I want to set a cell format (Data format of a cell) of an excel sheet as text. Is it possible using POI ? + </question> + <answer> + <p> + Yes. This is a built-in format for excel that you can get from DataFormat object using the format string "@". Also, the string "text" will alias this format. + </p> + </answer> + </faq> + <faq id="faq-N1013F"> + <question> + How do I add a border around a merged cell? + </question> + <answer> + <p>Add blank cells around where the cells normally would have been and set the borders individually for each cell. + We will probably enhance HSSF in the future to make this process easier.</p> + </answer> + </faq> + <faq id="faq-N1014B"> + <question> + I am using styles when creating a workbook in POI, but Excel refuses to open the file, complaining about "Too Many Styles". + </question> + <answer> + <p>You just create the styles OUTSIDE of the loop in which you create cells.</p> + <p>GOOD:</p> + <source><![CDATA[ + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet("new sheet"); + HSSFRow row = null; + + // Aqua background + HSSFCellStyle style = wb.createCellStyle(); + style.setFillBackgroundColor(HSSFColor.AQUA.index); + style.setFillPattern(HSSFCellStyle.BIG_SPOTS); + HSSFCell cell = row.createCell((short) 1); + cell.setCellValue("X"); + cell.setCellStyle(style); + + // Orange "foreground", + // foreground being the fill foreground not the font color. + style = wb.createCellStyle(); + style.setFillForegroundColor(HSSFColor.ORANGE.index); + style.setFillPattern(HSSFCellStyle.SOLID_FOREGROUND); + + for (int x = 0; x < 1000; x++) { + + // Create a row and put some cells in it. Rows are 0 based. + row = sheet.createRow((short) k); + + for (int y = 0; y < 100; y++) { + cell = row.createCell((short) k); + cell.setCellValue("X"); + cell.setCellStyle(style); + } + } + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + </source> + <p>BAD:</p> + <source> + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet("new sheet"); + HSSFRow row = null; + + for (int x = 0; x < 1000; x++) { + // Aqua background + HSSFCellStyle style = wb.createCellStyle(); + style.setFillBackgroundColor(HSSFColor.AQUA.index); + style.setFillPattern(HSSFCellStyle.BIG_SPOTS); + HSSFCell cell = row.createCell((short) 1); + cell.setCellValue("X"); + cell.setCellStyle(style); + + // Orange "foreground", + // foreground being the fill foreground not the font color. + style = wb.createCellStyle(); + style.setFillForegroundColor(HSSFColor.ORANGE.index); + style.setFillPattern(HSSFCellStyle.SOLID_FOREGROUND); + + // Create a row and put some cells in it. Rows are 0 based. + row = sheet.createRow((short) k); + + for (int y = 0; y < 100; y++) { + cell = row.createCell((short) k); + cell.setCellValue("X"); + cell.setCellStyle(style); + } + } + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close();]]></source> + </answer> + </faq> + <faq id="faq-N10165"> + <question> + I think POI is using too much memory! What can I do? + </question> + <answer> + <p>This one comes up quite a lot, but often the reason isn't what + you might initially think. So, the first thing to check is - what's + the source of the problem? Your file? Your code? Your environment? + Or Apache POI?</p> + <p>(If you're here, you probably think it's Apache POI. However, it + often isn't! A moderate laptop, with a decent but not excessive heap + size, from a standing start, can normally read or write a file with + 100 columns and 100,000 rows in under a couple of seconds, including + the time to start the JVM).</p> + <p>Apache POI ships with a few programs and a few example programs, + which can be used to do some basic performance checks. For testing + file generation, the class to use is in the examples package, + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/SSPerformanceTest.java">SSPerformanceTest</a> + (<a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/SSPerformanceTest.java">viewvc</a>). + Run SSPerformanceTest with arguments of the writing type (HSSF, XSSF + or SXSSF), the number rows, the number of columns, and if the file + should be saved. If you can't run that with 50,000 rows and 50 columns + in HSSF and SXSSF in under 3 seconds, and XSSF in under 20 seconds + (and ideally all 3 in less than that!), then the problem is with + your environment.</p> + <p>Next, use the example program + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/ToCSV.java">ToCSV</a> + (<a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/ss/ToCSV.java">viewvc</a>) + to try reading the file in with HSSF or XSSF. Related is + <a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/eventusermodel/XLSX2CSV.java">XLSX2CSV</a> + (<a href="https://github.com/apache/poi/tree/trunk/poi-examples/src/main/java/org/apache/poi/examples/xssf/eventusermodel/XLSX2CSV.java">viewvc</a>), + which uses SAX parsing for .xlsx. Run this against both your problem file, + and a simple one generated by SSPerformanceTest of the same size. If this is + slow, then there could be an Apache POI problem with how the file is being + processed (POI makes some assumptions that might not always be right on all + files). If these tests are fast, then performance problems likely are in your + code.</p> + </answer> + </faq> + <faq id="faq-N10192"> + <question> + I can't seem to find the source for the OOXML CT.. classes, where do they + come from? + </question> + <answer> + <p>The OOXML support in Apache POI is built on top of the file format + XML Schemas, as compiled into Java using + <a href="https://xmlbeans.apache.org/">XMLBeans</a>. Currently, + the compilation is done with XMLBeans 5.x, for maximum compatibility + with installations.</p> + <p>All of the <em>org.openxmlformats.schemas.spreadsheetml.x2006</em> CT... + classes are auto-generated by XMLBeans. The resulting generated Java goes + in the <em>poi-ooxml-full-*-sources</em> jar, and the compiled version into the + <em>poi-ooxml-full</em> jar.</p> + <p>The full <em>poi-ooxml-full</em> jar is distributed with Apache POI, + along with the cut-down <em>poi-ooxml-lite</em> jar containing just + the common parts. Use the sources off <em>poi-ooxml-full</em> for the lite version, + which is available from Maven Central - ask your favourite Maven + mirror for the <em>poi-ooxml-full-*-sources</em> jar. Alternately, if you download + the POI source distribution (or checkout from Git) and build, Ant will + automatically compile it for you to generate the source and binary poi-ooxml-full jars.</p> + </answer> + </faq> + <faq id="faq-N101BA"> + <question> + An OLE2 ("binary") file is giving me problems, but I can't share it. How can I investigate the problem on my own? + </question> + <answer> + <p>The first thing to try is running the + <a href="https://blogs.msdn.com/b/officeinteroperability/archive/2011/07/12/microsoft-office-binary-file-format-validator-is-now-available.aspx">Binary File Format Validator</a> + from Microsoft against the file, which will report if the file + complies with the specification. If your input file doesn't, then this + may well explain why POI isn't able to process it correctly. You + should probably in this case speak to whoever is generating the file, + and have them fix it there. If your POI generated file is identified + as having an issue, and you're on the + <a href="site:howtobuild">latest codebase</a>, report a new + POI bug and include the details of the validation failure.</p> + <p>Another thing to try, especially if the file is valid but POI isn't + behaving as expected, are the POI Dev Tools for the component you're + using. For example, HSSF has <em>org.apache.poi.hssf.dev.BiffViewer</em> + which will allow you to view the file as POI does. This will often + allow you to check that things are being read as you expect, and + narrow in on problem records and structures.</p> + </answer> + </faq> + <faq id="faq-N101D4"> + <question> + An OOXML ("xml") file is giving me problems, but I can't share it. How can I investigate the problem on my own? + </question> + <answer> + <p>There's not currently a simple validator tool as there is for the + OLE2 based (binary) file formats, but checking the basics of a file + is generally much easier.</p> + <p>Files such as .xlsx, .docx and .pptx are actually a zip file of XML + files, with a special structure. Your first step in diagnosing the + issues with the input or output file will likely be to unzip the + file, and look at the XML of it. Newer versions of Office will + normally tell you which area of the file is problematic, so + narrow in on there. Looking at the XML, does it look correct?</p> + <p>When reporting bugs, ideally include the whole file, but if you're + unable to then include the snippet of XML for the problem area, and + reference the OOXML standard for what it should contain.</p> + </answer> + </faq> + <faq id="faq-N101E6"> + <question> + Why do I get a java.lang.NoClassDefFoundError: javax/xml/stream/XMLEventFactory.newFactory() + </question> + <answer> + <p><strong>Applies to versions <= 3.17 (Java 6): </strong></p> + <p>This error indicates that the class XMLEventFactory does not provide + functionality which POI is depending upon. There can be a number of + different reasons for this:</p> + <ul> + <li>Outdated xml-apis.jar, stax-apis.jar or xercesImpl.jar:<br/> + These libraries were required with Java 5 and lower, but are not actually + required with spec-compliant Java 6 implementations, so try removing those + libraries from your classpath. If this is not possible, try upgrading to a + newer version of those jar files. + </li> + <li>Running IBM Java 6 (potentially as part of WebSphere Application Server):<br/> + IBM Java 6 does not provide all the interfaces required by the XML standards, + only IBM Java 7 seems to provide the correct interfaces, so try upgrading + your JDK. + </li> + <li>Sun/Oracle Java 6 with outdated patchlevel:<br/> + Some of the interfaces were only included/fixed in some of the patchlevels for + Java 6. Try running with the latest available patchlevel or even better use + Java 7/8 where this functionality should be available in all cases. + </li> + </ul> + </answer> + </faq> + <faq id="faq-N10204"> + <question> + Can I mix POI jars from different versions? + </question> + <answer> + <p>No. This is not supported.</p> + <p>All POI jars in use must come from the same version. A combination + such as <em>poi-3.11.jar</em> and <em>poi-ooxml-3.9.jar</em> is not + supported, and will fail to work in unpredictable ways.</p> + <p>If you're not sure which POI jars you're using at runtime, and/or + you suspect it might not be the one you intended, see + <a href="#faq-N10006">this FAQ entry</a> for details on + diagnosing it. If you aren't sure what POI jars you need, see the + <a href="site:components">Components Overview</a> + for details</p> + </answer> + </faq> + <faq id="faq-N10224"> + <question> + Can I access/modify workbooks/documents/slideshows in multiple threads? + What are the multi-threading guarantees that Apache POI makes + </question> + <answer> + <p>In short: <em>Handling different document-objects in different threads will + work. Accessing the same document in multiple threads will not work.</em></p> + <p>This means the workbook/document/slideshow objects are not checked for + thread safety, but any globally held object like global caches or other + data structures are guarded against multi threaded access accordingly.</p> + <p>There have been + <a href="https://mail-archives.apache.org/mod_mbox/poi-user/201109.mbox/%3C1314859350817-4757295.post@n5.nabble.com%3E">discussions</a> + about accessing different Workbook-sheets + in different threads concurrently. While this may work to some degree, it may lead + to very hard to track errors as multi-threading issues typically only + manifest after long runtime when many threads are active and the system + is under high load, i.e. in production use! Also it might break in future + versions of Apache POI as we do not specifically test using the library + this way.</p> + </answer> + </faq> + <faq id="faq-N1023C"> + <question> + What are the advantages and disadvantages of the different constructor and + write methods? + </question> + <answer> + <p>Across most of the UserModel classes ( +<a href="../apidocs/dev/org/apache/poi/ooxml/POIDocument.html">POIDocument</a> +and +<a href="../apidocs/dev/org/apache/poi/ooxml/POIXMLDocument.html">POIXMLDocument</a>), + you can open the document from a read-only <em>File</em>, a read-write <em>File</em> + or an <em>InputStream</em>. You can always write out to an <em>OutputStream</em>, + and increasing also to a <em>File</em>. + </p> + <p>Opening your document from a <em>File</em> is suggested wherever possible. + This will always be quicker and lower memory then using an <em>InputStream</em>, + as the latter has to buffer things in memory.</p> + <p>When writing, you can use an <em>OutputStream</em> to write to a new file, or + overwrite an existing one (provided it isn't already open!). On slow links / disks, + wrapping with a <em>BufferedOutputStream</em> is suggested. To write like this, use +<a href="../apidocs/dev/org/apache/poi/POIDocument.html#write(java.io.OutputStream)">write(OutputStream)</a>. + </p> + <p>To write to the currently open file (an in-place write / replace), you need to + have opened your document from a <em>File</em>, not an <em>InputStream</em>. In + addition, you need to have opened from the <em>File</em> in read-write mode, not + read-only mode. To write to the currently open file, on formats that support it + (not all do), use +<a href="../apidocs/dev/org/apache/poi/POIDocument.html#write()">write()</a>. + </p> + <p>You can also write out to a new <em>File</em>. This is available no matter how + you opened the document, and will create/replace a new file. It is faster and lower + memory than writing to an <em>OutputStream</em>. However, you can't use this to + replace the currently open file, only files not currently open. To write to a + new / different file, use +<a href="../apidocs/dev/org/apache/poi/POIDocument.html#write(java.io.File)">write(File)</a> + </p> + <p>More information is also available in the +<a href="../components/spreadsheet/quick-guide.html#FileInputStream">HSSF and XSSF documentation</a>, + which largely applies to the other formats too. + </p> + <p>Note that currenly (POI 3.15 beta 3), not all of the write methods are available + for the OOXML formats yet. + </p> + </answer> + </faq> + <faq id="faq-N1029C"> + <question> + Can POI be used with OSGI? + </question> + <answer> + <p>Starting with POI 3.16 there's a workaround for OSGIs context classloader handling, + i.e. it replaces the threads current context classloader with an implementation of + limited class view. This will lead to IllegalStateExceptions, as xmlbeans can't find + the xml schema definitions in this reduced view. The workaround is to initialize + the classloader delegate of <em>POIXMLTypeLoader</em> , which defaults to the current + thread context classloader. The initialization should take place before any other + OOXML related calls. The class in the example could be any class, which is + part of the poi-ooxml-schema or ooxml-schema:<br/> + <em> POIXMLTypeLoader.setClassLoader(CTTable.class.getClassLoader());</em> + </p> + </answer> + </faq> + <faq id="faq-N102B0"> + <question> + Can Apache POI be compiled/used with Java 11, 17 and 21? + </question> + <answer> + <p> + POI is successfully tested with many different versions of Java. It is + recommended that you use Java versions that have Long Term Support (Java 11, 17 and 21). + </p> + <p>Including the existing binaries as normal jar-files + should work when using recent versions of Apache POI. You may see + some warnings about illegal reflective access, but it should work fine + despite those. We are working on getting the code changed so we avoid + discouraged accesses in the future. + </p> + <p>NOTE: Apache POI tries to support the Java module system but it is more complicated + because Apache POI is still supporting Java 8 and the module system + cannot be fully supported while maintaining such support. + </p> + <p> + FYI, jaxb in current versions also causes some warnings about reflective access, + we cannot fix those until jaxb >= 2.4.0 is available, see + https://stackoverflow.com/a/50251510/411846 for details, you can set a system + property "com.sun.xml.bind.v2.bytecode.ClassTailor.noOptimize" to avoid this warning. + </p> + <p> + For compiling Apache POI, you should use at least version 4.1.0 when it becomes available + or a recent trunk checkout until then. + </p> + <p> + If you are building POI yourself from source files, use an up to date version of Gradle. + If you use Ant, again check the Ant version supports the version of Java you are using. + </p> + </answer> + </faq> + <faq id="faq-java10"> + <question> + Can Apache POI be compiled/used with Java 9 or Java 10? + </question> + <answer> + <p>Apache POI does not actively support Java 9 or Java 10 any longer as those versions were + obsoleted by Oracle already. See the previous FAQ entry for information about support for + Java LTS versions. + </p> + </answer> + </faq> + <faq id="faq-ibmjdk"> + <question> + Anything to consider when using IBM JDK? + </question> + <answer> + <p>The IBM Java runtime is using a JIT compiler which doesn't behave sometimes. ;) + Especially when rendering slideshows it throws errors, which don't occur when debugging the code. + E.g. an ArrayIndexOutOfBoundsException is thrown in TexturePaintContext when the image contains + textures - see <a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=62999">#62999</a> for more + details on how to detected JIT errors.</p> + <p>To prevent the JIT errors, the affected methods need be excluded from JIT compiling. + Currently (tested with IBM JDK 1.8.0_144 and _191) the following should be added to the VM parameters:<br/> + </p> + <source> + -Xjit:exclude={sun/java2d/pipe/AAShapePipe.renderTiles(Lsun/java2d/SunGraphics2D;Ljava/awt/Shape;Lsun/java2d/pipe/AATileGenerator;[I)V},exclude={sun/java2d/pipe/AlphaPaintPipe.renderPathTile(Ljava/lang/Object;[BIIIIII)V},exclude={java/awt/TexturePaintContext.getRaster(IIII)Ljava/awt/image/Raster;} + </source> + </answer> + </faq> + <faq id="faq-thread-local-memory-leaks"> + <question> + Tomcat is reporting memory leaks caused by some class in Apache POI which uses ThreadLocal + </question> + <answer> + <p>Apache POI uses Java <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/ThreadLocal.html">ThreadLocals</a> + in order to cache some data when Apache POI is used in a multi-threading environment (see also the FAQ about thread-safety above!) + </p> + <p>WebServers like Tomcat use thread-pooling to re-use threads to avoid the cost of frequent thread-startup and shutdown. + In order to guard against memory-leaks, Tomcat performs checks on allocated memory in ThreadLocals and reports them as warnings. + </p> + <p>In order to get rid of these warnings, Apache POI, starting with version 5.2.4, provides a utility ThreadLocalUtils which can + be used to clear all objects held in thread-local objects before returning the thread back to the global pool. + </p> + <source> + org.apache.poi.util.ThreadLocalUtil.clearAllThreadLocals(); + + // if you use poi-ooxml, also clear thread-locals in XMLBeans + org.apache.xmlbeans.ThreadLocalUtil.clearAllThreadLocals(); + </source> + </answer> + </faq> + <faq id="faq-demand-fix-asap"> + <question> + How can I demand fixes or features in Apache POI to be done with urgency? + </question> + <answer> + <p>Apache POI is an open source project developed by a very small group of volunteers. + </p> + <p>Currently no-one is paid to work on new features or bug-fixes. + </p> + <p>So it is considered fairly rude to "demand" things, especially "ASAP" is quite frowned + upon and may even reduce the likelihood that your issue is picked up and worked on. + </p> + <p>If you would like to increase chances that your problem is tackled, you can do a number of things + as follows, sorted by the amount of effort which may be required from you: + </p> + <ul> + <li>Ensure your bug-report is complete and contains instructions/samples which allow to reproduce the problem. + Ideally a self-sufficient test-case which does not need lots of manual setup.</li> + <li>Provide a summary of research of the root-cause of your problem.</li> + <li>Provide a patch which fixes the problem. We usually like to have unit-tests accompanying changes to + have high code-coverage and good confidence that issues are fixed and few regressions are introduced + over time.</li> + <li>Become a contributor! The entry threshold is actually not too high as soon as you provided your + first successful bugfix. If you think you can spare the time to contribute for some longer time, + becoming an official committer should not be too hard.</li> + </ul> + </answer> + </faq> + <faq id="faq-reproducible-build-and-output"> + <question> + Does Apache POI support building reproducibly and/or producing reproducible output? + </question> + <answer> + <p>There are two angles to reproducibility: building reproducible jars for Apache POI itself and making Apache POI + produce byte-for-byte identical files when it is used to create documents. + </p> + <ul> + <li>The build of jars for Apache POI should be reproducible since version 5.2.4 by removing the build-timestamp + from the generated Version.java. Make sure the exact same combination of build-tools is used, + especially the version of the JDK.</li> + <li>Producing reproducible output files will be supported in the future (after version 5.3.0), initial support is available in + nightly builds.<br/> + Note: Files are only written without timestamps if the environment variable SOURCE_DATE_EPOCH is set to a + non-empty value.</li> + </ul> + <p>Please create a bug entry if you find things which break reproducibility, both for building and output files.<br/> + Please provide exact steps how to reproduce your issue! + </p> + <p>See <a href="https://reproducible-builds.org/">https://reproducible-builds.org/</a> for general information about why reproducible builds + and output may be important. + </p> + </answer> + </faq> +</faqs> diff --git a/src/documentation/content/xdocs/help/index.xml b/src/documentation/content/xdocs/help/index.xml new file mode 100644 index 0000000000..b7f4fbd24c --- /dev/null +++ b/src/documentation/content/xdocs/help/index.xml @@ -0,0 +1,142 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Mailing Lists</title> + <authors> + <person id="NB" name="Nick Burch" email="nick@apache.org"/> + </authors> + </header> + + <body> + <section><title>Mailing Lists - Guidelines</title> + <p> + <strong>Before subscribing or participating in any of the mailing + lists, we suggest you read and understand the following + guidelines:</strong> + </p> + <ul> + <li><a href="https://www.apache.org/foundation/mailinglists.html">ASF guide to Mailing Lists</a></li> + <li><a href="https://www.apache.org/dev/contrib-email-tips.html">ASF Tips for email contributors</a></li> + <li><a href="https://jakarta.apache.org/site/mail.html">The Jakarta guide to Mailing Lists</a></li> + </ul> + </section> + <section><title>Lists</title> + <section><title>The POI Developer List</title> + <p> + <strong>Medium Traffic</strong> + <a href="https://lists.apache.org/list.html?dev@poi.apache.org">View, + Participate and Subscribe to the Dev List</a> + </p> + <p> + This is the list where participating developers of the POI + project meet and discuss issues, code changes/additions, etc. + Subscribers to this list also get notices of each and every + code change, build results, testing notices, etc. + <strong>Do not send mail to this list with usage questions or + configuration problems. Use the <a href="#The+POI+User+List">POI User List</a> or community sites + such as <a href="#Stack+Overflow+and+other+communities">Stack Overflow</a>, instead.</strong> + </p> + <p> + Alternate options: + <a href="mailto:dev-subscribe@poi.apache.org">Subscribe</a> + <a href="mailto:dev-unsubscribe@poi.apache.org">Unsubscribe</a> + <a href="https://mail-archives.apache.org/mod_mbox/poi-dev/">Old Archive</a> + <!--a href="http://news.gmane.org/gmane.comp.jakarta.poi.devel">gmane.org</a--> + <a href="http://apache-poi.1045710.n5.nabble.com/POI-Dev-f2312866.html">Nabble</a> + <a href="http://markmail.org/search/org.apache.poi.dev+list:org.apache.poi.dev">MarkMail</a> + </p> + </section> + <section><title>The POI User List</title> + <p> + <strong>Low Traffic</strong> + <a href="https://lists.apache.org/list.html?user@poi.apache.org">View, + Participate and Subscribe to the User List</a> + </p> + <p> + This list is for users of POI to ask questions, share knowledge, + and discuss issues. POI developers are also expected to be + lurking on this list to offer support to users of POI. + </p> + <p> + Alternate options: + <a href="mailto:user-subscribe@poi.apache.org">Subscribe</a> + <a href="mailto:user-unsubscribe@poi.apache.org">Unsubscribe</a> + <a href="https://mail-archives.apache.org/mod_mbox/poi-user/">Old Archive</a> + <!--a href="http://news.gmane.org/thread.php?group=gmane.comp.jakarta.poi.user">gmane.org</a--> + <a href="http://apache-poi.1045710.n5.nabble.com/POI-User-f2280730.html">Nabble</a> + <a href="http://markmail.org/search/org.apache.poi.user+list:org.apache.poi.user">MarkMail</a> + </p> + </section> + <section><title>The POI General List</title> + <p> + <strong>Very Low Traffic</strong> + <a href="https://lists.apache.org/list.html?general@poi.apache.org">View, + Participate and Subscribe to the General List</a> + </p> + <p> + This list exists for general discussions on POI, not specific to + code or problems with code. Used for discussion of general matters + relating to all of the POI project, such as the website and + changes in procedures. + </p> + <p> + Alternate options: + <a href="mailto:general-subscribe@poi.apache.org">Subscribe</a> + <a href="mailto:general-unsubscribe@poi.apache.org">Unsubscribe</a> + <a href="https://mail-archives.apache.org/mod_mbox/poi-general/">Old Archive</a> + </p> + </section> + </section> + <section><title>Stack Overflow and other communities</title> + <p> + There are many POI users in the Stack Overflow community who have asked + and answered questions that may be similar to the problem you are facing. + Search for the <a href="http://stackoverflow.com/questions/tagged/apache-poi">apache-poi</a> + tag on Stack Overflow. + </p> + <p>Regardless of which community you seek help from, remember to be courteous. + Short, working code examples, an explanation of observed and expected behavior, + the version of POI you are using, and genuine troubleshooting and research effort + on your part go a long way towards getting a helpful answer. + </p> + <p>Please read through the <a href="site:faq">FAQ</a>, + <a href="site:ssquickguide">Quick Guide</a>, + <a href="site:sshowto">How To</a> or + <a href="site:xslfcook">Cookbook</a>, and + <a href="site:ssexamples">Examples</a> + of the POI module that you are trying to use before consulting help. You may also find your + question has already been answered on the POI <a href="#The+POI+Developer+List">dev</a> + or <a href="#The+POI+User+List">user</a> mailing lists, + <a href="https://bz.apache.org/bugzilla/describecomponents.cgi?product=POI">bugzilla</a>, + </p> + </section> + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/images/add.png b/src/documentation/content/xdocs/images/add.png Binary files differnew file mode 100644 index 0000000000..7bb9021c39 --- /dev/null +++ b/src/documentation/content/xdocs/images/add.png diff --git a/src/documentation/content/xdocs/images/favicon.ico b/src/documentation/content/xdocs/images/favicon.ico Binary files differnew file mode 100644 index 0000000000..26add0212d --- /dev/null +++ b/src/documentation/content/xdocs/images/favicon.ico diff --git a/src/documentation/content/xdocs/images/fix.png b/src/documentation/content/xdocs/images/fix.png Binary files differnew file mode 100644 index 0000000000..57d390f5a2 --- /dev/null +++ b/src/documentation/content/xdocs/images/fix.png diff --git a/src/documentation/content/xdocs/images/group-logo.png b/src/documentation/content/xdocs/images/group-logo.png Binary files differnew file mode 100644 index 0000000000..8c5a7b8da2 --- /dev/null +++ b/src/documentation/content/xdocs/images/group-logo.png diff --git a/src/documentation/content/xdocs/images/group.svg b/src/documentation/content/xdocs/images/group.svg new file mode 100644 index 0000000000..44da1b5512 --- /dev/null +++ b/src/documentation/content/xdocs/images/group.svg @@ -0,0 +1,522 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + version="1.1" + id="Layer_2" + x="0px" + y="0px" + viewBox="0 0 7127.6 2890" + enable-background="new 0 0 7127.6 2890" + xml:space="preserve" + sodipodi:docname="asf_logo.svg" + inkscape:export-filename="/home/kiwiwings/project/xmlbeans/site/src/documentation/resources/images/asf_logo.png" + inkscape:export-xdpi="6.6435986" + inkscape:export-ydpi="6.6435986" + inkscape:version="0.92.3 (2405546, 2018-03-11)"><metadata + id="metadata5077"><rdf:RDF><cc:Work + rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /></cc:Work></rdf:RDF></metadata><defs + id="defs5075" /><sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="3770" + inkscape:window-height="2096" + id="namedview5073" + showgrid="false" + inkscape:zoom="0.41360345" + inkscape:cx="3563.8" + inkscape:cy="1445" + inkscape:window-x="70" + inkscape:window-y="27" + inkscape:window-maximized="1" + inkscape:current-layer="Layer_2" /> +<path + fill="#6D6E71" + d="M7104.7,847.8c15.3,15.3,22.9,33.7,22.9,55.2c0,21.5-7.6,39.9-22.9,55.4c-15.3,15.4-33.8,23.1-55.6,23.1 c-21.8,0-40.2-7.6-55.4-22.9c-15.1-15.3-22.7-33.7-22.7-55.2c0-21.5,7.6-39.9,22.9-55.4c15.3-15.4,33.7-23.1,55.4-23.1 C7070.9,824.9,7089.4,832.5,7104.7,847.8z M7098.1,951.9c13.3-13.6,20-29.8,20-48.7s-6.6-35-19.8-48.5 c-13.2-13.4-29.4-20.1-48.6-20.1c-19.2,0-35.4,6.7-48.7,20.2c-13.3,13.5-19.9,29.7-19.9,48.7c0,19,6.6,35.2,19.7,48.6 c13.1,13.4,29.3,20.1,48.5,20.1S7084.7,965.4,7098.1,951.9z M7087.1,888.1c0,14-6.1,22.8-18.4,26.4l22.5,30.5h-18.2l-20.3-28.3 h-18.6v28.3h-14.7v-84.6h31.8c12.8,0,22,2.2,27.6,6.6C7084.4,871.4,7087.1,878.4,7087.1,888.1z M7068.2,900c3-2.4,4.4-6.5,4.4-12 c0-5.5-1.5-9.4-4.5-11.6c-3-2.2-8.4-3.2-16-3.2h-18v30.5h17.5C7059.7,903.6,7065.3,902.4,7068.2,900z" + id="path4880" /> +<path + fill="#6D6E71" + d="M1803.6,499.8v155.4h-20V499.8h-56.8v-19.2h133.9v19.2H1803.6z" + id="path4882" /> +<path + fill="#6D6E71" + d="M2082.2,655.2v-76.9h-105.2v76.9h-20V480.5h20v78.9h105.2v-78.9h20v174.7H2082.2z" + id="path4884" /> +<path + fill="#6D6E71" + d="M2241.4,499.8v57.4h88.1v19.2h-88.1v59.8h101.8v19h-121.8V480.5H2340v19.2H2241.4z" + id="path4886" /> +<path + fill="#D22128" + d="M1574.5,1852.4l417.3-997.6h80.1l417.3,997.6h-105.4l-129.3-311.9h-448.2l-127.9,311.9H1574.5z M2032.6,970 l-205.1,493.2h404.7L2032.6,970z" + id="path4888" /> +<path + fill="#D22128" + d="M2596.9,1852.4V854.8H3010c171.4,0,295.1,158.8,295.1,313.3c0,163-115.2,316.1-286.6,316.1h-324.6v368.1 H2596.9z M2693.9,1397.1h318.9c118,0,193.9-108.2,193.9-229c0-125.1-92.7-226.2-202.3-226.2h-310.5V1397.1z" + id="path4890" /> +<path + fill="#D22128" + d="M3250.5,1852.4l417.3-997.6h80.1l417.3,997.6h-105.4l-129.3-311.9h-448.2l-127.9,311.9H3250.5z M3708.6,970 l-205.1,493.2h404.7L3708.6,970z" + id="path4892" /> +<path + fill="#D22128" + d="M4637.3,849.1c177,0,306.3,89.9,368.1,217.8l-78.7,47.8c-63.2-132.1-186.9-177-295.1-177 c-238.9,0-369.5,213.6-369.5,414.5c0,220.6,161.6,420.1,373.7,420.1c112.4,0,244.5-56.2,307.7-185.5l81.5,42.1 c-64.6,148.9-241.7,231.8-394.8,231.8c-274,0-466.5-261.3-466.5-514.2C4163.8,1106.3,4336.6,849.1,4637.3,849.1z" + id="path4894" /> +<path + fill="#D22128" + d="M5949.1,854.8v997.6h-98.4v-466.5h-591.5v466.5h-96.9V854.8h96.9v444h591.5v-444H5949.1z" + id="path4896" /> +<path + fill="#D22128" + d="M6844.6,1765.2v87.1h-670.2V854.8H6832v87.1h-560.6v359.7h489v82.9h-489v380.8H6844.6z" + id="path4898" /> +<path + fill="#6D6E71" + d="M1667.6,2063.6c11.8,3.5,22.2,8.3,31,14.2l-10.3,22.6c-9-6-18.6-10.4-28.9-13.4c-10.2-2.9-20-4.4-29.2-4.4 c-13.6,0-24.5,2.4-32.6,7.3c-8.1,4.9-12.2,11.8-12.2,20.7c0,7.6,2.3,14,6.8,19c4.5,5,10.2,8.9,17,11.7c6.8,2.8,16.1,6,28,9.6 c14.4,4.6,26,8.9,34.7,12.9c8.8,4,16.3,9.9,22.5,17.8c6.2,7.8,9.3,18.2,9.3,31c0,11.7-3.2,21.8-9.5,30.6 c-6.3,8.7-15.3,15.5-26.8,20.3c-11.6,4.8-24.9,7.2-40,7.2c-15.1,0-29.7-2.9-43.9-8.7c-14.2-5.8-26.4-13.6-36.6-23.4l10.7-21.6 c9.6,9.4,20.7,16.7,33.3,21.9c12.6,5.2,24.8,7.8,36.8,7.8c15.3,0,27.3-3,36.1-8.9c8.8-5.9,13.2-13.9,13.2-23.9 c0-7.8-2.3-14.3-6.9-19.4c-4.6-5.1-10.3-9-17.1-11.9c-6.8-2.8-16.1-6-28-9.6c-14.2-4.2-25.7-8.3-34.6-12.2 c-8.9-3.9-16.4-9.7-22.5-17.5c-6.1-7.7-9.2-17.9-9.2-30.6c0-10.9,3-20.4,9-28.6c6-8.2,14.6-14.6,25.6-19.1 c11.1-4.5,23.8-6.8,38.2-6.8C1643.8,2058.3,1655.7,2060.1,1667.6,2063.6z" + id="path4900" /> +<path + fill="#6D6E71" + d="M1980.1,2072.8c16.8,9.4,30.2,22.3,40,38.4c9.8,16.2,14.8,33.9,14.8,53.3c0,19.5-4.9,37.4-14.8,53.6 c-9.8,16.3-23.2,29.1-40,38.6c-16.8,9.5-35.3,14.3-55.2,14.3c-20.3,0-38.8-4.7-55.7-14.3c-16.8-9.5-30.2-22.4-40-38.6 c-9.8-16.3-14.8-34.1-14.8-53.6c0-19.5,4.9-37.3,14.8-53.5c9.8-16.2,23.2-29,40-38.3c16.8-9.4,35.4-14,55.7-14 C1944.8,2058.6,1963.2,2063.3,1980.1,2072.8z M1881.9,2092.7c-13.1,7.4-23.6,17.5-31.4,30.1c-7.8,12.6-11.8,26.5-11.8,41.7 c0,15.3,3.9,29.3,11.8,42c7.8,12.7,18.3,22.8,31.4,30.2c13.1,7.4,27.4,11.1,42.9,11.1c15.5,0,29.7-3.7,42.7-11.1 c13-7.4,23.3-17.4,31.1-30.2c7.7-12.7,11.6-26.7,11.6-42s-3.9-29.2-11.6-41.8c-7.7-12.6-18.1-22.6-31.1-30 c-13-7.4-27.2-11.2-42.6-11.2C1909.4,2081.5,1895.1,2085.2,1881.9,2092.7z" + id="path4902" /> +<path + fill="#6D6E71" + d="M2186.5,2082.4v74h98.4v23.2h-98.4v90.2h-24.1v-210.6h133.8v23.2H2186.5z" + id="path4904" /> +<path + fill="#6D6E71" + d="M2491.6,2082.4v187.4h-24.1v-187.4h-68.4v-23.2h161.4v23.2H2491.6z" + id="path4906" /> +<path + fill="#6D6E71" + d="M2871.8,2269.8l-56.8-177.4l-57.6,177.4h-24.5l-70.5-210.6h25.9l57.9,182.7l57.1-182.4l24.1-0.3l57.7,182.7 l57.1-182.7h25l-70.6,210.6H2871.8z" + id="path4908" /> +<path + fill="#6D6E71" + d="M3087.3,2216.6l-23.5,53.2h-25.6l94.4-210.6h25l94.1,210.6h-26.1l-23.5-53.2H3087.3z M3144.5,2086.6 l-46.9,106.8h94.4L3144.5,2086.6z" + id="path4910" /> +<path + fill="#6D6E71" + d="M3461.1,2202.7c-6,0.4-10.7,0.6-14.1,0.6h-56v66.5H3367v-210.6h80c26.2,0,46.6,6.2,61.2,18.5 c14.5,12.3,21.8,29.8,21.8,52.3c0,17.2-4.1,31.7-12.2,43.3c-8.1,11.6-19.8,20-35,25l49.2,71.5h-27.3L3461.1,2202.7z M3491.3,2167.6 c10.3-8.4,15.5-20.8,15.5-37c0-15.9-5.2-27.9-15.5-36c-10.3-8.1-25.1-12.2-44.3-12.2h-56v97.8h56 C3466.2,2180.2,3481,2176,3491.3,2167.6z" + id="path4912" /> +<path + fill="#6D6E71" + d="M3688.3,2082.4v69.2h106.2v23.2h-106.2v72.1h122.8v22.9h-146.9v-210.6h142.9v23.2H3688.3z" + id="path4914" /> +<path + fill="#6D6E71" + d="M4147,2082.4v74h98.4v23.2H4147v90.2h-24.1v-210.6h133.8v23.2H4147z" + id="path4916" /> +<path + fill="#6D6E71" + d="M4523.3,2072.8c16.8,9.4,30.2,22.3,40,38.4c9.8,16.2,14.8,33.9,14.8,53.3c0,19.5-4.9,37.4-14.8,53.6 c-9.8,16.3-23.2,29.1-40,38.6c-16.8,9.5-35.3,14.3-55.2,14.3c-20.3,0-38.8-4.7-55.7-14.3c-16.8-9.5-30.2-22.4-40-38.6 c-9.8-16.3-14.8-34.1-14.8-53.6c0-19.5,4.9-37.3,14.8-53.5c9.8-16.2,23.2-29,40-38.3c16.8-9.4,35.4-14,55.7-14 C4488.1,2058.6,4506.5,2063.3,4523.3,2072.8z M4425.2,2092.7c-13.1,7.4-23.6,17.5-31.4,30.1c-7.8,12.6-11.8,26.5-11.8,41.7 c0,15.3,3.9,29.3,11.8,42c7.8,12.7,18.3,22.8,31.4,30.2c13.1,7.4,27.4,11.1,42.9,11.1c15.5,0,29.7-3.7,42.7-11.1 c13-7.4,23.3-17.4,31.1-30.2c7.7-12.7,11.6-26.7,11.6-42s-3.9-29.2-11.6-41.8c-7.7-12.6-18.1-22.6-31.1-30 c-13-7.4-27.2-11.2-42.6-11.2C4452.6,2081.5,4438.3,2085.2,4425.2,2092.7z" + id="path4918" /> +<path + fill="#6D6E71" + d="M4854.7,2247.7c-15.7,15.5-37.3,23.3-64.8,23.3c-27.7,0-49.4-7.8-65.1-23.3c-15.7-15.5-23.6-37-23.6-64.6 v-124h24.1v124c0,20.3,5.8,36.1,17.3,47.5c11.6,11.4,27.3,17.1,47.3,17.1c20.1,0,35.8-5.7,47.1-17c11.4-11.3,17-27.2,17-47.7v-124 h24.1v124C4878.2,2210.7,4870.4,2232.2,4854.7,2247.7z" + id="path4920" /> +<path + fill="#6D6E71" + d="M5169.5,2269.8l-126.3-169.1v169.1h-24.1v-210.6h25l126.3,169.3v-169.3h23.8v210.6H5169.5z" + id="path4922" /> +<path + fill="#6D6E71" + d="M5478.4,2073.1c16.4,9.3,29.4,21.9,38.9,37.9c9.6,16,14.3,33.9,14.3,53.5s-4.8,37.6-14.3,53.6 c-9.5,16.1-22.6,28.7-39.3,37.9c-16.6,9.2-35.2,13.8-55.5,13.8h-84.3v-210.6h85.2C5443.7,2059.2,5462,2063.8,5478.4,2073.1z M5362.3,2246.9h61.4c15.5,0,29.6-3.5,42.3-10.6c12.7-7.1,22.8-16.9,30.2-29.5c7.4-12.5,11.1-26.5,11.1-42 c0-15.5-3.8-29.4-11.3-41.9c-7.5-12.5-17.7-22.3-30.6-29.6c-12.8-7.2-27-10.9-42.6-10.9h-60.5V2246.9z" + id="path4924" /> +<path + fill="#6D6E71" + d="M5668.6,2216.6l-23.5,53.2h-25.6l94.4-210.6h25l94.1,210.6H5807l-23.5-53.2H5668.6z M5725.8,2086.6 l-46.9,106.8h94.4L5725.8,2086.6z" + id="path4926" /> +<path + fill="#6D6E71" + d="M5991,2082.4v187.4H5967v-187.4h-68.4v-23.2h161.4v23.2H5991z" + id="path4928" /> +<path + fill="#6D6E71" + d="M6175.9,2269.8v-210.6h24.1v210.6H6175.9z" + id="path4930" /> +<path + fill="#6D6E71" + d="M6493.7,2072.8c16.8,9.4,30.2,22.3,40,38.4c9.8,16.2,14.8,33.9,14.8,53.3c0,19.5-4.9,37.4-14.8,53.6 c-9.8,16.3-23.2,29.1-40,38.6c-16.8,9.5-35.3,14.3-55.2,14.3c-20.3,0-38.8-4.7-55.7-14.3c-16.8-9.5-30.2-22.4-40-38.6 c-9.8-16.3-14.8-34.1-14.8-53.6c0-19.5,4.9-37.3,14.8-53.5c9.8-16.2,23.2-29,40-38.3c16.8-9.4,35.4-14,55.7-14 C6458.5,2058.6,6476.9,2063.3,6493.7,2072.8z M6395.6,2092.7c-13.1,7.4-23.6,17.5-31.4,30.1c-7.8,12.6-11.8,26.5-11.8,41.7 c0,15.3,3.9,29.3,11.8,42c7.8,12.7,18.3,22.8,31.4,30.2c13.1,7.4,27.4,11.1,42.9,11.1c15.5,0,29.7-3.7,42.7-11.1 c13-7.4,23.3-17.4,31.1-30.2c7.7-12.7,11.6-26.7,11.6-42s-3.9-29.2-11.6-41.8c-7.7-12.6-18.1-22.6-31.1-30 c-13-7.4-27.2-11.2-42.6-11.2C6423,2081.5,6408.8,2085.2,6395.6,2092.7z" + id="path4932" /> +<path + fill="#6D6E71" + d="M6826.5,2269.8l-126.3-169.1v169.1h-24.1v-210.6h25l126.3,169.3v-169.3h23.8v210.6H6826.5z" + id="path4934" /> +<linearGradient + id="SVGID_1_" + gradientUnits="userSpaceOnUse" + x1="-4516.6152" + y1="-2338.7222" + x2="-4108.4111" + y2="-1861.3982" + gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)"> + <stop + offset="0" + style="stop-color:#F69923" + id="stop4936" /> + <stop + offset="0.3123" + style="stop-color:#F79A23" + id="stop4938" /> + <stop + offset="0.8383" + style="stop-color:#E97826" + id="stop4940" /> +</linearGradient> +<path + fill="url(#SVGID_1_)" + d="M1230.1,13.7c-45.3,26.8-120.6,102.5-210.5,212.3l82.6,155.9c58-82.9,116.9-157.5,176.3-221.2 c4.6-5.1,7-7.5,7-7.5c-2.3,2.5-4.6,5-7,7.5c-19.2,21.2-77.5,89.2-165.5,224.4c84.7-4.2,214.9-21.6,321.1-39.7 c31.6-177-31-258-31-258S1323.4-41.4,1230.1,13.7z" + id="path4943" /> +<path + fill="none" + d="M1090.2,903.1c0.6-0.1,1.2-0.2,1.8-0.3l-11.9,1.3c-0.7,0.3-1.4,0.7-2.1,1 C1082.1,904.4,1086.2,903.7,1090.2,903.1z" + id="path4945" /> +<path + fill="none" + d="M1005.9,1182.3c-6.7,1.5-13.7,2.7-20.7,3.7C992.3,1185,999.2,1183.8,1005.9,1182.3z" + id="path4947" /> +<path + fill="none" + d="M432.9,1808.8c0.9-2.3,1.8-4.7,2.6-7c18.2-48,36.2-94.7,54-140.1c20-51,39.8-100.4,59.3-148.3 c20.6-50.4,40.9-99.2,60.9-146.3c21-49.4,41.7-97,62-142.8c16.5-37.3,32.8-73.4,48.9-108.3c5.4-11.7,10.7-23.2,16-34.6 c10.5-22.7,21-44.8,31.3-66.5c9.5-20,19-39.6,28.3-58.8c3.1-6.4,6.2-12.8,9.3-19.1c0.5-1,1-2,1.5-3.1l-10.2,1.1l-8-15.9 c-0.8,1.6-1.6,3.1-2.4,4.6c-14.5,28.8-28.9,57.9-43.1,87.2c-8.2,16.9-16.4,34-24.6,51c-22.6,47.4-44.8,95.2-66.6,143.3 c-22.1,48.6-43.7,97.5-64.9,146.5c-20.8,48.1-41.3,96.2-61.2,144.2c-20,48-39.5,95.7-58.5,143.2c-19.9,49.5-39.2,98.7-58,147.2 c-4.2,10.9-8.5,21.9-12.7,32.8c-15,39.2-29.7,77.8-44,116l12.7,25.1l11.4-1.2c0.4-1.1,0.8-2.3,1.3-3.4 C396.7,1905.4,414.9,1856.4,432.9,1808.8z" + id="path4949" /> +<path + fill="none" + d="M980,1186.8L980,1186.8c0.1,0,0.1,0,0.1-0.1C980.1,1186.8,980.1,1186.8,980,1186.8z" + id="path4951" /> +<path + fill="#BE202E" + d="M952.6,1323c-10.6,1.9-21.4,3.8-32.5,5.7c-0.1,0-0.1,0.1-0.2,0.1c5.6-0.8,11.2-1.7,16.6-2.6 C942,1325.2,947.3,1324.1,952.6,1323z" + id="path4953" /> +<path + opacity="0.35" + fill="#BE202E" + d="M952.6,1323c-10.6,1.9-21.4,3.8-32.5,5.7c-0.1,0-0.1,0.1-0.2,0.1c5.6-0.8,11.2-1.7,16.6-2.6 C942,1325.2,947.3,1324.1,952.6,1323z" + id="path4955" /> +<path + fill="#BE202E" + d="M980.3,1186.7C980.2,1186.7,980.2,1186.7,980.3,1186.7c-0.1,0.1-0.2,0.1-0.2,0.1c1.8-0.2,3.5-0.5,5.2-0.8 c7-1,13.9-2.2,20.7-3.7C997.5,1183.8,989,1185.2,980.3,1186.7L980.3,1186.7L980.3,1186.7z" + id="path4957" /> +<path + opacity="0.35" + fill="#BE202E" + d="M980.3,1186.7C980.2,1186.7,980.2,1186.7,980.3,1186.7c-0.1,0.1-0.2,0.1-0.2,0.1 c1.8-0.2,3.5-0.5,5.2-0.8c7-1,13.9-2.2,20.7-3.7C997.5,1183.8,989,1185.2,980.3,1186.7L980.3,1186.7L980.3,1186.7z" + id="path4959" /> +<linearGradient + id="SVGID_2_" + gradientUnits="userSpaceOnUse" + x1="-7537.7339" + y1="-2391.4075" + x2="-4625.4141" + y2="-2391.4075" + gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)"> + <stop + offset="0.3233" + style="stop-color:#9E2064" + id="stop4961" /> + <stop + offset="0.6302" + style="stop-color:#C92037" + id="stop4963" /> + <stop + offset="0.7514" + style="stop-color:#CD2335" + id="stop4965" /> + <stop + offset="1" + style="stop-color:#E97826" + id="stop4967" /> +</linearGradient> +<path + fill="url(#SVGID_2_)" + d="M858.6,784.7c25.1-46.9,50.5-92.8,76.2-137.4c26.7-46.4,53.7-91.3,80.9-134.7 c1.6-2.6,3.2-5.2,4.8-7.7c27-42.7,54.2-83.7,81.6-122.9L1019.5,226c-6.2,7.6-12.5,15.3-18.8,23.2c-23.8,29.7-48.6,61.6-73.9,95.5 c-28.6,38.2-58,78.9-87.8,121.7c-27.6,39.5-55.5,80.9-83.5,123.7c-23.8,36.5-47.7,74-71.4,112.5c-0.9,1.4-1.8,2.9-2.6,4.3 l107.5,212.3C811.8,873.6,835.1,828.7,858.6,784.7z" + id="path4970" /> +<linearGradient + id="SVGID_3_" + gradientUnits="userSpaceOnUse" + x1="-7186.1777" + y1="-2099.3059" + x2="-5450.7183" + y2="-2099.3059" + gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)"> + <stop + offset="0" + style="stop-color:#282662" + id="stop4972" /> + <stop + offset="9.548390e-02" + style="stop-color:#662E8D" + id="stop4974" /> + <stop + offset="0.7882" + style="stop-color:#9F2064" + id="stop4976" /> + <stop + offset="0.9487" + style="stop-color:#CD2032" + id="stop4978" /> +</linearGradient> +<path + fill="url(#SVGID_3_)" + d="M369,1981c-14.2,39.1-28.5,78.9-42.9,119.6c-0.2,0.6-0.4,1.2-0.6,1.8c-2,5.7-4.1,11.5-6.1,17.2 c-9.7,27.4-18,52.1-37.3,108.2c31.7,14.5,57.1,52.5,81.1,95.6c-2.6-44.7-21-86.6-56.2-119.1c156.1,7,290.6-32.4,360.1-146.6 c6.2-10.2,11.9-20.9,17-32.2c-31.6,40.1-70.8,57.1-144.5,53c-0.2,0.1-0.3,0.1-0.5,0.2c0.2-0.1,0.3-0.1,0.5-0.2 c108.6-48.6,163.1-95.3,211.2-172.6c11.4-18.3,22.5-38.4,33.8-60.6c-94.9,97.5-205,125.3-320.9,104.2l-86.9,9.5 C374.4,1966.3,371.7,1973.6,369,1981z" + id="path4981" /> +<linearGradient + id="SVGID_4_" + gradientUnits="userSpaceOnUse" + x1="-7374.1626" + y1="-2418.5454" + x2="-4461.8428" + y2="-2418.5454" + gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)"> + <stop + offset="0.3233" + style="stop-color:#9E2064" + id="stop4983" /> + <stop + offset="0.6302" + style="stop-color:#C92037" + id="stop4985" /> + <stop + offset="0.7514" + style="stop-color:#CD2335" + id="stop4987" /> + <stop + offset="1" + style="stop-color:#E97826" + id="stop4989" /> +</linearGradient> +<path + fill="url(#SVGID_4_)" + d="M409.6,1786.3c18.8-48.5,38.1-97.7,58-147.2c19-47.4,38.5-95.2,58.5-143.2 c20-48,40.4-96.1,61.2-144.2c21.2-49,42.9-97.8,64.9-146.5c21.8-48.1,44-95.9,66.6-143.3c8.1-17.1,16.3-34.1,24.6-51 c14.2-29.3,28.6-58.4,43.1-87.2c0.8-1.6,1.6-3.1,2.4-4.6L681.4,706.8c-1.8,2.9-3.5,5.8-5.3,8.6c-25.1,40.9-50,82.7-74.4,125.4 c-24.7,43.1-49,87.1-72.7,131.7c-20,37.6-39.6,75.6-58.6,113.9c-3.8,7.8-7.6,15.5-11.3,23.2c-23.4,48.2-44.6,94.8-63.7,139.5 c-21.7,50.7-40.7,99.2-57.5,145.1c-11,30.2-21,59.4-30.1,87.4c-7.5,24-14.7,47.9-21.5,71.8c-16,56.3-29.9,112.4-41.2,168.3 L353,1935.1c14.3-38.1,28.9-76.8,44-116C401.1,1808.2,405.4,1797.3,409.6,1786.3z" + id="path4992" /> +<linearGradient + id="SVGID_5_" + gradientUnits="userSpaceOnUse" + x1="-7161.7642" + y1="-2379.1431" + x2="-5631.2524" + y2="-2379.1431" + gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)"> + <stop + offset="0" + style="stop-color:#282662" + id="stop4994" /> + <stop + offset="9.548390e-02" + style="stop-color:#662E8D" + id="stop4996" /> + <stop + offset="0.7882" + style="stop-color:#9F2064" + id="stop4998" /> + <stop + offset="0.9487" + style="stop-color:#CD2032" + id="stop5000" /> +</linearGradient> +<path + fill="url(#SVGID_5_)" + d="M243.5,1729.4c-13.6,68.2-23.2,136.2-28,203.8c-0.2,2.4-0.4,4.7-0.5,7.1 c-33.7-54-124-106.8-123.8-106.2c64.6,93.7,113.7,186.7,120.9,278c-34.6,7.1-82-3.2-136.8-23.3c57.1,52.5,100,67,116.7,70.9 c-52.5,3.3-107.1,39.3-162.1,80.8c80.5-32.8,145.5-45.8,192.1-35.3C148.1,2414.2,74.1,2645,0,2890c22.7-6.7,36.2-21.9,43.9-42.6 c13.2-44.4,100.8-335.6,238-718.2c3.9-10.9,7.8-21.8,11.8-32.9c1.1-3,2.2-6.1,3.3-9.2c14.5-40.1,29.5-81.1,45.1-122.9 c3.5-9.5,7.1-19,10.7-28.6c0.1-0.2,0.1-0.4,0.2-0.6l-107.9-213.2C244.6,1724.4,244,1726.9,243.5,1729.4z" + id="path5003" /> +<linearGradient + id="SVGID_6_" + gradientUnits="userSpaceOnUse" + x1="-7374.1626" + y1="-2117.1309" + x2="-4461.8428" + y2="-2117.1309" + gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)"> + <stop + offset="0.3233" + style="stop-color:#9E2064" + id="stop5005" /> + <stop + offset="0.6302" + style="stop-color:#C92037" + id="stop5007" /> + <stop + offset="0.7514" + style="stop-color:#CD2335" + id="stop5009" /> + <stop + offset="1" + style="stop-color:#E97826" + id="stop5011" /> +</linearGradient> +<path + fill="url(#SVGID_6_)" + d="M805.6,937c-3.1,6.3-6.2,12.7-9.3,19.1c-9.3,19.2-18.8,38.8-28.3,58.8 c-10.3,21.7-20.7,43.9-31.3,66.5c-5.3,11.4-10.6,22.9-16,34.6c-16.1,35-32.4,71.1-48.9,108.3c-20.3,45.8-41,93.4-62,142.8 c-20,47.1-40.3,95.9-60.9,146.3c-19.5,47.9-39.3,97.3-59.3,148.3c-17.8,45.4-35.9,92.1-54,140.1c-0.9,2.3-1.8,4.7-2.6,7 c-18,47.6-36.2,96.6-54.6,146.8c-0.4,1.1-0.8,2.3-1.3,3.4l86.9-9.5c-1.7-0.3-3.5-0.5-5.2-0.9c103.9-13,242.1-90.6,331.4-186.5 c41.1-44.2,78.5-96.3,113-157.3c25.7-45.4,49.8-95.8,72.8-151.5c20.1-48.7,39.4-101.4,58-158.6c-23.9,12.6-51.2,21.8-81.4,28.2 c-5.3,1.1-10.7,2.2-16.1,3.1c-5.5,1-11,1.8-16.6,2.6l0,0l0,0c0.1,0,0.1-0.1,0.2-0.1c96.9-37.3,158-109.2,202.4-197.4 c-25.5,17.4-66.9,40.1-116.6,51.1c-6.7,1.5-13.7,2.7-20.7,3.7c-1.7,0.3-3.5,0.6-5.2,0.8l0,0l0,0c0.1,0,0.1,0,0.1-0.1 c0,0,0.1,0,0.1,0l0,0c33.6-14.1,62-29.8,86.6-48.4c5.3-4,10.4-8.1,15.3-12.3c7.5-6.5,14.7-13.3,21.5-20.5c4.4-4.6,8.6-9.3,12.7-14.2 c9.6-11.5,18.7-23.9,27.1-37.3c2.6-4.1,5.1-8.3,7.6-12.6c3.2-6.2,6.3-12.3,9.3-18.3c13.5-27.2,24.4-51.5,33-72.8 c4.3-10.6,8.1-20.5,11.3-29.7c1.3-3.7,2.5-7.2,3.7-10.6c3.4-10.2,6.2-19.3,8.4-27.3c3.3-12,5.3-21.5,6.4-28.4l0,0l0,0 c-3.3,2.6-7.1,5.2-11.3,7.7c-29.3,17.5-79.5,33.4-119.9,40.8l79.8-8.8l-79.8,8.8c-0.6,0.1-1.2,0.2-1.8,0.3c-4,0.7-8.1,1.3-12.2,2 c0.7-0.3,1.4-0.7,2.1-1l-273,29.9C806.6,935,806.1,936,805.6,937z" + id="path5014" /> +<linearGradient + id="SVGID_7_" + gradientUnits="userSpaceOnUse" + x1="-7554.8232" + y1="-2132.0981" + x2="-4642.5034" + y2="-2132.0981" + gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)"> + <stop + offset="0.3233" + style="stop-color:#9E2064" + id="stop5016" /> + <stop + offset="0.6302" + style="stop-color:#C92037" + id="stop5018" /> + <stop + offset="0.7514" + style="stop-color:#CD2335" + id="stop5020" /> + <stop + offset="1" + style="stop-color:#E97826" + id="stop5022" /> +</linearGradient> +<path + fill="url(#SVGID_7_)" + d="M1112.9,385.1c-24.3,37.3-50.8,79.6-79.4,127.5c-1.5,2.5-3,5.1-4.5,7.6 c-24.6,41.5-50.8,87.1-78.3,137c-23.8,43.1-48.5,89.3-74.3,139c-22.4,43.3-45.6,89.2-69.4,137.8l273-29.9 c79.5-36.6,115.1-69.7,149.6-117.6c9.2-13.2,18.4-27,27.5-41.3c28-43.8,55.6-92,80.1-139.9c23.7-46.3,44.7-92.2,60.7-133.5 c10.2-26.3,18.4-50.8,24.1-72.3c5-19,8.9-36.9,11.9-54.1C1327.9,363.5,1197.6,380.9,1112.9,385.1z" + id="path5025" /> +<path + fill="#BE202E" + d="M936.5,1326.1c-5.5,1-11,1.8-16.6,2.6l0,0C925.5,1328,931,1327.1,936.5,1326.1z" + id="path5027" /> +<path + opacity="0.35" + fill="#BE202E" + d="M936.5,1326.1c-5.5,1-11,1.8-16.6,2.6l0,0C925.5,1328,931,1327.1,936.5,1326.1z" + id="path5029" /> +<linearGradient + id="SVGID_8_" + gradientUnits="userSpaceOnUse" + x1="-7374.1626" + y1="-2027.484" + x2="-4461.8433" + y2="-2027.484" + gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)"> + <stop + offset="0.3233" + style="stop-color:#9E2064" + id="stop5031" /> + <stop + offset="0.6302" + style="stop-color:#C92037" + id="stop5033" /> + <stop + offset="0.7514" + style="stop-color:#CD2335" + id="stop5035" /> + <stop + offset="1" + style="stop-color:#E97826" + id="stop5037" /> +</linearGradient> +<path + fill="url(#SVGID_8_)" + d="M936.5,1326.1c-5.5,1-11,1.8-16.6,2.6l0,0C925.5,1328,931,1327.1,936.5,1326.1z" + id="path5040" /> +<path + fill="#BE202E" + d="M980,1186.8c1.8-0.2,3.5-0.5,5.2-0.8C983.5,1186.3,981.8,1186.6,980,1186.8L980,1186.8z" + id="path5042" /> +<path + opacity="0.35" + fill="#BE202E" + d="M980,1186.8c1.8-0.2,3.5-0.5,5.2-0.8C983.5,1186.3,981.8,1186.6,980,1186.8L980,1186.8z" + id="path5044" /> +<linearGradient + id="SVGID_9_" + gradientUnits="userSpaceOnUse" + x1="-7374.1626" + y1="-2037.7417" + x2="-4461.8433" + y2="-2037.7417" + gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)"> + <stop + offset="0.3233" + style="stop-color:#9E2064" + id="stop5046" /> + <stop + offset="0.6302" + style="stop-color:#C92037" + id="stop5048" /> + <stop + offset="0.7514" + style="stop-color:#CD2335" + id="stop5050" /> + <stop + offset="1" + style="stop-color:#E97826" + id="stop5052" /> +</linearGradient> +<path + fill="url(#SVGID_9_)" + d="M980,1186.8c1.8-0.2,3.5-0.5,5.2-0.8C983.5,1186.3,981.8,1186.6,980,1186.8L980,1186.8z" + id="path5055" /> +<path + fill="#BE202E" + d="M980.2,1186.7C980.2,1186.7,980.2,1186.7,980.2,1186.7L980.2,1186.7L980.2,1186.7L980.2,1186.7 C980.2,1186.7,980.2,1186.7,980.2,1186.7z" + id="path5057" /> +<path + opacity="0.35" + fill="#BE202E" + d="M980.2,1186.7C980.2,1186.7,980.2,1186.7,980.2,1186.7L980.2,1186.7L980.2,1186.7 L980.2,1186.7C980.2,1186.7,980.2,1186.7,980.2,1186.7z" + id="path5059" /> +<linearGradient + id="SVGID_10_" + gradientUnits="userSpaceOnUse" + x1="-5738.0635" + y1="-2039.799" + x2="-5094.3457" + y2="-2039.799" + gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)"> + <stop + offset="0.3233" + style="stop-color:#9E2064" + id="stop5061" /> + <stop + offset="0.6302" + style="stop-color:#C92037" + id="stop5063" /> + <stop + offset="0.7514" + style="stop-color:#CD2335" + id="stop5065" /> + <stop + offset="1" + style="stop-color:#E97826" + id="stop5067" /> +</linearGradient> +<path + fill="url(#SVGID_10_)" + d="M980.2,1186.7C980.2,1186.7,980.2,1186.7,980.2,1186.7L980.2,1186.7L980.2,1186.7L980.2,1186.7 C980.2,1186.7,980.2,1186.7,980.2,1186.7z" + id="path5070" /> +</svg>
\ No newline at end of file diff --git a/src/documentation/content/xdocs/images/icon.png b/src/documentation/content/xdocs/images/icon.png Binary files differnew file mode 100644 index 0000000000..3be8bbbe65 --- /dev/null +++ b/src/documentation/content/xdocs/images/icon.png diff --git a/src/documentation/content/xdocs/images/poweredby-poi-logo.png b/src/documentation/content/xdocs/images/poweredby-poi-logo.png Binary files differnew file mode 100644 index 0000000000..a4a189d917 --- /dev/null +++ b/src/documentation/content/xdocs/images/poweredby-poi-logo.png diff --git a/src/documentation/content/xdocs/images/poweredby-poi.svg b/src/documentation/content/xdocs/images/poweredby-poi.svg new file mode 100644 index 0000000000..c5aa728f35 --- /dev/null +++ b/src/documentation/content/xdocs/images/poweredby-poi.svg @@ -0,0 +1,1025 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + xml:space="preserve" + width="202.278mm" + height="202.278mm" + version="1.1" + style="shape-rendering:geometricPrecision; text-rendering:geometricPrecision; image-rendering:optimizeQuality; fill-rule:evenodd; clip-rule:evenodd" + viewBox="0 0 20435 20435" + id="svg3850" + sodipodi:docname="poweredby-poi.svg" + inkscape:version="0.92.3 (2405546, 2018-03-11)"><metadata + id="metadata3854"><rdf:RDF><cc:Work + rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /></cc:Work></rdf:RDF></metadata><sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="3770" + inkscape:window-height="2096" + id="namedview3852" + showgrid="false" + inkscape:zoom="1.2347693" + inkscape:cx="773.41149" + inkscape:cy="555.47326" + inkscape:window-x="70" + inkscape:window-y="27" + inkscape:window-maximized="1" + inkscape:current-layer="svg3850" /> + <defs + id="defs3795"> + <style + type="text/css" + id="style3790"> + <![CDATA[ + .fil0 {fill:none} + .fil3 {fill:#2B2A29} + .fil1 {fill:#555759} + .fil2 {fill:white} + .fil4 {fill:white;fill-rule:nonzero} + .fnt0 {font-weight:normal;font-size:855.355px;font-family:'Arial Black'} + .fnt1 {font-weight:normal;font-size:2316.58px;font-family:'Arial'} + ]]> + </style> + <clipPath + id="id0"> + <rect + x="5749" + y="3200" + width="9073" + height="13105" + id="rect3792" /> + </clipPath> + + + + + + + + + + + + + + + + + + + + + + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2260" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.044266516" + id="feGaussianBlur2262" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2278" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2292" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.0242213" + id="feGaussianBlur2294" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2324" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.016787887" + id="feGaussianBlur2326" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2308" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.012210993" + id="feGaussianBlur2310" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2340" + x="-0.18000001" + width="1.36" + y="-0.18000001" + height="1.36"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.05036366" + id="feGaussianBlur2342" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248" + x="-0.18000001" + width="1.36" + y="-0.18000001" + height="1.36"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.032203086" + id="feGaussianBlur2250" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter1940" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406177" + id="feGaussianBlur1942" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2260-7" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.044266516" + id="feGaussianBlur2262-6" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2278-0" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2278-0-9" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2278-0-9-4" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5-5" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2278-0-9-4-9" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5-5-6" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2278-0-9-4-9-9" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5-5-2" + x="-0.18000001" + width="1.36" + y="-0.18000001" + height="1.36"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.10523737" + id="feGaussianBlur2278-0-9-4-9-4" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5-5-7" + x="-0.18000001" + width="1.36" + y="-0.18000001" + height="1.36"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.10523737" + id="feGaussianBlur2278-0-9-4-9-5" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5-5-8" + x="-0.18000001" + width="1.36" + y="-0.18000001" + height="1.36"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.10523737" + id="feGaussianBlur2278-0-9-4-9-1" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5-5-6-8" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2278-0-9-4-9-9-6" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5-5-9" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.21047475" + id="feGaussianBlur2278-0-9-4-9-3" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2531" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2533" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2531-0" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2533-5" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2531-0-1" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2533-5-0" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2531-0-5" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2533-5-06" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2531-0-5-6" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2533-5-06-2" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2531-0-8" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2533-5-4" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2" + x="-0.18000001" + width="1.36" + y="-0.18000001" + height="1.36"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.032203086" + id="feGaussianBlur2250-4" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-1" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-0" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-4" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-03" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-19" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-6" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-3" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-8" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-5" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-66" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-0" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-04" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-2" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-67" /></filter><filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-6" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"><feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-9" /></filter> + + </defs> + <circle + style="fill:none" + r="6890" + cy="10218" + cx="10218" + class="fil0" + id="Ellipse_as" /><circle + style="fill:none" + r="6890" + cy="10218" + cx="10218" + class="fil0" + id="Ellipse_pb" /><circle + style="fill:#555759" + r="10218" + cy="10218" + cx="10218" + class="fil1" + id="Ellipse_1" /><circle + style="fill:#ffffff" + r="6890" + cy="10218" + cx="10218" + class="fil2" + id="Ellipse_2" /><circle + style="fill:#ffffff" + cy="6423.9541" + cx="17773.666" + r="614" + transform="rotate(-0.65999872)" + class="fil2" + id="Ellipse_3" /><circle + style="fill:#ffffff" + cy="15882.426" + cx="3662.6582" + r="614" + transform="rotate(-0.65999872)" + class="fil2" + id="Ellipse_4" /><path + style="fill:#5993dc;fill-opacity:1;stroke-width:77.54569244" + d="m 7349.9714,15624.847 v -310.178 h 736.697 c 603.143,0 736.696,-21.086 736.696,-116.316 0,-95.23 -133.553,-116.317 -736.696,-116.317 -736.574,0 -736.697,-0.03 -736.697,-196.322 v -196.322 l 911.178,21.847 911.177,21.847 v 465.267 465.266 l -717.31,22.296 c -567.567,17.642 -717.31,45.97 -717.31,135.703 0,69.27 -75.45,113.406 -193.867,113.406 -174.481,0 -193.868,-31.018 -193.868,-310.177 z m 2204.644,207.632 c -22.721,-59.208 -30.79,-330.793 -17.932,-603.522 l 23.378,-495.871 h 891.7906 891.79 v 581.583 581.583 l -873.858,21.94 c -689.0856,17.3 -882.5916,-0.822 -915.1686,-85.713 z m 1440.0656,-517.81 v -232.633 h -542.829 -542.8296 v 232.633 232.633 h 542.8296 542.829 z m 697.923,0 c 0,-610.016 3.231,-620.355 193.867,-620.355 190.637,0 193.868,10.339 193.868,620.355 0,610.016 -3.232,620.355 -193.868,620.355 -190.636,0 -193.867,-10.339 -193.867,-620.355 z" + id="path4921" + inkscape:connector-curvature="0" + sodipodi:nodetypes="scsssscccccsssscsccccccccccccccccsssss" /><text + style="font-weight:normal;font-size:855.35498047px;font-family:'Arial Black';fill:#2b2a29" + class="fil3 fnt0" + id="TM" + y="15144" + x="12183">TM</text> +<text + style="font-weight:normal;font-size:2316.58007812px;font-family:Arial;fill:#ffffff" + class="fil2 fnt1" + id="powered_by" + y="9734" + x="2530"><tspan + id="tspan3809" + rotate="280">P</tspan></text> +<text + style="font-weight:normal;font-size:2316.58007812px;font-family:Arial;fill:#ffffff" + class="fil2 fnt1" + id="text3814" + y="8207" + x="2796"><tspan + id="tspan3812" + rotate="291">O</tspan></text> +<text + style="font-weight:normal;font-size:2316.58007812px;font-family:Arial;fill:#ffffff" + class="fil2 fnt1" + id="text3818" + y="6492" + x="3418"><tspan + id="tspan3816" + rotate="308">W</tspan></text> +<text + style="font-weight:normal;font-size:2316.58007812px;font-family:Arial;fill:#ffffff" + class="fil2 fnt1" + id="text3822" + y="4769" + x="4777"><tspan + id="tspan3820" + rotate="322">E</tspan></text> +<text + style="font-weight:normal;font-size:2316.58007812px;font-family:Arial;fill:#ffffff" + class="fil2 fnt1" + id="text3826" + y="3789" + x="5981"><tspan + id="tspan3824" + rotate="333">R</tspan></text> +<text + style="font-weight:normal;font-size:2316.58007812px;font-family:Arial;fill:#ffffff" + class="fil2 fnt1" + id="text3830" + y="3042" + x="7482"><tspan + id="tspan3828" + rotate="344">E</tspan></text> +<text + style="font-weight:normal;font-size:2316.58007812px;font-family:Arial;fill:#ffffff" + class="fil2 fnt1" + id="text3834" + y="2644" + x="8978"><tspan + id="tspan3832" + rotate="356">D</tspan></text> +<text + style="font-weight:normal;font-size:2316.58007812px;font-family:Arial;fill:#ffffff" + class="fil2 fnt1" + id="text3838" + y="2582" + x="10648"><tspan + id="tspan3836" + rotate="4"> </tspan></text> +<text + style="font-weight:normal;font-size:2316.58007812px;font-family:Arial;fill:#ffffff" + class="fil2 fnt1" + id="text3842" + y="2617" + x="11294"><tspan + id="tspan3840" + rotate="13">B</tspan></text> +<text + style="font-weight:normal;font-size:2316.58007812px;font-family:Arial;fill:#ffffff" + class="fil2 fnt1" + id="text3846" + y="2990" + x="12795"><tspan + id="tspan3844" + rotate="24">Y</tspan></text> +<path + style="fill:#ffffff;fill-rule:nonzero" + inkscape:connector-curvature="0" + d="m 7981,19698 1132,-2184 332,37 672,2387 -344,-39 -186,-721 -961,-108 -325,664 z m 762,-863 778,87 -167,-659 c -50,-200 -86,-365 -110,-495 -48,145 -106,287 -175,425 z m 1942,1062 -257,-2282 862,-97 c 151,-17 268,-23 350,-17 114,6 212,31 294,75 82,44 151,110 208,199 57,89 91,190 104,303 22,193 -21,364 -130,512 -108,148 -324,240 -647,277 l -585,66 105,931 -303,34 z m 168,-1233 590,-66 c 195,-22 330,-74 404,-156 74,-82 103,-189 88,-321 -11,-95 -44,-174 -100,-237 -56,-63 -125,-101 -206,-113 -53,-8 -147,-4 -284,11 l -584,66 z m 1806,1007 -58,-2459 309,-127 1738,1769 -320,131 -510,-543 -895,368 34,738 z m 253,-1123 724,-297 -464,-498 c -140,-152 -252,-279 -335,-381 28,150 45,302 51,457 l 23,719 z m 3095,-1573 293,-115 c 94,240 111,461 53,664 -58,203 -184,374 -378,513 -201,144 -393,220 -578,228 -185,9 -365,-42 -542,-150 -177,-109 -329,-251 -457,-430 -139,-194 -224,-390 -253,-588 -29,-198 -2,-384 81,-557 83,-173 207,-319 371,-436 187,-134 378,-199 573,-195 196,4 380,74 553,210 l -201,231 c -140,-105 -274,-159 -400,-162 -127,-3 -252,40 -377,129 -143,102 -238,223 -285,360 -47,137 -48,279 -4,422 44,144 110,278 198,401 114,159 236,281 367,366 131,86 266,123 405,112 139,-11 265,-57 379,-138 138,-99 226,-222 265,-370 38,-148 18,-313 -60,-495 z m 1224,-34 -1802,-1424 189,-239 742,587 736,-931 -742,-587 189,-239 1802,1424 -189,239 -848,-670 -736,931 848,670 z m 1527,-2139 -2092,-947 684,-1511 245,111 -558,1233 643,291 523,-1154 245,111 -523,1154 713,323 581,-1283 245,111 -706,1560 z" + class="fil4" + id="Apache" /> +<g + id="g4891" + transform="matrix(2.9616396,0,0,2.9616396,21935.299,-9027.9702)"><path + inkscape:label="hourglass" + sodipodi:nodetypes="cccccccccsccccccccssccccsccccccsccccc" + inkscape:connector-curvature="0" + id="path1466" + d="m -5304.232,8108.9773 c -61.0646,-61.0651 283.6317,-740.0284 531.6467,-1047.2111 100.6669,-124.6833 267.8115,-297.649 371.4343,-384.3663 103.6189,-86.7193 188.6251,-176.3471 188.9006,-199.1776 0.2828,-22.8234 -46.23,-67.7732 -103.3467,-99.8757 -196.3214,-110.3367 -484.878,-409.8638 -638.3783,-662.6479 -102.5987,-168.9632 -158.7545,-273.877 -210.0569,-292.5958 -44.9017,23.9681 -81.2893,-20.1745 -80.9418,-48.4644 -47.099,-116.5639 169.4896,-236.9707 260.7107,-208.0182 86.9906,14.9971 112.4317,174.5893 136.3212,237.6012 55.2593,145.7538 47.8835,131.465 106.4089,248.3976 128.6505,257.0312 336.0988,477.6259 551.3588,586.2867 164.665,83.1238 223.4752,164.3817 188.1246,259.9396 -11.9287,32.251 -198.7602,235.0382 -415.1785,450.6363 -401.2679,399.7492 -586.7125,641.3329 -710.8516,926.0355 -37.2135,85.3453 -76.7407,172.3547 -87.8365,193.3556 -23.1058,43.7333 -65.457,62.9634 -88.3155,40.1045 z m 2674.8495,-55.4795 c -21.1649,-21.1645 2.8186,-62.5704 36.187,-62.5704 13.7129,0 24.9529,17.9097 24.9529,39.7623 0,40.9924 -31.2774,52.6619 -61.1306,22.7929 z m -162.4108,-359.4424 c -66.0521,-138.5278 -182.9367,-328.4463 -259.7433,-422.0384 -144.3675,-175.9076 -604.8611,-578.4734 -631.8313,-606.4935 -56.5116,-58.7134 -158.4226,-85.5697 -140.6169,-230.2557 8.1718,-31.2155 116.4401,-126.1754 246.3525,-216.0496 335.3256,-231.9883 495.482,-449.6584 598.8948,-813.9572 53.4501,-188.2901 115.3161,-263.8169 195.3067,-238.4285 70.9612,22.5112 70.3256,52.2518 -5.6039,261.4065 -130.5381,359.6305 -335.9735,607.7816 -713.6344,862.0275 -112.9903,76.0653 -207.6106,133.042 -205.4356,179.9062 3.6874,79.4506 71.9134,119.3683 278.3344,302.8578 181.4652,161.3096 406.8723,419.1216 543.629,621.7836 162.2852,240.4976 276.1365,489.4105 240.2626,525.2861 -16.7815,16.7823 -67.9617,-62.5291 -145.9235,-226.0448 z" + style="fill:#ff0000;stroke-width:26.50802994" /><g + inkscape:label="color_dots" + id="g2864" + transform="matrix(101.02434,0,0,101.02434,-5326.9405,-21864.362)"><circle + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.13229166;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2260)" + id="path1483" + cx="13.948128" + cy="273.89798" + r="0.88533032" + inkscape:label="green1" /><circle + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276)" + id="path1483-3" + cx="15.638769" + cy="275.59299" + r="0.70158249" + inkscape:label="green2" /><circle + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.072386;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2292)" + id="path1483-3-0" + cx="14.06506" + cy="275.61847" + r="0.48442599" + inkscape:label="green3" + inkscape:transform-center-x="-1.1418613" + inkscape:transform-center-y="-0.24220642" /><circle + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.05017104;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2324)" + id="path1483-3-0-4" + cx="15.014526" + cy="277.57547" + r="0.33575773" + inkscape:label="green4" + inkscape:transform-center-x="-0.79142984" + inkscape:transform-center-y="-0.16789611" /><circle + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.03649288;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2308)" + id="path1483-3-0-4-8" + cx="14.125602" + cy="276.88751" + r="0.24421985" + inkscape:label="green5" + inkscape:transform-center-x="-0.57566127" + inkscape:transform-center-y="-0.1221404" /><circle + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.05017104;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2340)" + id="path1483-3-0-4-88" + cx="13.949684" + cy="279.63672" + r="0.33575773" + inkscape:label="green6" + inkscape:transform-center-x="-0.79142984" + inkscape:transform-center-y="-0.16789611" /><circle + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248)" + id="path1483-3-0-4-88-9" + cx="14.34833" + cy="281.6181" + r="0.21468724" + inkscape:label="green7" + inkscape:transform-center-x="-0.50604888" + inkscape:transform-center-y="-0.10736249" /><circle + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter1940)" + id="path1483-3-0-4-88-9-7" + cx="12.798038" + cy="283.44598" + r="0.21468726" + inkscape:label="green8" + inkscape:transform-center-x="-0.50604888" + inkscape:transform-center-y="-0.10736249" /><circle + style="opacity:1;fill:#ff0000;fill-opacity:0.94117647;stroke:none;stroke-width:0.13229166;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2260-7)" + id="path1483-4" + cx="11.592816" + cy="275.20081" + r="0.88533032" + inkscape:label="red1" + inkscape:transform-center-x="-2.9065562" + inkscape:transform-center-y="-1.2110651" /><circle + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3)" + id="path1483-3-3" + cx="9.529829" + cy="274.95859" + r="0.70158249" + inkscape:label="red2" /><circle + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0)" + id="path1483-3-3-2" + cx="12.03548" + cy="277.33896" + r="0.70158249" + inkscape:label="red3" + inkscape:transform-center-x="1.7956426" + inkscape:transform-center-y="-1.9588817" + transform="matrix(0.88839286,0,0,0.88839286,1.4058873,30.932131)" /><circle + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5)" + id="path1483-3-3-2-0" + cx="12.03548" + cy="277.33896" + r="0.70158249" + inkscape:label="red3" + inkscape:transform-center-x="0.95776193" + inkscape:transform-center-y="-1.0448304" + transform="matrix(0.47385204,0,0,0.47385204,4.3279237,144.86906)" /><circle + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5-5)" + id="path1483-3-3-2-0-4" + cx="12.03548" + cy="277.33896" + r="0.70158249" + inkscape:label="red4" + inkscape:transform-center-x="0.69995244" + inkscape:transform-center-y="-0.76358713" + transform="matrix(0.34630101,0,0,0.34630101,6.798504,180.89532)" /><circle + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5-5-6)" + id="path1483-3-3-2-0-4-2" + cx="12.03548" + cy="277.33896" + r="0.70158249" + inkscape:label="red5" + inkscape:transform-center-x="0.69995244" + inkscape:transform-center-y="-0.76358713" + transform="matrix(0.34630101,0,0,0.34630101,10.707321,182.43211)" /><circle + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5-5-2)" + id="path1483-3-3-2-0-4-7" + cx="12.03548" + cy="277.33896" + r="0.70158249" + inkscape:label="red6" + inkscape:transform-center-x="0.69995244" + inkscape:transform-center-y="-0.76358713" + transform="matrix(0.34630101,0,0,0.34630101,9.9305688,184.55356)" /><circle + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5-5-7)" + id="path1483-3-3-2-0-4-4" + cx="12.03548" + cy="277.33896" + r="0.70158249" + inkscape:label="red7" + inkscape:transform-center-x="0.69995244" + inkscape:transform-center-y="-0.76358713" + transform="matrix(0.34630101,0,0,0.34630101,8.8865472,186.35764)" /><circle + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5-5-8)" + id="path1483-3-3-2-0-4-28" + cx="12.03548" + cy="277.33896" + r="0.70158249" + inkscape:label="red8" + inkscape:transform-center-x="0.69995244" + inkscape:transform-center-y="-0.76358713" + transform="matrix(0.34630101,0,0,0.34630101,10.181134,186.3994)" /><circle + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5-5-6-8)" + id="path1483-3-3-2-0-4-2-2" + cx="12.03548" + cy="277.33896" + r="0.70158249" + inkscape:label="red10" + inkscape:transform-center-x="0.88984675" + inkscape:transform-center-y="-0.97074837" + transform="matrix(0.44025121,0,0,0.44025121,10.986824,155.23165)" /><circle + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5-5-9)" + id="path1483-3-3-2-0-4-6" + cx="12.03548" + cy="277.33896" + r="0.70158249" + inkscape:label="red9" + inkscape:transform-center-x="0.69995244" + inkscape:transform-center-y="-0.76358713" + transform="matrix(0.34630101,0,0,0.34630101,11.233508,187.66058)" /><circle + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2531)" + id="path1483-3-1" + cx="17.475492" + cy="274.56949" + r="0.70158249" + inkscape:label="blue1" + transform="matrix(1.1352883,0,0,1.1352883,-2.3642295,-37.146036)" /><circle + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2531-0)" + id="path1483-3-1-1" + cx="17.475492" + cy="274.56949" + r="0.70158249" + inkscape:label="blue2" + transform="matrix(0.67681132,0,0,0.67681132,5.9136463,90.544934)" + inkscape:transform-center-x="-0.059854253" + inkscape:transform-center-y="-0.72177105" /><circle + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2531-0-1)" + id="path1483-3-1-1-8" + cx="17.475492" + cy="274.56949" + r="0.70158249" + inkscape:label="blue3" + transform="matrix(0.48139489,0,0,0.48139489,10.50982,142.52895)" + inkscape:transform-center-x="-0.042571968" + inkscape:transform-center-y="-0.51337868" /><circle + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2531-0-5)" + id="path1483-3-1-1-4" + cx="17.475492" + cy="274.56949" + r="0.70158249" + inkscape:label="blue4" + transform="matrix(0.29349449,0,0,0.29349449,13.651731,195.042)" + inkscape:transform-center-x="-0.025955496" + inkscape:transform-center-y="-0.31298695" /><circle + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2531-0-5-6)" + id="path1483-3-1-1-4-5" + cx="17.475492" + cy="274.56949" + r="0.70158249" + inkscape:label="blue5" + transform="matrix(0.32355855,0,0,0.32355855,7.3976455,186.79913)" + inkscape:transform-center-x="-0.028614186" + inkscape:transform-center-y="-0.34504766" /><circle + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2531-0-8)" + id="path1483-3-1-1-7" + cx="17.475492" + cy="274.56949" + r="0.70158249" + inkscape:label="blue6" + transform="matrix(0.76609135,0,0,0.76609135,0.30399118,67.713821)" + inkscape:transform-center-x="-0.067749861" + inkscape:transform-center-y="-0.81698114" /><circle + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2)" + id="path1483-3-0-4-88-9-0" + cx="13.559896" + cy="281.60339" + r="0.21468724" + inkscape:label="blue7" + inkscape:transform-center-x="-0.50604888" + inkscape:transform-center-y="-0.10736249" /><circle + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6)" + id="path1483-3-0-4-88-9-0-9" + cx="13.819755" + cy="283.19205" + r="0.21468724" + inkscape:label="blue8" + inkscape:transform-center-x="-0.50604888" + inkscape:transform-center-y="-0.10736249" /><circle + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9)" + id="path1483-3-0-4-88-9-0-9-8" + cx="15.130859" + cy="282.93811" + r="0.21468724" + inkscape:label="blue9" + inkscape:transform-center-x="-0.50604888" + inkscape:transform-center-y="-0.10736249" /><circle + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1)" + id="path1483-3-0-4-88-9-0-9-8-1" + cx="12.012555" + cy="283.69995" + r="0.21468724" + inkscape:label="coffee1" + inkscape:transform-center-x="-0.50604888" + inkscape:transform-center-y="-0.10736249" /><circle + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-1)" + id="path1483-3-0-4-88-9-0-9-8-1-3" + cx="11.510556" + cy="284.78076" + r="0.21468724" + inkscape:label="coffee2" + inkscape:transform-center-x="-0.50604888" + inkscape:transform-center-y="-0.10736249" /><circle + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-4)" + id="path1483-3-0-4-88-9-0-9-8-1-9" + cx="12.561803" + cy="284.50906" + r="0.21468724" + inkscape:label="coffee3" + inkscape:transform-center-x="-0.50604888" + inkscape:transform-center-y="-0.10736249" /><circle + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-19)" + id="path1483-3-0-4-88-9-0-9-8-1-93" + cx="13.311849" + cy="284.76303" + r="0.21468724" + inkscape:label="coffee4" + inkscape:transform-center-x="-0.50604888" + inkscape:transform-center-y="-0.10736249" /><circle + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-3)" + id="path1483-3-0-4-88-9-0-9-8-1-0" + cx="13.613049" + cy="283.97754" + r="0.21468724" + inkscape:label="coffee5" + inkscape:transform-center-x="-0.50604888" + inkscape:transform-center-y="-0.10736249" /><circle + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-5)" + id="path1483-3-0-4-88-9-0-9-8-1-4" + cx="14.605236" + cy="283.96573" + r="0.21468724" + inkscape:label="coffee6" + inkscape:transform-center-x="-0.50604888" + inkscape:transform-center-y="-0.10736249" /><circle + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-0)" + id="path1483-3-0-4-88-9-0-9-8-1-6" + cx="14.871001" + cy="284.78073" + r="0.21468724" + inkscape:label="coffee7" + inkscape:transform-center-x="-0.50604888" + inkscape:transform-center-y="-0.10736249" /><circle + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-2)" + id="path1483-3-0-4-88-9-0-9-8-1-5" + cx="15.6742" + cy="284.77481" + r="0.21468724" + inkscape:label="coffee8" + inkscape:transform-center-x="-0.50604888" + inkscape:transform-center-y="-0.10736249" /><circle + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-6)" + id="path1483-3-0-4-88-9-0-9-8-1-8" + cx="16.418341" + cy="284.49725" + r="0.21468724" + inkscape:label="coffee9" + inkscape:transform-center-x="-0.50604888" + inkscape:transform-center-y="-0.10736249" /></g><g + style="display:inline" + inkscape:label="cup" + id="g3054" + transform="matrix(319.20648,0,0,319.20648,-45013.798,-50651.641)"><g + id="g2998" + transform="translate(0.01169304,-1.727816)"><ellipse + ry="0.64501309" + rx="2.2179031" + cy="184.27515" + cx="128.77695" + id="path2951-9" + style="opacity:1;fill:#000000;fill-opacity:1;stroke:#5993dc;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /><ellipse + ry="0.64501309" + rx="2.2179034" + cy="184.3564" + cx="128.77747" + id="path2951-9-0" + style="opacity:1;fill:#000000;fill-opacity:1;stroke:#5993dc;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /><ellipse + ry="0.61824954" + rx="2.1833072" + cy="184.27364" + cx="128.77689" + id="path2951" + style="opacity:1;fill:#ccaf5f;fill-opacity:1;stroke:#5993dc;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /></g><path + style="display:inline;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.03779528;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 486.9043,682.01953 c -2.50186,-0.048 -5.12716,0.67257 -5.125,1.49024 l 0.004,1.44335 h 0.002 c 0.37644,3.65723 2.27859,6.05321 4.87059,6.03812 2.592,-0.0151 3.60697,-1.28146 4.563,-3.19632 4.12974,-2.05232 2.78561,-3.41817 0.43164,-3.0957 l 0.0332,-1.28906 c 0.0227,-0.79491 -2.27789,-1.34255 -4.77929,-1.39063 z m 5.67382,3.14258 c 0.69846,0.0585 0.66798,0.67417 0.20899,1.13281 l -1.44727,1.08399 c 0.10281,-0.65923 0.26206,-0.69907 0.36524,-2.17774 z" + transform="scale(0.26458333)" + id="path3012" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccczcccccccccc" /><path + style="fill:#ccaf5f;fill-opacity:1;stroke:none;stroke-width:0.01;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 127.51611,181.29623 c 0.0272,0.28871 0.2976,1.45684 1.25955,1.48215 0.96194,0.0253 1.27955,-0.97941 1.26773,-1.47933 -0.83083,0.45557 -1.88688,0.29236 -2.52728,-0.003 z" + id="path3033" + inkscape:connector-curvature="0" + sodipodi:nodetypes="czcc" /><path + style="fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.01;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 127.51166,181.23764 c 0.18196,0.10413 0.86168,0.30435 1.25671,0.29869 0.39503,-0.006 0.64044,-3.2e-4 1.27229,-0.29087 l 0.006,-0.25539 c -0.0394,0.10285 -0.67435,0.32561 -1.27739,0.32734 -0.60304,0.002 -1.0452,-0.12585 -1.25972,-0.33363 z" + id="path3035" + inkscape:connector-curvature="0" + sodipodi:nodetypes="czcczcc" /><ellipse + style="display:inline;opacity:1;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.01257183;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + id="path3037" + cx="129.53156" + cy="180.86237" + rx="1.2750689" + ry="0.36997855" + transform="matrix(1,0,-0.00411815,0.99999152,0,0)" /><path + style="fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.01;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 127.71432,181.06203 c 0.21614,0.0876 0.47779,0.21433 1.05092,0.19878 0.57313,-0.0155 0.93983,-0.11187 1.11084,-0.20902 -0.23422,-0.15242 -0.45794,-0.24172 -1.05092,-0.24847 -0.59298,-0.007 -0.93477,0.10876 -1.11084,0.25871 z" + id="path3039" + inkscape:connector-curvature="0" + sodipodi:nodetypes="czczc" /></g><g + inkscape:label="documents" + id="g3733" + transform="matrix(311.05378,0,0,311.05378,-54899.286,-54969.589)"><path + style="display:inline;fill:#cdcdcd;stroke-width:0.31999999" + d="m 614.56836,722.91602 c 0.002,0.004 0.003,0.008 0.006,0.0137 v -0.008 c -2.3e-4,-2.7e-4 2.3e-4,-0.002 0,-0.002 -10e-4,-0.002 -0.005,-0.002 -0.006,-0.004 z m 5.42578,0.0117 c -0.002,1.2e-4 -0.004,0.002 -0.006,0.002 -0.1937,0.015 -0.41023,0.095 -0.76953,0.16601 -0.10717,0.0216 -0.21816,0.0376 -0.35742,0.0547 -0.0666,0.008 -0.12593,0.0171 -0.20117,0.0234 -0.22608,0.0193 -0.48216,0.0314 -0.80274,0.0254 -0.96726,-0.0188 -1.60126,-0.0356 -2.0918,-0.0586 -0.31591,-0.0155 -0.60455,-0.0331 -0.77539,-0.0605 -0.0128,-0.002 -0.0445,-0.004 -0.0566,-0.006 0.0281,0.18475 0.0803,0.4784 0.0586,0.93945 0.0126,10e-6 0.0188,0.002 0.0312,0.002 0.40748,7e-4 0.69076,0.0115 0.91406,0.0313 0.002,1.6e-4 0.006,-1.8e-4 0.008,0 0.8289,-0.006 1.30116,0.31165 3.53907,-0.10938 0.78424,-0.13351 1.11772,0.35153 1.40751,0.60657 1.07734,0.94809 2.09321,1.54497 2.99288,1.11413 0.8859,-0.21646 1.35349,-0.96306 2.28711,-1.36718 0.005,-0.36089 -0.0122,-0.68485 -0.0684,-0.9004 -0.0575,0.0439 -0.0813,0.0652 -0.1504,0.11524 -0.2538,0.18525 -0.58093,0.40701 -1.02539,0.66797 -0.7936,0.37882 -1.30115,0.7521 -1.86914,0.73047 -0.14265,-0.005 -0.28748,-0.0362 -0.44336,-0.0977 -0.30958,-0.12215 -0.65735,-0.3673 -1.08398,-0.7832 -0.21381,-0.20842 -0.44754,-0.45931 -0.70703,-0.75977 h -0.002 c -0.1815,-0.12569 -0.31465,-0.19926 -0.43555,-0.25195 -0.0298,-0.0131 -0.0603,-0.0238 -0.0879,-0.0332 -0.1097,-0.0378 -0.20697,-0.0574 -0.30274,-0.0508 -6e-4,5e-5 -10e-4,-4e-5 -0.002,0 z m -3.60547,1.22071 c 0.0152,0.008 0.0364,0.0159 0.0488,0.0254 -0.013,-0.009 -0.0333,-0.0174 -0.0488,-0.0254 z m 0.11719,0.0918 c 0.0279,0.0463 0.0488,0.0951 0.0488,0.16211 0,-0.0653 -0.0184,-0.11719 -0.0488,-0.16211 z m -0.4082,0.93555 c -0.35394,0.0763 -0.84461,-0.0283 -1.3086,0.0625 -1.24811,0 -2.34218,0.41393 -3.45117,1.29883 -0.5884,0.46949 -1.00688,0.59193 -1.92383,0.90234 -0.4734,0.16026 -0.8412,0.29665 -1.15429,0.40821 -0.20318,0.0716 -0.3993,0.13804 -0.54102,0.17382 -0.002,5.5e-4 -0.006,10e-4 -0.008,0.002 -0.0983,0.0248 -0.19086,0.0444 -0.26172,0.0469 l 0.33984,1.15625 c 0.0232,3.9e-4 0.0468,0.008 0.0742,0.0449 1.2116,-0.62653 1.31838,-0.71948 2.17774,-0.92773 0,0 0.66835,2.23444 0.71484,2.58594 0.0464,0.35134 0.92017,2.45074 1.25391,3.35351 0.33354,0.90278 1.20365,2.5793 1.32421,3.06055 0.19658,0.19695 0.18808,0.006 2.16602,-0.71094 0.86293,-0.43711 1.7418,-0.80741 1.95312,-0.94726 -0.037,-0.13335 -0.072,-0.32803 -0.10937,-0.48438 -0.0285,0.22021 -0.14999,0.26349 -0.39648,0.35742 l -3.41407,1.60547 -0.2832,-0.73633 c -0.15553,-0.40414 -0.54891,-1.28429 -1.02539,-2.26757 -0.53401,-1.10193 -1.02095,-2.43748 -1.19141,-3.37696 l -0.63476,-2.58398 c 1.19584,-0.94571 3.1848,-1.84002 4.5,-2.07813 l 1.19922,-0.21679 z m -1.14258,1.50195 c -0.67536,0.0796 -1.891,0.63431 -2.9043,1.37891 -0.90792,0.66728 -0.98351,0.84509 -0.74805,1.78906 0.43382,1.73832 0.91084,3.16881 1.65039,4.95313 h 0.002 c 0.38645,0.93241 0.7439,1.69531 0.79492,1.69531 0.0509,0 2.0813,-0.88412 2.89062,-1.27734 0.1304,-0.16929 0.12256,-0.25807 -0.0215,-0.95899 -0.091,-0.44281 -0.34121,-2.24389 -0.55664,-4.0039 -0.21532,-1.75998 -0.5042,-3.32873 -0.64062,-3.48633 -0.0776,-0.0894 -0.24168,-0.11649 -0.4668,-0.0898 z m 0.0234,0.39063 c 0.50294,-0.16078 0.90556,4.02711 1.26953,6.55078 0.006,0.23962 0.30726,1.1777 -0.0723,1.31641 l -2.21875,0.95117 -0.67383,-1.77149 c -0.40535,-0.92284 -0.9257,-2.48879 -1.15625,-3.48046 -0.40898,-1.75971 -0.4,-1.81602 0.33985,-2.30079 0.41695,-0.27318 2.04339,-1.0876 2.51172,-1.26562 z m 9.18164,0.51953 c -0.10742,0.13097 -0.19843,0.43318 -0.28321,0.83789 l 1.14649,0.18945 c 0.63537,0.10508 1.8186,0.19335 2.63086,0.19532 1.00739,0.002 1.74678,0.21378 2.32422,0.66797 l 1.08203,0.71484 c 0.1978,-0.33447 0.32853,-0.62243 0.33984,-1.06055 -0.005,-0.002 -0.0182,-0.01 -0.0234,-0.0117 -0.25455,-0.10181 -0.58631,-0.28506 -1.11914,-0.57421 -0.165,-0.0828 -0.38513,-0.16696 -0.64062,-0.25 -0.51099,-0.16609 -1.16506,-0.32421 -1.81446,-0.4375 -0.32469,-0.0566 -0.64776,-0.10284 -0.95117,-0.13282 -1.16295,-0.11481 -2.36301,-0.0875 -2.6914,-0.13867 z m 0.0723,1.48438 -0.61328,3.79296 c -0.4252,3.679 -0.8807,4.03516 -0.17578,3.72071 -2.3e-4,-1.0944 0.38782,-3.86556 0.53711,-4.22461 l 0.50391,-2.84375 1.00781,0.31836 c 0.55366,0.17575 1.43684,0.30613 1.96484,0.29101 2.25732,0.25334 1.90883,0.29584 1.08399,2.54493 h 0.002 c -0.41843,1.25833 -0.63416,2.89481 -1.1543,4.18359 -0.27364,0.8945 -0.24083,0.80859 -0.082,0.80859 0.45562,0 0.93095,-2.05232 1.25977,-3.51953 0.16478,-0.73531 0.53262,-1.89602 0.81836,-2.58008 0.52236,-1.25019 0.35743,-1.71536 -0.64649,-1.8125 -1.18628,-0.11444 -2.08425,-0.23813 -3.21289,-0.44336 z" + transform="scale(0.26458333)" + id="path3233" + inkscape:connector-curvature="0" + inkscape:label="light gray" + sodipodi:nodetypes="ccccccccccccccccccccsccccccccccccccccccccccccccccccccccccccccccccccccccccscccccccccccccccccccccccccccccccccccccccsccccc" /><path + inkscape:label="dark gray" + sodipodi:nodetypes="cccccccccccccccccccccccccccccccccccccccccccccccccccccccscccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccscccccccccscccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccacccccccccccccccccccccccccccccccaccccccccccccccccccccccccc" + inkscape:connector-curvature="0" + id="path3720" + transform="scale(0.26458333)" + d="m 626.15039,722.23828 c -0.14691,0.008 -0.33657,0.0733 -0.57617,0.20703 -0.0343,0.0259 -0.0336,0.0296 -0.0664,0.0547 0.38795,-0.18092 0.68437,-0.26853 0.80664,-0.23438 -0.0486,-0.0175 -0.10043,-0.0306 -0.16406,-0.0273 z m 0.22266,0.0586 c 0.12023,0.27135 0.19498,0.41351 0.22656,0.50585 -0.0197,-0.24909 -0.0913,-0.42249 -0.22656,-0.50585 z m -11.79883,0.62304 -0.006,0.15039 c 0.0586,0.39974 0.11165,0.72251 0.01,0.97266 0.12842,-0.0114 0.2595,-0.0288 0.38086,-0.0293 0.0136,0 0.0198,-1e-5 0.0332,0 0.0217,-0.46105 -0.0305,-0.7547 -0.0586,-0.93945 -0.19719,-0.0351 -0.30099,-0.0865 -0.35937,-0.1543 z m 12.01953,0.0605 c -0.0201,0.0274 -0.0441,0.0537 -0.0879,0.0918 -0.0787,0.0683 -0.23959,0.19403 -0.40234,0.31835 0.15981,0.61344 0.12008,1.9391 -0.4043,3.27344 0.16535,8.8e-4 0.26398,-0.009 0.42187,-0.01 0.0681,-1.24363 0.47946,-2.77778 0.47266,-3.67383 z m -10.09961,1.82226 c -0.0247,0.0975 -0.0488,0.17774 -0.0488,0.17774 0.24607,0.0359 0.53324,0.0793 0.68555,0.10156 -0.0135,0.19358 -0.0176,0.38986 -0.0293,0.58399 -0.19721,-0.0281 -0.39458,-0.0669 -0.59179,-0.0918 l -0.004,0.008 c -0.0218,-0.29767 -0.0399,-0.41047 -0.0606,-0.60156 -0.0752,0.099 -0.19947,0.15041 -0.34765,0.17578 v 1.59961 c 0.2313,3.30557 0.38456,3.93259 0.79687,5.97656 0.3035,2.36652 0.85626,4.33856 1.05469,3.75977 -0.0301,-0.23244 -0.17148,-0.92772 -0.25977,-1.4043 0.28908,0.0415 0.57832,0.0846 0.86914,0.14453 -0.0129,0.12232 -0.0208,0.24484 -0.0351,0.36719 v 0.004 l 0.19726,-0.0527 c 0.012,-0.089 0.0233,-0.18205 0.0352,-0.27148 0.31303,0.069 0.62621,0.1366 0.94141,0.22851 0.13038,0.0527 0.23996,0.0862 0.36132,0.13086 -0.0236,0.15167 -0.0424,0.30349 -0.0684,0.45508 l 0.002,0.006 0.19922,-0.043 c 0.0213,-0.11338 0.0413,-0.23158 0.0625,-0.3457 0.44049,0.15355 0.82488,0.25811 1.17968,0.33594 -0.0364,0.16869 -0.068,0.33741 -0.10742,0.50585 v 0.006 l 0.20117,-0.0312 c 0.0365,-0.14521 0.0713,-0.29666 0.10743,-0.44336 0.21287,0.0424 0.4227,0.0826 0.6289,0.11914 -0.0515,0.16763 -0.0959,0.34695 -0.15234,0.50586 0.30879,0.25097 0.18438,0.11058 0.37109,-0.1914 0.26079,-0.42202 0.76162,-3.30859 1.22461,-7.06446 0.13238,-1.0739 0.27097,-1.64313 0.45313,-1.86523 -0.0143,-0.002 -0.0752,-0.001 -0.0859,-0.004 -0.15022,-0.0358 -0.28444,-0.0541 -0.31641,-0.23828 -0.003,0.003 -10e-4,0.002 -0.004,0.006 -0.18592,-0.0366 -0.37038,-0.0778 -0.55469,-0.11914 0.0477,-0.18362 0.0904,-0.37084 0.14062,-0.55273 0.11144,0.0194 0.32348,0.0739 0.50391,0.11719 0.0203,-0.0696 0.0222,-0.1071 0.0508,-0.19141 v -0.002 c 0.0162,0.002 0.0962,0.002 0.11719,0.004 -0.29845,-0.0544 -0.65568,-0.11849 -0.82422,-0.1543 -0.59074,-0.13474 -1.17005,-0.30158 -1.74609,-0.48046 l -0.19532,-0.0625 c -0.37223,-0.1181 -0.74609,-0.232 -1.11523,-0.35938 -0.22725,-0.0761 -0.45439,-0.13883 -0.68164,-0.20117 l -0.19727,-0.0566 c -0.63665,-0.16467 -1.27349,-0.26855 -1.91015,-0.36328 l -0.20313,-0.0332 c -0.13758,-0.0194 -0.41922,-0.0616 -0.64453,-0.0937 z m -4.92969,0.16407 c -0.23426,0.0811 -0.46164,0.17563 -0.66992,0.31445 0.222,-0.11618 0.44609,-0.2107 0.66992,-0.31445 z m 5.76758,0.14648 c 0.62706,0.098 1.25768,0.22985 1.89063,0.39258 -0.0282,0.17857 -0.0496,0.35984 -0.0762,0.53906 -0.61509,-0.15695 -1.22864,-0.25569 -1.84375,-0.34765 0.0111,-0.19395 0.0153,-0.39129 0.0293,-0.58399 z m 2.08789,0.44338 c 0.20915,0.0561 0.41709,0.0941 0.62696,0.1582 0.4176,0.17683 0.79717,0.31852 1.15234,0.4375 -0.0344,0.16347 -0.0627,0.33003 -0.0957,0.49414 -0.34441,-0.1102 -0.69139,-0.21212 -1.03321,-0.33007 -0.24151,-0.0809 -0.48309,-0.14943 -0.72461,-0.21485 0.0262,-0.18111 0.0456,-0.36515 0.0742,-0.54492 z m -2.90234,0.20313 c 0.19106,0.0266 0.38304,0.0636 0.57422,0.0918 -0.0125,0.21903 -0.024,0.4382 -0.0332,0.65821 -0.16601,-0.0239 -0.33198,-0.053 -0.49804,-0.0781 -0.0144,-0.23095 -0.0286,-0.46702 -0.043,-0.67187 z m 0.77734,0.12304 c 0.60423,0.0951 1.21063,0.22186 1.82031,0.37696 -0.0295,0.20485 -0.0593,0.4092 -0.0859,0.61523 -0.58836,-0.14899 -1.17726,-0.24282 -1.76563,-0.33203 0.008,-0.22136 0.0198,-0.44048 0.0312,-0.66016 z m 4.09961,0.32813 c 0.64638,0.20535 1.2145,0.33822 1.74414,0.43554 -0.0493,0.17948 -0.093,0.3626 -0.14062,0.54297 -0.57469,-0.13531 -1.13806,-0.30457 -1.69922,-0.48047 0.0326,-0.16569 0.0611,-0.33361 0.0957,-0.49804 z m -2.07812,0.0996 c 0.22372,0.0595 0.44537,0.10134 0.66992,0.16992 0.38544,0.16319 0.73671,0.29482 1.06836,0.4082 -0.0375,0.19116 -0.0765,0.38186 -0.11133,0.57422 -0.32223,-0.10377 -0.64679,-0.20011 -0.9668,-0.31055 -0.24913,-0.0834 -0.49695,-0.15368 -0.74609,-0.2207 0.0252,-0.20894 0.0573,-0.414 0.0859,-0.62109 z m -2.74414,0.30859 c 0.15893,0.0257 0.31786,0.0524 0.47656,0.0762 -0.008,0.21689 -0.0273,0.43031 -0.0312,0.64844 -0.13472,-0.0194 -0.26951,-0.041 -0.4043,-0.0625 -0.0138,-0.24156 -0.0269,-0.42968 -0.041,-0.66211 z m 0.68164,0.10938 c 0.57959,0.0927 1.16147,0.21332 1.74609,0.36132 -0.0249,0.20228 -0.0568,0.40174 -0.0781,0.60547 -0.56362,-0.13957 -1.12584,-0.23095 -1.68946,-0.3164 0.002,-0.21898 0.0152,-0.43312 0.0215,-0.65039 z m 3.99804,0.22265 c 0.62838,0.20422 1.18156,0.33936 1.69532,0.4375 -0.053,0.20412 -0.1081,0.40759 -0.15821,0.61328 -0.55747,-0.13478 -1.10338,-0.30451 -1.64844,-0.47656 0.0335,-0.19358 0.075,-0.3824 0.11133,-0.57422 z m -2.05078,0.18945 c 0.23091,0.0611 0.45962,0.105 0.69141,0.17579 0.36294,0.15367 0.69097,0.27559 1.00586,0.38476 -0.0326,0.18711 -0.0701,0.372 -0.0996,0.56055 -0.28411,-0.0925 -0.57107,-0.17597 -0.85352,-0.27344 -0.27075,-0.0907 -0.54174,-0.1688 -0.8125,-0.24023 0.0198,-0.204 0.0452,-0.40524 0.0684,-0.60743 z m 3.94922,0.28321 c 0.19209,0.0346 0.384,0.0686 0.57227,0.0996 -0.0397,0.20343 -0.0805,0.4101 -0.11719,0.65234 -0.20538,-0.0407 -0.40997,-0.084 -0.61328,-0.13086 0.0493,-0.20935 0.10556,-0.41405 0.1582,-0.62109 z m -6.52539,0.0449 c 0.13102,0.0222 0.26186,0.0429 0.39258,0.0625 -0.003,0.24824 -0.002,0.49782 0.002,0.74805 -0.15903,-0.0236 -0.2503,-0.0511 -0.34961,-0.0781 -0.0171,-0.31108 -0.0263,-0.40281 -0.0449,-0.73242 z m 0.61133,0.0977 c 0.55306,0.0888 1.10839,0.20272 1.66601,0.34179 -0.0231,0.23644 -0.0434,0.47405 -0.0605,0.71289 -0.52982,-0.1333 -1.05807,-0.22103 -1.58789,-0.30468 -0.004,-0.24917 -0.0188,-0.50311 -0.0176,-0.75 z m 3.85937,0.20313 c 0.61033,0.20172 1.14356,0.33098 1.64258,0.42969 -0.0472,0.1987 -0.0988,0.39512 -0.14258,0.5957 -0.53836,-0.13488 -1.06652,-0.30045 -1.59375,-0.46875 0.028,-0.18739 0.0633,-0.37095 0.0937,-0.55664 z m -6.20703,0.0742 c -0.13001,-0.0265 -0.55675,0.13977 -0.87109,0.30078 -0.35188,0.18028 -0.85495,0.47515 -1.11914,0.6543 -0.26419,0.17915 -0.86243,0.57544 -0.66211,0.57812 0.20069,0.003 1.22197,-0.45764 2.47851,-1.24023 0.22262,-0.19465 0.25169,-0.27785 0.17383,-0.29297 z m 16.55469,0 c 0.1773,0.0898 0.39366,0.18554 0.51562,0.26563 0.1493,0.0983 0.0816,0.58475 0.0801,0.68359 -0.11266,0.41136 -0.28085,0.47549 -0.63867,0.33789 -0.0189,0.75318 -0.29408,0.92866 -0.88867,1.98047 -0.56096,1.30858 -0.61518,1.52649 -1.29492,3.46289 -0.008,0.68542 -1.86633,3.83984 -2.26368,3.83984 -0.1829,0 -0.23912,0.14955 -0.125,0.33399 0.35263,0.57044 1.15822,-0.36321 2.08594,-2.41602 0.47721,-1.056 0.97152,-2.42307 1.09961,-3.03906 0.12813,-0.61603 0.65113,-1.75695 1.16016,-2.53516 1.06057,-1.62138 1.22175,-2.90499 0.36523,-2.9082 -0.0218,-7e-5 -0.0704,-0.006 -0.0957,-0.006 z m -12.32422,0.12109 c 0.24771,0.0648 0.49347,0.11155 0.74219,0.1875 0.32627,0.13815 0.61737,0.24397 0.90429,0.34571 -0.0336,0.22596 -0.0676,0.45119 -0.0957,0.67968 -0.28549,-0.0929 -0.57361,-0.17745 -0.85742,-0.27539 -0.24666,-0.0826 -0.49357,-0.15225 -0.74023,-0.21875 0.0167,-0.23907 0.0254,-0.48222 0.0469,-0.71875 z m -11.85547,0.0723 c 0.1332,0.58702 0.38873,1.56717 0.95899,3.36914 1.38047,4.08113 2.87774,7.00112 3.72851,7.26758 0.31106,0.0975 0.24734,-0.10812 -0.19336,-0.61719 -1.22101,-1.41124 -1.95489,-2.62617 -3.19726,-6.19922 l -1.11133,-3.78711 c -0.0757,0.003 -0.1388,-0.006 -0.18555,-0.0332 z m 15.67774,0.20312 c 0.21672,0.0404 0.42961,0.0766 0.64062,0.11133 -0.0299,0.20623 -0.0605,0.41527 -0.0898,0.64258 -0.2295,-0.0459 -0.45888,-0.0923 -0.68555,-0.14648 0.043,-0.20392 0.0885,-0.40576 0.13477,-0.60743 z m -6.26172,0.15235 c 0.0957,0.0267 0.1905,0.0509 0.33984,0.0742 0.005,0.23278 0.0195,0.46828 0.0312,0.70312 -0.15023,-0.0214 -0.23313,-0.0241 -0.32617,-0.0293 -0.0143,-0.24588 -0.028,-0.44064 -0.0449,-0.74804 z m 0.57812,0.11133 c 0.51953,0.0875 1.04087,0.19988 1.56446,0.33203 -0.0135,0.21376 -0.0156,0.43239 -0.0234,0.64844 -0.50855,-0.12242 -1.01684,-0.20432 -1.52539,-0.28126 -0.01,-0.23488 -0.0105,-0.46638 -0.0156,-0.69921 z m 3.70899,0.0703 c 0.59255,0.2009 1.1038,0.32723 1.58789,0.42773 -0.0485,0.23019 -0.0977,0.46015 -0.14063,0.69336 -0.51953,-0.13151 -1.02983,-0.29067 -1.53906,-0.45312 0.0273,-0.22459 0.0603,-0.44588 0.0918,-0.66797 z m -5.82032,0.26758 c -0.0816,-0.008 -0.18983,0.0196 -0.20117,0.0234 l -2.10156,1.01954 c -0.23206,0.13266 -0.26909,0.10921 -0.42383,0.24414 -0.15458,0.13682 -0.0114,0.16173 0.12696,0.16211 0.26416,6.4e-4 2.29504,-1.01883 2.63671,-1.27735 0.0994,-0.12623 0.0449,-0.16387 -0.0371,-0.16992 z m 3.91016,0.0547 c 0.22434,0.0596 0.44671,0.10116 0.67188,0.16993 0.32835,0.13902 0.62159,0.24548 0.91015,0.34765 -0.0222,0.19558 -0.0333,0.39599 -0.0508,0.59375 -0.27242,-0.0858 -0.54753,-0.16342 -0.81836,-0.2539 -0.25115,-0.0814 -0.50275,-0.15016 -0.75391,-0.21485 0.01,-0.21655 0.0274,-0.42816 0.041,-0.64258 z m 3.71289,0.15235 c 0.2384,0.0463 0.46914,0.0847 0.69922,0.12305 -0.0286,0.22624 -0.0625,0.50047 -0.0918,0.74218 -0.24602,-0.049 -0.49169,-0.0998 -0.73437,-0.1582 0.0432,-0.23516 0.0794,-0.47492 0.12695,-0.70703 z m -6.0332,0.26367 c 0.0911,0.007 0.18116,0.0117 0.32422,0.0332 0.0104,0.18065 0.0142,0.35898 0.0293,0.54102 0.007,0.0799 0.0105,0.16028 0.0176,0.24023 -0.14637,-0.0208 -0.23041,-0.0373 -0.32617,-0.0547 -0.0102,-0.12388 -0.0311,-0.52924 -0.0449,-0.75977 z m 0.54297,0.0664 c 0.50192,0.0809 1.00586,0.18573 1.51172,0.30859 -0.004,0.14889 -0.0146,0.2952 -0.0156,0.44531 8e-5,0.0977 -0.004,0.19531 -0.004,0.29297 -0.48076,-0.11476 -0.9626,-0.19303 -1.44336,-0.26562 -0.0155,-0.11595 -0.0216,-0.20986 -0.0391,-0.33008 -0.009,-0.15282 -0.002,-0.29925 -0.01,-0.45117 z m 3.5664,0.11523 h 0.002 c 0.56834,0.19209 1.06007,0.31162 1.52734,0.41016 -0.0332,0.18955 -0.0571,0.38427 -0.0859,0.57617 -0.50461,-0.12323 -1.00554,-0.25743 -1.5,-0.41016 0.0186,-0.19232 0.0349,-0.38572 0.0566,-0.57617 z m -11.13867,0.0371 -1.42773,0.56445 0.12109,0.13672 1.42188,-0.54883 z m 5.45899,0.0977 -1.30664,0.65039 c -0.61599,0.29518 -1.18063,0.58853 -1.25391,0.65429 v 0.002 c -0.0673,0.16932 -0.015,0.20936 0.0625,0.2207 0.28233,-0.22639 2.16708,-0.99679 2.58203,-1.34375 z m 3.83593,0.11132 c 0.22876,0.0583 0.45589,0.10007 0.68555,0.16797 0.31733,0.1301 0.60221,0.22882 0.88086,0.32422 -0.0109,0.13923 -0.0288,0.27558 -0.0371,0.41602 -0.005,0.0945 -0.0144,0.18872 -0.0195,0.2832 -0.26456,-0.0831 -0.53194,-0.15846 -0.79492,-0.24609 -0.24306,-0.0786 -0.48546,-0.14476 -0.72852,-0.20703 -0.006,-0.13461 -0.002,-0.24425 -0.01,-0.38477 0.003,-0.1202 0.0188,-0.23398 0.0234,-0.35352 z m -9.09375,0.19532 -1.42773,0.56445 0.12109,0.13672 1.41992,-0.55078 z m 12.69922,0.0215 c 0.25516,0.0499 0.50234,0.0919 0.74805,0.13281 -0.0247,0.20424 -0.0503,0.40702 -0.0762,0.61914 -0.26093,-0.0528 -0.51702,-0.11958 -0.77539,-0.17968 0.0309,-0.19319 0.0696,-0.38117 0.10351,-0.57227 z m 2.1543,0.28125 -0.0801,0.17188 3.99805,0.58789 0.0879,-0.15821 z m -7.9707,0.002 c 0.0943,0.0183 0.18643,0.0334 0.32812,0.0547 0.0203,0.2347 0.0325,0.47017 0.0508,0.70508 -0.10919,-0.0172 -0.18546,-0.0264 -0.26172,-0.0371 -0.022,-0.12265 -0.10074,-0.50715 -0.10742,-0.56055 -0.002,-0.0142 -0.008,-0.14173 -0.01,-0.16211 z m 3.9746,0.0645 c 0.56497,0.18476 1.03186,0.28419 1.49415,0.37695 -0.0222,0.15685 -0.0514,0.31014 -0.0703,0.46875 -0.009,0.0783 -0.0223,0.15609 -0.0312,0.23438 -0.48208,-0.11668 -0.96127,-0.24174 -1.43359,-0.38672 10e-4,-0.1321 0.01,-0.23907 0.01,-0.37696 0.008,-0.10663 0.0218,-0.21036 0.0312,-0.3164 z m -3.41796,0.0254 c 0.47159,0.0762 0.9447,0.17431 1.41992,0.28906 -8.7e-4,0.23117 -0.009,0.46215 -0.0117,0.69336 -0.44201,-0.11631 -0.88417,-0.1945 -1.32617,-0.26953 -0.0232,-0.22789 -0.0507,-0.46714 -0.082,-0.71289 z m -7.27539,0.0312 -1.42774,0.56445 0.12109,0.13477 1.41993,-0.54883 z m 8.92187,0.3125 c 0.21517,0.0549 0.42853,0.0945 0.64453,0.1582 0.30878,0.12624 0.58681,0.22429 0.85742,0.31641 -0.0134,0.23715 -0.0333,0.47385 -0.0488,0.71094 -0.25022,-0.0875 -0.5032,-0.16754 -0.75196,-0.25977 -0.22728,-0.0818 -0.45436,-0.15153 -0.68164,-0.2168 -0.002,-0.22484 -0.011,-0.46625 -0.0195,-0.70898 z m 3.47656,0.0488 c 0.2603,0.0487 0.53439,0.10857 0.78711,0.15039 -0.0316,0.25695 -0.0572,0.48184 -0.0918,0.74609 -0.2694,-0.0491 -0.52962,-0.12454 -0.79493,-0.18555 0.007,-0.10629 0.0191,-0.1907 0.0254,-0.30078 0.0198,-0.1401 0.0528,-0.27117 0.0742,-0.41015 z m 2.17578,0.0273 -0.0801,0.17188 3.99804,0.58593 0.0879,-0.15625 z m -7.70312,0.39453 c 0.0724,0.0114 0.14292,0.019 0.24023,0.0352 0.022,0.29293 0.0467,0.58549 0.0645,0.8789 -0.12439,-0.0186 -0.12691,-0.0225 -0.13477,-0.0273 -0.0671,-0.34147 -0.1283,-0.66195 -0.16992,-0.88672 z m 0.50781,0.082 c 0.43193,0.0787 0.86571,0.17887 1.30078,0.29492 -0.004,0.27226 -0.006,0.54408 -0.0137,0.81641 -0.40797,-0.10108 -0.81467,-0.17012 -1.22266,-0.23633 -0.0164,-0.28049 -0.0353,-0.56632 -0.0644,-0.875 z m 3.26758,0 c 0.53335,0.17163 0.97767,0.26291 1.41602,0.34961 -0.0298,0.25686 -0.0674,0.5129 -0.0996,0.76953 -0.44853,-0.12116 -0.89428,-0.25079 -1.33399,-0.40039 0.01,-0.22687 0.0131,-0.47327 0.0176,-0.71875 z m 3.77734,0.0664 -0.0781,0.17187 3.99805,0.58594 0.0879,-0.15625 z m -14.10937,0.18359 -1.42774,0.56446 0.1211,0.13476 1.42187,-0.54883 z m 8.63281,0.11719 c 0.20063,0.0572 0.40019,0.098 0.60156,0.16406 0.2923,0.13296 0.55382,0.23446 0.81055,0.33203 -0.0171,0.24881 -0.0324,0.49739 -0.0527,0.7461 -0.25056,-0.0819 -0.50294,-0.15761 -0.75196,-0.24414 -0.20816,-0.0702 -0.41684,-0.12895 -0.625,-0.18555 0.008,-0.26309 0.0182,-0.52392 0.0176,-0.8125 z m 3.33399,0.0254 c 0.24521,0.045 0.50743,0.10521 0.74414,0.14258 l 0.0625,-0.10352 c -0.0408,0.31041 -0.10209,0.62462 -0.14844,0.93946 -0.24606,-0.0505 -0.48392,-0.12596 -0.72656,-0.1875 0.0257,-0.25037 0.0481,-0.51734 0.0684,-0.79102 z m 2.01367,0.24414 -0.0781,0.17188 3.99805,0.58593 0.0879,-0.1582 z m -13.7793,0.0176 -1.42773,0.56445 0.11914,0.13477 1.42187,-0.54883 z m 10.10547,0.30859 c 0.49217,0.17447 0.90692,0.27296 1.31445,0.36328 -0.0309,0.24031 -0.0598,0.48068 -0.0937,0.72071 -0.4292,-0.1075 -0.85669,-0.22018 -1.27734,-0.35352 0.0202,-0.23938 0.0428,-0.46967 0.0566,-0.73047 z m -3.54688,0.008 c 0.0188,0.006 0.0257,0.01 0.11329,0.0234 0.0145,0.25428 0.0266,0.50893 0.0371,0.76368 -0.0713,-0.35957 -0.0879,-0.47009 -0.1504,-0.78711 z m 0.37891,0.0664 c 0.40199,0.0699 0.8061,0.15821 1.21094,0.25977 -0.009,0.28122 -0.0187,0.56242 -0.0332,0.84375 -0.38076,-0.0882 -0.76178,-0.16479 -1.14257,-0.22266 -0.004,-0.27647 -0.0196,-0.57887 -0.0352,-0.88086 z m -6.77344,0.041 -1.42773,0.56445 0.11914,0.13672 1.42187,-0.54883 z m 13.47657,0.17578 -0.0801,0.17187 3.99804,0.58789 0.0898,-0.1582 z m -5.23438,0.10937 c 0.18761,0.0503 0.37421,0.0847 0.5625,0.14258 0.29188,0.12448 0.55352,0.22238 0.80859,0.3125 -0.0221,0.25725 -0.0458,0.51438 -0.0723,0.77149 -0.21523,-0.0693 -0.43246,-0.13224 -0.64649,-0.20508 -0.23196,-0.0766 -0.46334,-0.12061 -0.69531,-0.17969 0.02,-0.26414 0.0315,-0.55356 0.043,-0.8418 z m 3.27539,0.0176 c 0.2247,0.0454 0.46612,0.10822 0.68359,0.14649 l 0.0488,-0.0937 c -0.13707,0.92285 -0.28541,1.84537 -0.49804,2.70507 -0.22267,-0.0474 -0.44178,-0.10593 -0.66211,-0.16015 0.0541,-0.24409 0.10445,-0.49939 0.15429,-0.76172 0.17789,0.0323 0.37176,0.0795 0.54493,0.10742 l 0.0684,-0.12109 c -0.19739,-0.036 -0.38742,-0.0945 -0.58204,-0.13867 0.0445,-0.24307 0.0817,-0.5182 0.1211,-0.78321 0.19797,0.0368 0.413,0.0894 0.60547,0.1211 l 0.0742,-0.13477 c -0.22177,-0.0413 -0.43571,-0.10715 -0.65429,-0.1582 0.0333,-0.23641 0.0674,-0.47062 0.0957,-0.72852 z m 1.88867,0.44531 -0.0801,0.17188 3.95313,0.52539 0.0898,-0.1582 z m -3.53906,0.0801 c 0.47531,0.15617 0.87751,0.24383 1.27148,0.32422 -0.0375,0.25858 -0.0734,0.51722 -0.11523,0.77539 -0.41458,-0.10139 -0.82641,-0.21116 -1.23242,-0.33789 0.0301,-0.23852 0.052,-0.5031 0.0762,-0.76172 z m -3.05859,0.15821 c 0.37641,0.0607 0.75373,0.1368 1.13281,0.22656 -0.0145,0.26229 -0.0268,0.5247 -0.0469,0.78711 -0.36295,-0.0772 -0.72493,-0.13791 -1.08789,-0.18946 0.006,-0.26215 0.004,-0.5444 0.002,-0.82421 z m -6.4336,0.0195 -1.42773,0.56445 0.12109,0.13672 1.42188,-0.55078 z m 7.8125,0.26757 c 0.21357,0.0543 0.42611,0.0955 0.64063,0.16016 0.25015,0.10443 0.47266,0.18417 0.69336,0.26172 -0.0262,0.24346 -0.0491,0.48716 -0.0801,0.73047 -0.13421,-0.0447 -0.27053,-0.0829 -0.4043,-0.12891 -0.30655,-0.10246 -0.61336,-0.16697 -0.91992,-0.23828 0.0278,-0.24944 0.0485,-0.51896 0.0703,-0.78516 z m 5.125,0.008 -0.0801,0.17187 3.89843,0.53516 0.0899,-0.1582 z m -12.73633,0.1289 -1.42773,0.56446 0.11914,0.13476 1.42188,-0.54883 z m 9.1875,0.3711 c 0.46377,0.15175 0.85179,0.23463 1.23243,0.31054 -0.0419,0.25212 -0.0819,0.50423 -0.12891,0.75586 -0.40607,-0.10613 -0.8088,-0.22198 -1.20703,-0.35156 0.037,-0.22819 0.0708,-0.47197 0.10351,-0.71484 z m -9.02343,0.0527 -1.42774,0.56445 0.11914,0.13672 1.42188,-0.54882 z m 12.49804,0.0215 -0.0801,0.17187 3.84375,0.53125 0.0898,-0.1582 z m -6.43554,0.0937 c 0.35822,0.0528 0.71743,0.1135 1.07812,0.19336 -0.0175,0.2165 -0.0387,0.43379 -0.0605,0.65039 -0.30252,-0.0596 -0.60556,-0.10288 -0.90821,-0.14454 -0.0397,-0.21227 -0.0679,-0.37019 -0.11328,-0.60546 9.3e-4,-0.0317 0.003,-0.062 0.004,-0.0937 z m 1.29883,0.25 c 0.29061,0.069 0.5806,0.13156 0.87304,0.2207 0.15988,0.0675 0.29651,0.11249 0.44336,0.16797 -0.0264,0.19998 -0.0597,0.39975 -0.0898,0.59961 -0.107,-0.0343 -0.21555,-0.0645 -0.32227,-0.0996 -0.32902,-0.10512 -0.6573,-0.17378 -0.98633,-0.24414 0.0279,-0.21303 0.0566,-0.42467 0.082,-0.64453 z m 5.06445,0.2539 -0.0801,0.17188 3.75,0.54883 0.0898,-0.15821 z m -3.53125,0.2168 c 0.44924,0.1598 0.83558,0.26297 1.19922,0.34375 -0.0366,0.1905 -0.0792,0.38013 -0.11914,0.57031 -0.39887,-0.10142 -0.7942,-0.21303 -1.18555,-0.33594 0.0351,-0.19193 0.0722,-0.38 0.10547,-0.57812 z m 3.40234,0.33594 -0.0801,0.17187 3.7168,0.59375 0.0898,-0.1582 z m -1.98047,0.0527 c 0.22305,0.0448 0.45024,0.0945 0.66602,0.13281 -0.052,0.20405 -0.11595,0.38915 -0.17383,0.58399 -0.2106,-0.0454 -0.41997,-0.0942 -0.6289,-0.14453 0.046,-0.18919 0.0922,-0.37626 0.13671,-0.57227 z" + style="display:inline;opacity:1;vector-effect:none;fill:#616162;fill-opacity:1;stroke:none;stroke-width:0.31999999;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /><path + style="fill:#f8f1d7;fill-opacity:1;stroke:none;stroke-width:0.99999994px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 619.05664,728.89648 c -0.0136,0.21442 -0.031,0.42603 -0.041,0.64258 0.25116,0.0647 0.50276,0.13345 0.75391,0.21485 0.27083,0.0905 0.54594,0.1681 0.81836,0.2539 0.0175,-0.19776 0.0286,-0.39817 0.0508,-0.59375 -0.28856,-0.10217 -0.5818,-0.20863 -0.91015,-0.34765 -0.22517,-0.0688 -0.44754,-0.11033 -0.67188,-0.16993 z" + transform="scale(0.26458333)" + id="path3718" + inkscape:connector-curvature="0" + inkscape:label="orange" /><path + style="fill:#ebeca1;fill-opacity:1;stroke:none;stroke-width:0.99999994px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 617.25391,726.72852 c -0.006,0.21727 -0.0195,0.43141 -0.0215,0.65039 0.56362,0.0855 1.12584,0.17683 1.68946,0.3164 0.0213,-0.20373 0.0532,-0.40319 0.0781,-0.60547 -0.58462,-0.148 -1.1665,-0.26862 -1.74609,-0.36132 z" + transform="scale(0.26458333)" + id="path3712" + inkscape:connector-curvature="0" + inkscape:label="yellow" /><path + inkscape:connector-curvature="0" + id="path3221" + d="m 162.66447,193.95371 c -0.13988,-0.50689 -0.14183,-0.55038 -0.0263,-0.58889 0.0531,-0.0177 0.11799,0.10907 0.14812,0.28928 0.0295,0.17642 0.0771,0.4065 0.10589,0.51127 0.0289,0.1052 0.0144,0.1905 -0.0322,0.1905 -0.0465,0 -0.13443,-0.18097 -0.19547,-0.40216 z" + style="display:inline;fill:#218f21;stroke-width:0.08466666" + inkscape:label="green" /><path + inkscape:connector-curvature="0" + id="path3227" + d="m 162.50287,194.46906 c -0.10611,-0.23139 -0.0911,-0.43226 -0.20126,-0.64538 0.0463,-0.0286 0.0882,-0.0701 0.12291,-0.0488 0.12358,0.0755 0.22998,0.52277 0.26279,0.66028 -0.11606,0.0585 -0.16428,0.0872 -0.18444,0.0339 z" + style="display:inline;fill:#fe2e2e;stroke-width:0.08466666" + sodipodi:nodetypes="ccscc" + inkscape:label="red" /><path + inkscape:label="blue" + sodipodi:nodetypes="ccsccczcccccsccccccccsccsccccscccc" + style="display:inline;fill:#2e51a8;stroke-width:0.08466666" + d="m 165.0721,192.24716 c 0.11577,0.0167 0.70155,0.0255 0.88925,0.008 0.29837,-0.0217 1.00383,0.23252 1.24429,0.39042 0.0395,0.026 0.0216,0.15484 0.0212,0.18099 -0.0511,0.18658 -0.12311,0.12376 -0.47112,-0.0651 -0.17463,-0.0876 -0.58023,-0.18528 -0.90134,-0.21701 -0.3211,-0.0317 -0.66675,-0.0217 -0.73477,-0.0379 -0.068,-0.0162 -0.13557,5.4e-4 -0.0475,-0.25905 z m -4.43342,0.29225 c 0,-0.0999 -0.0618,-0.16543 -0.006,-0.22131 0.20363,-0.0637 0.29492,0.0258 0.57742,-0.17089 0.47957,-0.32451 1.07497,-0.58353 1.49778,-0.58535 0.34961,0 0.42224,0.0139 0.42224,0.10294 0,0.066 -0.029,0.153 -0.029,0.153 -0.0793,0.10437 -0.26688,0.0348 -0.43805,0.0683 -0.33023,0 -0.61963,0.10946 -0.91305,0.34359 -0.15568,0.12422 -0.26659,0.15663 -0.5092,0.23876 -0.44106,0.14931 -0.60233,0.25267 -0.60233,0.071 z m 3.62077,-1.17593 c -0.28458,-0.19709 -0.19911,-0.006 -0.78444,-0.017 -0.88366,-0.0172 -0.889,-0.0182 -0.889,-0.16053 0,-0.0952 0.12051,-0.11835 0.55038,-0.10584 0.30271,0.009 0.4036,-0.002 0.55033,-0.0475 0.062,-0.0266 0.17179,-0.0439 0.26948,-0.048 0.22225,-0.009 0.42781,0.0952 0.60128,0.27927 0.0961,0.0952 0.2389,0.31165 0.28835,0.28548 0.0348,0.0267 0.26569,-0.16317 0.39854,-0.24475 0.2255,-0.1511 0.43624,-0.23203 0.47979,-0.20512 0.0763,0.17481 0.0942,0.16525 0.0388,0.21343 -0.0555,0.0482 -0.18423,0.15408 -0.41773,0.29118 -0.41995,0.20046 -0.53647,0.39532 -1.08572,-0.24064 z" + id="path3703" + inkscape:connector-curvature="0" /></g></g></svg>
\ No newline at end of file diff --git a/src/documentation/content/xdocs/images/project-header.png b/src/documentation/content/xdocs/images/project-header.png Binary files differnew file mode 100644 index 0000000000..92bf1b04db --- /dev/null +++ b/src/documentation/content/xdocs/images/project-header.png diff --git a/src/documentation/content/xdocs/images/remove.png b/src/documentation/content/xdocs/images/remove.png Binary files differnew file mode 100644 index 0000000000..cdf8054f2f --- /dev/null +++ b/src/documentation/content/xdocs/images/remove.png diff --git a/src/documentation/content/xdocs/images/update.png b/src/documentation/content/xdocs/images/update.png Binary files differnew file mode 100644 index 0000000000..339f99dd16 --- /dev/null +++ b/src/documentation/content/xdocs/images/update.png diff --git a/src/documentation/content/xdocs/images/usemap.gif b/src/documentation/content/xdocs/images/usemap.gif Binary files differnew file mode 100644 index 0000000000..91a8e6c385 --- /dev/null +++ b/src/documentation/content/xdocs/images/usemap.gif diff --git a/src/documentation/content/xdocs/index.xml b/src/documentation/content/xdocs/index.xml new file mode 100644 index 0000000000..171883deba --- /dev/null +++ b/src/documentation/content/xdocs/index.xml @@ -0,0 +1,282 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - the Java API for Microsoft Documents</title> + </header> + + <body> + <section><title>Project News</title> + + <section><title>7 July 2025 - Source repository switched from Subversion to Git</title> + <p> + Apache POI switched hosting of the source repository from Subversion to Git. + </p> + <p> + After Subversion served the project well for many years, it was time to enable more + up-to-date workflows by using more of the features offered by Git-based platforms like + GitHub. + </p> + <p> + Therefore the source-code is now officially available at the previous + read-only mirror at <a href="https://github.com/apache/poi">https://github.com/apache/poi</a>. + </p> + <p> + This hopefully allows a smooth transition for anybody already using Git via + the read-only mirror. + </p> + <p> + Users who still used the Subversion-based repository will need to checkout a + fresh copy and migrate any pending changes. + </p> + </section> + + <section><title>8 April 2025 - CVE-2025-31672 - Improper Input Validation vulnerability in Apache POI before 5.4.0</title> + <p> + While parsing of OOXML format files like xlsx, docx and pptx, a specially crafted file could + be used to provide multiple entries with the same name in the zip-compressed file-format. + <br/> + Products reading the affected file could read different data because one of the zip entries with the + duplicate name is selected over another by different products differently.<br/><br/> + This issue affects Apache POI component poi-ooxml before 5.4.0. Starting with 5.4.0 poi-ooxml performs + a check that throws an exception if zip entries with duplicate file names are found in the input file.<br/><br/> + Users are recommended to upgrade to version poi-ooxml 5.4.0 or later, which fixes the issue. + Please refer to our <a href="https://poi.apache.org/security.html">security guidelines</a> + for recommendations about how to use the POI libraries securely. + </p> + <p> + References: + </p> + <ul> + <li><a href="https://bz.apache.org/bugzilla/show_bug.cgi?id=69620">Bug 69620</a></li> + <li><a href="https://www.cve.org/CVERecord?id=CVE-2025-31672">CVE-2025-31672</a></li> + </ul> + </section> + + <!-- latest final release --> + <section><title>6 April 2025 - POI 5.4.1 available</title> + <p>The Apache POI team is pleased to announce the release of 5.4.1. + Several dependencies were updated to their latest versions to pick up security fixes and other improvements.</p> + <p>A summary of changes is available in the + <a href="https://www.apache.org/dyn/closer.lua/poi/release/RELEASE-NOTES.txt">Release Notes</a>. + A full list of changes is available in the <a href="changes.html#5.4.1">change log</a>. + People interested should also follow the <a href="site:mailinglists">dev list</a> to track progress.</p> + <p>See the <a href="download.html#POI-5.4.1">downloads</a> page for more details.</p> + <p>POI requires Java 8 or newer since version 4.0.1.</p> + </section> + + <section><title>11 November 2024 - Avoid log4j-api 2.24.1</title> + <p>While testing a potential Apache POI 5.4.0 release, we discovered a serious bug in + log4j-api 2.24.1. This leads to NullPointerExceptions when you use a version of log4j-core that is not of + the exact same version (2.24.1). We recommend that users avoid log4j 2.24.1 and use the latest + 2.24.x version where this issue is fixed again.</p> + <p>XMLBeans release 5.2.2 had the problematic log4j-api 2.24.1 dependency and thus + can lead to such issues if used in some other context. In the meantime a version 5.3.0 + of XmlBeans was released which avoids this issue.</p> + <p>Please direct any queries to the Log4j Team. The main issue is + <a href="https://github.com/apache/logging-log4j2/issues/3143">Issue 3143</a>.</p> + </section> + + <section><title>4 March 2022 - CVE-2022-26336 - A carefully crafted TNEF file can cause an out of memory exception in Apache POI poi-scratchpad versions prior to 5.2.0</title> + <p>Description:<br/> + A shortcoming in the HMEF package of poi-scratchpad (Apache POI) allows an attacker to cause an Out of Memory exception. + This package is used to read TNEF files (Microsoft Outlook and Microsoft Exchange Server). + If an application uses poi-scratchpad to parse TNEF files and the application allows untrusted users to supply them, then a carefully crafted file can cause an Out of Memory exception.</p> + + <p>Mitigation:<br/> + Affected users are advised to update to poi-scratchpad 5.2.1 or above + which fixes this vulnerability. It is recommended that you use the same versions of all POI jars.</p> + + </section> + + <section><title>10+16+18 December 2021- Log4j vulnerabilities CVE-2021-44228, CVE-2021-45046 and CVE-2021-45105</title> + <p>The Apache POI PMC has evaluated the security vulnerabilities reported + for Apache Log4j.</p> + <p>POI 5.1.0 and XMLBeans 5.0.2 only have dependencies on log4j-api 2.14.1. + The security vulnerabilities are not in log4j-api - they are in log4j-core.</p> + <p>If any POI or XMLBeans user uses log4j-core to control their logging of their application, + we strongly recommend that they upgrade all their log4j dependencies to the latest + version (currently v2.20.0) - including log4j-api.</p> + </section> + + <section><title>13 January 2021 - CVE-2021-23926 - XML External Entity (XXE) Processing in Apache XMLBeans versions prior to 3.0.0</title> + <p>Description:<br/> + When parsing XML files using XMLBeans 2.6.0 or below, the underlying parser + created by XMLBeans could be susceptible to XML External Entity (XXE) attacks.</p> + + <p>This issue was fixed a few years ago but on review, we decided we should have a CVE + to raise awareness of the issue.</p> + + <p>Mitigation:<br/> + Affected users are advised to update to Apache XMLBeans 3.0.0 or above + which fixes this vulnerability. XMLBeans 4.0.0 or above is preferable.</p> + + <p>References: + <a href="https://en.wikipedia.org/wiki/XML_external_entity_attack">XML external entity attack</a> + </p> + </section> + + <section><title>20 October 2019 - CVE-2019-12415 - XML External Entity (XXE) Processing in Apache POI versions prior to 4.1.1</title> + <p>Description:<br/> + When using the tool XSSFExportToXml to convert user-provided Microsoft + Excel documents, a specially crafted document can allow an attacker to + read files from the local filesystem or from internal network resources + via XML External Entity (XXE) Processing.</p> + + <p>Mitigation:<br/> + Apache POI 4.1.0 and before: users who do not use the tool XSSFExportToXml + are not affected. Affected users are advised to update to Apache POI 4.1.1 + which fixes this vulnerability.</p> + + <p>Credit: + This issue was discovered by Artem Smotrakov from SAP</p> + + <p>References: + <a href="https://en.wikipedia.org/wiki/XML_external_entity_attack">XML external entity attack</a> + </p> + </section> + + + <!-- xmlbeans 3.1.0 release --> + <section><title>26 March 2019 - XMLBeans 3.1.0 available</title> + <p>The Apache POI team is pleased to announce the release of XMLBeans 3.1.0. + Featured are a handful of bug fixes.</p> + <p>The Apache POI project has unretired the XMLBeans codebase and is maintaining it as a sub-project, + due to its importance in the poi-ooxml codebase.</p> + <p>A summary of changes is available in the + <a href="https://svn.apache.org/viewvc/xmlbeans/trunk/CHANGES.txt?view=markup">Release Notes</a>. + People interested should also follow the <a href="site:mailinglists">POI dev list</a> to track progress.</p> + <p>The XMLBeans <a href="https://issues.apache.org/jira/projects/XMLBEANS">JIRA project</a> has been reopened and feel free to open issues.</p> + <p>POI 4.1.0 uses XMLBeans 3.1.0.</p> + <p>XMLBeans requires Java 6 or newer since version 3.0.2.</p> + </section> + + <section><title>11 January 2019 - Initial support for JDK 11</title> + <p>We did some work to verify that compilation with Java 11 is working and + that all unit-tests pass. + </p> + <p>See the details in the <a href="help/faq.html#faq-N102B0">FAQ entry</a>.</p> + </section> + </section> + + <section><title>Mission Statement</title> + <p> + The Apache POI Project's mission is to create and maintain Java APIs for manipulating various file formats + based upon the Office Open XML standards (OOXML) and Microsoft's OLE 2 Compound Document format (OLE2). + In short, you can read and write MS Excel files using Java. + In addition, you can read and write MS Word and MS PowerPoint files using Java. Apache POI is your Java Excel + solution (for Excel 97-2008). We have a complete API for porting other OOXML and OLE2 formats and welcome others to participate. + </p> + <p> + OLE2 files include most Microsoft Office files such as XLS, DOC, and PPT as well as MFC serialization API based file formats. + The project provides APIs for the <a href="site:poifs">OLE2 Filesystem (POIFS)</a> and + <a href="site:hpsf">OLE2 Document Properties (HPSF)</a>. + </p> + <p> + Office OpenXML Format is the new standards based XML file format found in Microsoft Office 2007 and 2008. + This includes XLSX, DOCX and PPTX. The project provides a low level API to support the Open Packaging Conventions + using <a href="site:oxml4j">openxml4j</a>. + </p> + <p> + For each MS Office application there exists a component module that attempts to provide a common high level Java api to both OLE2 and OOXML + document formats. This is most developed for <a href="site:spreadsheet">Excel workbooks (SS=HSSF+XSSF)</a>. + Work is progressing for <a href="site:document">Word documents (WP=HWPF+XWPF)</a> and + <a href="site:slideshow">PowerPoint presentations (SL=HSLF+XSLF)</a>. + </p> + <p> + The project has some support for <a href="site:hsmf">Outlook (HSMF)</a>. Microsoft opened the specifications + to this format in October 2007. We would welcome contributions. + </p> + <p> + There are also projects for + <a href="site:diagram">Visio (HDGF and XDGF)</a>, + <a href="site:hmef">TNEF (HMEF)</a>, + and <a href="site:hpbf">Publisher (HPBF)</a>. + </p> + <p> + As a general policy we collaborate as much as possible with other projects to + provide this functionality. Examples include: <a href="https://xml.apache.org/cocoon">Cocoon</a> for + which there are serializers for HSSF; + <a href="https://www.openoffice.org">Open Office.org</a> with whom we collaborate in documenting the + XLS format; and <a href="https://tika.apache.org/">Tika</a> / + <a href="https://lucene.apache.org">Lucene</a>, + for which we provide format interpretors. When practical, we donate + components directly to those projects for POI-enabling them. + </p> + <section><title>Why should I use Apache POI?</title> + <p> + A major use of the Apache POI api is for <a href="text-extraction.html">Text Extraction</a> applications + such as web spiders, index builders, and content management systems. + </p> + <p> + So why should you use POIFS, HSSF or XSSF? + </p> + <p> + You'd use POIFS if you had a document written in OLE 2 Compound Document Format, probably written using + MFC, that you needed to read in Java. Alternatively, you'd use POIFS to write OLE 2 Compound Document Format + if you needed to inter-operate with software running on the Windows platform. We are not just bragging when + we say that POIFS is the most complete and correct implementation of this file format to date! + </p> + <p> + You'd use HSSF if you needed to read or write an Excel file using Java (XLS). You'd use + XSSF if you need to read or write an OOXML Excel file using Java (XLSX). The combined + SS interface allows you to easily read and write all kinds of Excel files (XLS and XLSX) + using Java. Additionally there is a specialized SXSSF implementation which allows to write + very large Excel (XLSX) files in a memory optimized way. + </p> + </section> + <section><title>Components</title> + <p> + The Apache POI Project provides several component modules some of which may not be of interest to you. + Use the information on our <a href="site:components">Components</a> page to determine which + jar files to include in your classpath. + </p> + </section> + </section> + + <section><title>Contributing</title> + <p> + So you'd like to contribute to the project? Great! We need enthusiastic, + hard-working, talented folks to help us on the project, no matter your + background. So if you're motivated, ready, and have the time: Download the + source from the + <a href="site:git">Git Repository</a>, + <a href="site:howtobuild">build the code</a>, join the + <a href="site:mailinglists">mailing lists</a>, and we'll be happy to + help you get started on the project! + </p> + <p> + Please read our <a href="site:guidelines">Contribution Guidelines</a>. + When your contribution is ready submit a patch to our + <a href="https://bz.apache.org/bugzilla/buglist.cgi?product=POI">Bug Database</a>. + </p> + </section> + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document>
\ No newline at end of file diff --git a/src/documentation/content/xdocs/legal.xml b/src/documentation/content/xdocs/legal.xml new file mode 100644 index 0000000000..b5113e2574 --- /dev/null +++ b/src/documentation/content/xdocs/legal.xml @@ -0,0 +1,100 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - Legal Stuff</title> + <authors> + <person id="TK" name="Tetsuya Kitahata" email="tetsuya@apache.org"/> + <person id="DF" name="David Fisher" email="dfisher@jmlafferty.com"/> + </authors> + </header> + + <body> + <section><title>License and Notice</title> +<p> + Apache POI™ releases are available under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0.</a> + See the NOTICE file contained in each release artifact for applicable copyright attribution notices. Release artifacts are available + from the <a href="site:download">Download</a> page. +</p> +</section> + <section><title>Copyrights and Trademarks</title> +<p> +All material on this website is Copyright © 2002-2025, The Apache +Software Foundation. +</p> +<p> +Apache POI, POI, Apache, the Apache feather logo, and the Apache POI +project logo are trademarks of The Apache Software Foundation. +</p> +<p> +Sun, Sun Microsystems, Solaris, Java, JavaServer Web Development Kit, +and JavaServer Pages are trademarks or registered trademarks of Sun +Microsystems, Inc. UNIX is a registered trademark in the United States +and other countries, exclusively licensed through 'The Open Group'. +Microsoft, Windows, WindowsNT, Excel, Word, PowerPoint, Visio, Publisher, Outlook, +and Win32 are registered trademarks of Microsoft Corporation. +Linux is a registered trademark of Linus Torvalds. +All other product names mentioned herein and throughout the entire +web site are trademarks of their respective owners. +</p> + <section><title>Cryptography Notice</title> + <p> + This distribution includes cryptographic software. The country in + which you currently reside may have restrictions on the import, + possession, use, and/or re-export to another country, of + encryption software. BEFORE using any encryption software, please + check your country's laws, regulations and policies concerning the + import, possession, or use, and re-export of encryption software, to + see if this is permitted. See + <a href="http://www.wassenaar.org/">http://www.wassenaar.org/</a> + for more information. + </p> + + <p> + The U.S. Government Department of Commerce, Bureau of Industry and + Security (BIS), has classified this software as Export Commodity + Control Number (ECCN) 5D002.C.1, which includes information security + software using or performing cryptographic functions with asymmetric + algorithms. The form and manner of this Apache Software Foundation + distribution makes it eligible for export under the License Exception + ENC Technology Software Unrestricted (TSU) exception (see the BIS + Export Administration Regulations, Section 740.13) for both object + code and source code. + </p> + + <p> + The cryptographic software used is from <em>java.security</em> and + <em>javax.crypto</em> and is used when processing encrypted and + protected documents. + </p> + </section> +</section> +</body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/news.xml b/src/documentation/content/xdocs/news.xml new file mode 100644 index 0000000000..c6854515b2 --- /dev/null +++ b/src/documentation/content/xdocs/news.xml @@ -0,0 +1,233 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - In the News over the world</title> + <authors> + <person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/> + <person id="TK" name="Tetsuya Kitahata" email="tetsuya@apache.org"/> + </authors> + </header> + + <body> + <section><title>POI in the news</title> + <p> + These are articles/etc. posted about POI around the web. If you + see POI in the news or mentioned at least somewhat prominently + on a site (not your homepage that you put the work POI on in + order to get us to link you and by the why here is a picture of + your wife in kids) then send a patch to the list. In general + equal time will be given so please feel free to send inflammatory + defamation as well as favorable, technical and factual. Really + stupid things won't be mentioned (sorry). + </p> + </section> + <section><title>English</title> + <ul> + <li> + <a href="http://archive.midrange.com/web400/200204/msg00023.html">Discussion about using POI on AS/400s</a> + </li> + <li> + <a href="http://www.somelist.com/mails/23819.html">Discussion from back when we almost had POI as the filter for KOffice if politics and licenses hadn't killed iit</a> + </li> + <li> + <a href="http://www.oreillynet.com/pub/wlg/1552?page=last&x-showcontent=text">Java discussion on O'Reilly Network including discussion about POI</a> - O'Reilly.net + </li> + <li> + <a href="http://www.rollerweblogger.org/page/roller/20020715">Poor Obfuscation Implementation.</a> - Blog of David M. Johnson + </li> + <li> + <a href="http://www.jsurfer.org/article.php?sid=322"> + POI 1.5-dev-rc2 released </a> - JSurfer + </li> + + <li> + <a href="http://directory.google.com/Top/Computers/Programming/Languages/Java/Class_Libraries/Data_Formats/Microsoft_Formats/"> Google says we're the most important in our category </a> + </li> + <li> + <a href="http://www.javaworld.com/javaworld/javaqa/2002-05/01-qa-0503-excel3.html">It's POI-fect</a> - Tony Sintes, Javaworld + </li> + <li> + <a href="http://www.need-a-cake.com/categories/cocoonWeblog/2002/03/07.html"> + Nicola announces POI serialization code + </a> - Matthew Langham's Radio Weblog + </li> + <li> + <a href="http://javalobby.org/discussionContext/showThreaded/frm/javalobby?folderId=20&discussionContextId=11523"> + Jakarta POI 1.4583 Released</a> - JavaLobby + </li> + <li> + <a href="http://javalobby.org/discussionContext/showThreaded/frm/javalobby?discussionContextId=11442&folderId=20"> + POI project moves to Jakarta (OLE 2 CDF/Excel/Word in + pure java)</a> - JavaLobby + </li> + <li> + <a + href="http://www.geocities.com/marcoschmidt.geo/java-image-coding.html"> + List of Java libraries to read and write image and document files + </a> Marco Schmidt's homepage (normally we wouldn't + feature someone's homepage but its an extensive list of + information including "alternatives to POI" (for those + of you who are very wealthy). But heck I think I'll + bookmark his page for myself since he's like got every + piece of info known to man linked or featured on it! + </li> + <li> + <a href="http://radio.weblogs.com/0101350/"> + The Experiences of an Operator (Måns af Klercker) + </a> - radio.weblogs.com + </li> + <li> + <a href="http://dataconv.org/apps_office.html"> + DATACONV - Data Conversion Tools: Office + </a> DATACONV + </li> + <li> + <a href="http://chicago.sourceforge.net/devel/"> + Chicago Developer Page + </a> + </li> + <li> + <a href="http://www.onjava.com/pub/d/1157"> + POI/POI Serialization Project + </a> - Man you know you've hit the bigtime when + O'Reilly Likes you.. ;-) + </li> + <li> + <a + href="http://www.javaworld.com/netnews/index.shtml"> + News Around the Net + </a> - Java World + </li> + + </ul> + </section> + <section><title>Nederlandstalige (Dutch)</title> + <ul> + <li> + <a + href="http://www.ster.be/java/java9.html"> + Een Excel-werkboek maken vanuit Java - Lieven Smits + </a> + </li> + </ul> + </section> + <section><title>Deutsch (German)</title> + <ul> + <li> <a + href="http://www.entwickler.com/itr/news/show.php3?id=6132&nodeid=82 ">Apache POI verffentlicht</a> - entwicker.com + </li> + <li> + <a + href="http://www.jsp-develop.de/newsletter/10/"> + Apache Jakarta-Projekt bringt Word und Excel in die Java-Welt </a> - jsp-develop.de (for the misguided who use JSP ;-) ) + </li> + <li> + <a + href="http://www.entwickler.com/news/2002/02/5718/news.shtml"> + Neues Apache-Projekt bringt Word- und Excel nach Java + </a> - entwickler.com + </li> + </ul> + </section> + <section><title>Español (Spanish)</title> + <ul> + <li> + <a href="http://www.javahispano.com/noticias/todas.jsp"> + OLE2 desde Java nativo + </a> - javaHispano + </li> + <li> + <a href="http://p2p.wrox.com/archive/java_espanol/2002-08/3.asp">Spanish discussion about Excel and Java including POI from Wrox forums</a> + </li> + </ul> + </section> + <section><title>Français (French)</title> + <ul> + <li> + <a href="http://linuxfr.org/section/D%E9veloppeur,0,1,8,0.html"> + Excel/OLE accessibles + </a> - Da Linux French Page + </li> + <li> + <a href="http://www.sogid.com/javalist/f2002/traiter_word_java.html">Discussion on POI in French</a> + </li> + </ul> + </section> + <section><title>Nihongo (Japanese)</title> + <ul> + <li> + <a href="http://drpanda.freezope.org/Memo/docs/jakarta/poi/poi_sample">100% PureJava...</a> - Dr. Panda Portal + </li> + <li> + <a + href="http://www.gimlay.org/~andoh/java/javanew.html"> + What's new with java? + </a> - gimlay.org + </li> + <li><a href="http://taka-2.com/jclass/POI/">Java de Excel</a> - How to use Japanese with POI</li> + <li><a href="http://www.tech-arts.co.jp/macosx/webobjects-jp/htdocs/3200/3218.html">Various discussion in Japanese including on POI</a></li> + <li><a href="http://muimi.com/j/jakarta/">Japanese resources on Jakarta projects including POI</a></li> + <li><a href="http://www.fk.urban.ne.jp/home/kishida/">Kishida's site</a> -- Weekly Forte Lectures -- includes a snip about POI and Japanese.</li> + + </ul> + </section> + <section><title>Russkii Yazyk (Russian)</title> + <ul> + <li> + <a href="http://www.nestor.minsk.by/kg/kg02/21/kg22108.html"> + Probably a translation of the Javalobby announcement of 1.5-final + </a> -- Computer News (What's New) + </li> + </ul> + </section> + <section><title>Hangul (Korean)</title> + <ul> + <li> + <a href="http://www.javabrain.co.kr/AnswerView?questionId=1189&categoryId=8">Various discussion in Korean about Excel output/APIs including POI</a> + </li> + </ul> + </section> + <section><title>No freaking idea</title> + <p> + If you can read one of these languages, send mail to the list + telling us what language it is and we'll categorize it! + </p> + <ul> + <li> + <a + href="http://www.javacentrix.com/index.htm"> + If I had to guess, I'd say this is Thai, but + maybe you actually know</a> - javacentrix.com + </li> + </ul> + </section> + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/related-projects.xml b/src/documentation/content/xdocs/related-projects.xml new file mode 100644 index 0000000000..c6bc2ef8a3 --- /dev/null +++ b/src/documentation/content/xdocs/related-projects.xml @@ -0,0 +1,254 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - Related Projects</title> + </header> + + <body> + <section> + <title>Introduction</title> + <p> + This page lists other projects that you might find interesting when working with documents of various types. Suggestions for additional links are welcome, however please note that we only list open source projects here. Commercial applications can provide <a href="casestudies.html">case studies</a> if they want to show their support for POI. + </p> + </section> + <section> + <title>Apache projects</title> + <section> + <title>Apache Tika</title> + <p> + <a href="https://tika.apache.org/">Apache Tika</a> + is a toolkit which detects and extracts metadata and text from over a thousand different file types. + </p> + </section> + <section> + <title>Apache Drill</title> + <p> + <a href="https://drill.apache.org/">Apache Drill</a> + is a toolkit that allows the use of SQL querying on numerous file and data formats. The POI support is in + the <a href="https://drill.apache.org/docs/excel-format-plugin/">excel-format-plugin</a>. + </p> + </section> + <section> + <title>Apache Hop</title> + <p> + <a href="https://hop.apache.org/">Apache Hop</a> + is a data orchestration and data engineering platform. The POI support is in + the <a href="https://hop.apache.org/manual/latest/pipeline/transforms/excelinput.html">excelinput</a> transform + and the <a href="https://hop.apache.org/manual/latest/pipeline/transforms/excelwriter.html">excelwriter</a> transform. + + </p> + </section> + <section> + <title>Apache DolphinScheduler</title> + <p> + <a href="https://dolphinscheduler.apache.org/">Apache DolphinScheduler</a> + is a distributed and easy-to-extend visual workflow scheduler system. The POI support is in + the alert email component. + + </p> + </section> + <section> + <title>Worksheet plugin for JSPWiki</title> + <p> + There is a <a href="https://jspwiki-wiki.apache.org/Wiki.jsp?page=WorksheetPlugin#top">Worksheet + plugin</a> for <a href="https://jspwiki.apache.org/">JSPWiki</a> which allows you to display contents of Excel + files as a table in JSPWiki. + </p> + </section> + </section> + <section> + <title>Apache incubating projects</title> + <section><title>Apache Linkis</title> + <p> + <a href="https://linkis.apache.org/">Apache Linkis (incubating)</a> is a computation middleware layer. + The linkis-storage component has an Excel read capability built using Apache Poi. + </p> + </section> + <section><title>Apache Seatunnel</title> + <p> + <a href="https://seatunnel.apache.org/">Apache Seatunnel (incubating)</a> is a high-performance, distributed, massive data integration framework. + The seatunnel-connector-spark-email component uses Apache Poi. + </p> + </section> + <section><title>Apache ODF Toolkit (retired)</title> + <p> + <a href="https://incubator.apache.org/projects/odftoolkit.html">Apache ODF Toolkit (incubating)</a> is a set of Java modules that allow programmatic creation, scanning and manipulation of OpenDocument Format (ISO/IEC 26300 == ODF) documents. + See also <a href="https://odftoolkit.org/">new website</a>. + </p> + </section> + + <section><title>Apache Corinthia (retired)</title> + <p> + <a href="https://corinthia.incubator.apache.org/">Apache Corinthia (incubating)</a> is a toolkit/application written in C++ for converting between and editing common office file formats, with an initial focus on word processing. + </p> + </section> + </section> + <section> + <title>Other projects</title> + <section><title>Jackcess</title> + <p> + <a href="http://jackcess.sourceforge.net/">Jackcess</a> is a pure Java library for reading from and writing to MS Access databases available under Apache License 2.0. + </p> + </section> + <section><title>poi-mail-merge</title> + <p> + <a href="https://github.com/centic9/poi-mail-merge">poi-mail-merge</a> is a small tool to automate mail-merges, i.e. replacing strings in a template Microsoft Word file multiple times with data from a list of replacements + provided as Excel/CSV data. Available under the BSD 2-Clause License. + </p> + </section> + <section><title>poi-visio</title> + <p>Merged into POI as of version 3.14</p> + <p> + <a href="https://github.com/BBN-D/poi-visio">poi-visio</a> is a Java library that loads Visio OOXML (vsdx) files and creates an in-memory data structure that allows full access to the contents of the document. + There is built-in support for easily traversing the content of the document in a structured way, and can render pages to simplified PNG files, or other backends supported by Java AWT. + Currently, the library only operates in read-only mode, but its design does not exclude being able to modify existing documents or creating new documents. + Available under the Apache License, Version 2.0. + </p> + </section> + <section><title>poi-visio-graph</title> + <p> + <a href="https://github.com/BBN-D/poi-visio-graph">poi-visio-graph</a> is a Java library that loads Visio OOXML (vsdx) files using the poi-visio library and creates an in-memory graph structure from the objects present on the page. + It utilizes user-specified connection points and also performs analysis to infer logical visual connection points between the objects on each page. + One possible use of this library is to create a network diagram from a Visio document. + Available under the Apache License, Version 2.0. + </p> + </section> + <section><title>NPOI</title> + <p> + <a href="https://npoi.codeplex.com/">NPOI</a> is a .NET version of Apache POI available under Apache License 2.0. + </p> + </section> + <section><title>Vaadin Spreadsheet</title> + <p> + <a href="https://github.com/vaadin/spreadsheet">Vaadin Spreadsheet</a> is a UI component add-on for Vaadin 7 which provides means to view and edit Excel spreadsheets in Vaadin applications. + Available under the Commercial Vaadin Add-on License version 3 (CVALv3). + </p> + </section> + <section><title>Excel module for Apache Isis</title> + <p> + <a href="https://github.com/isisaddons/isis-module-excel">Excel module for Apache Isis</a> is an add on for Apache Isis and provides a domain service so that a collection of (view model) + object scan be exported to an Excel spreadsheet, or recreated by importing from Excel. + Available under the Apache License, Version 2.0. + </p> + </section> + <section><title>Excel Streaming Reader</title> + <p> + <a href="https://github.com/monitorjbl/excel-streaming-reader">Excel Streaming Reader</a> uses the POI Streaming API to provide Row/Cell like read-access to large Excel spreadsheets. + Available under the Apache License, Version 2.0. + </p> + <p> + <a href="https://github.com/pjfanning/excel-streaming-reader">Forked Version</a> that supports the latest POI versions. + Has support for a number of extra features, including Strict OOXML files. + Also, available under the Apache License, Version 2.0. + </p> + </section> + <section><title>fast-excel</title> + <p> + <a href="https://github.com/dhatim/fastexcel/">fastexcel</a> is a benchmarked library for reading and writing Excel files. + Available under the Apache License, Version 2.0. + </p> + </section> + <section><title>poi-shared-strings</title> + <p> + <a href="https://github.com/pjfanning/poi-shared-strings/">poi-shared-strings</a> is a memory efficient Shared Strings Table and Comments Table implementation for POI streaming. + Available under the Apache License, Version 2.0. + </p> + </section> + <section><title>The Wordinator</title> + <p> + <a href="https://github.com/drmacro/wordinator">The Wordinator</a> abstracts the general problem of mapping from XML (or any similar structured content--with XSLT 3 you could just as easily process JSON content or some other format) to word processing data through a relatively simple XML structure, the Simple Word Processing Markup Language (SWPX), which is basically OOXML simplified way down. + Available under the Apache License, Version 2.0. + </p> + </section> + <section><title>POI-TL</title> + <p> + <a href="https://github.com/Sayi/poi-tl">POI-TL</a> is a Word template engine that generates new documents based on a Word template and data. + Available under the Apache License, Version 2.0. + </p> + </section> + <section><title>XDocReport</title> + <p> + <a href="https://github.com/opensagres/xdocreport">XDocReport</a> is a Java API to merge XML document created with MS Office (docx) or OpenOffice (odt), + LibreOffice (odt) with a Java model to generate report and convert it if you need to another format (PDF, XHTML...). + XDocReport code is license under MIT license but the samples are licensed under LGPL license. + </p> + </section> + <section><title>Frosted Sheets</title> + <p> + <a href="https://bitbucket.org/erosa/frostedsheets/overview">Frosted Sheets</a> is a Groovy library which provides decorators for Apache POI spreadsheets, making it easier to work with spreadsheets + in Groovy. + Frosted Sheets is license under the Apache License, Version 2.0. + </p> + </section> + <section><title>IEXL Software</title> + <p> + <a href="http://www.iexlsoftware.com/">iEXL</a> is a commercial product which allows you to generate Excel spreadsheets on AS/400, iSeries, i5 or IBM i on Power systems. + It uses Apache POI internally. + </p> + </section> + <section><title>jotlmsg</title> + <p> + <a href="https://github.com/ctabin/jotlmsg">jotlmsg</a> is a simple API (on top of POI) to easily generate Microsoft Outlook message files (.msg). + </p> + </section> + <section><title>HadoopOffice</title> + <p> + <a href="https://github.com/ZuInnoTe/hadoopoffice">HadoopOffice</a> allows you to read and write Office documents while using the Hadoop ecosystem. + Available under the Apache License, Version 2.0. + </p> + </section> + <section><title>Scala POI Wrapper</title> + <p> + <a href="https://github.com/norbert-radyk/spoiwo">SPOIWO</a> allows you to read and write Office documents using Scala friendly APIs. + Available under the MIT License. + </p> + </section> + <section><title>Spark Excel</title> + <p> + <a href="https://github.com/crealytics/spark-excel">Spark Excel</a> allows you to read and write Excel documents into/from Spark Dataframes. + Available under the Apache License, Version 2.0. + </p> + </section> + <section><title>ExcelUtil</title> + <p> + <a href="https://github.com/nambach/ExcelUtil">ExcelUtil</a> is a Java wrapper using Apache POI to read and write Excel files in declarative fashion. + Available under the Apache License, Version 2.0. + </p> + </section> + <section><title>bld-commons/dev-excel</title> + <p> + <a href="https://github.com/bld-commons/dev-excel">dev-excel</a> is a Java wrapper using Apache POI to read and write Excel files. + Available under the MIT License. + </p> + </section> + </section> + </body> + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/security.xml b/src/documentation/content/xdocs/security.xml new file mode 100644 index 0000000000..a902f05a8a --- /dev/null +++ b/src/documentation/content/xdocs/security.xml @@ -0,0 +1,114 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + + +<document> + <header> + <title>Apache POI™ - Security guidance</title> + <authors> + <person id="centic" name="Dominik Stadler" email="centic@apache.org"/> + </authors> + </header> + + <body> + <section> + <title>Overview</title> + + <p>This page provides some guidance about how Apache POI can be used in security-sensible areas.</p> + </section> + + <section> + <title>Information about related security vulnerabilities</title> + + <p>Information about security issues is included in the <a href="index.html">Project News</a>.</p> + </section> + + <section> + <title>Reporting security vulnerabilities</title> + + <p>Apache POI will try to fix security-related bugs with priority.</p> + + <p>Please follow the general <a href="https://www.apache.org/security/">Apache Security Guidelines</a> + for proper handling.</p> + + <p>But please note that by the nature of processing external files, you should design your application + in a way which limits impact of malicious documents as much as possible. The higher your security-related + requirements are, the more you likely need to invest in your application to contain effects. + </p> + </section> + + <section> + <title>Architecting your Application</title> + + <p>If you are processing documents from an untrusted source, you should add a number of safeguards to + your application to contain any unexpected side effects.</p> + + <p>Apache POI cannot fully protect against some documents causing impact on the current process, therefore + we suggest the following additional layers of security.</p> + + <ul> + <li><strong>Expect any type of Exception when processing documents</strong><br/> + As parsing the various formats is very complex and involved, there are some unexpected types of + exceptions which can be thrown. E.g. StackOverflowError or many different types of RuntimeException. + <br/> + Make sure to have a broad catch-statement around your document-parsing functionality and be prepared + to handle all those gracefully. + </li> + <li><strong>Expect long parsing time</strong><br/> + As parsing the various formats is very complex and involved, some documents might cause prolonged CPU + usage and long parsing time. + <br/> + If this is a concern, make sure to have a way to stop processing after some time, maybe by the + sandboxing approach described below. + </li> + <li><strong>Memory use can be very high</strong><br/> + The data in Microsoft format files is usually compressed so even small files can have a lot of data. + <br/> + The core POI APIs are not optimized to avoid excessive memory use. POI has streaming APIs for reading + and writing xlsx files - so if you are working with large xlsx files, you should consider using the + streaming APIs. + </li> + <li><strong>Consider sandboxing document-parsing</strong><br/> + If you operate in a highly sensitive environment and would like to avoid any side effect from + parsing documents on your application, then consider extracting the parsing logic into a separate + process which is configured with appropriate memory settings and which you stop after some timeout. + It is a good idea to be able to auto-restart the process in case of a crash. + <br /> + </li> + <li><strong>Keep up to date with releases</strong><br/> + Apache POI does occasionally issue CVEs for security issues. There are also other bug fixes and + improvements in each release. Some of these fixes will be to make POI more robust against malicious + inputs, even if they are not explicitly security-related. + <br /> + </li> + </ul> + </section> + </body> + + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/content/xdocs/site.xml b/src/documentation/content/xdocs/site.xml new file mode 100644 index 0000000000..3bfb5efbe7 --- /dev/null +++ b/src/documentation/content/xdocs/site.xml @@ -0,0 +1,172 @@ +<?xml version="1.0"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!-- +Forrest site.xml + +This file contains an outline of the site's information content. It is used to: +- Generate the website menus (though these can be overridden - see docs) +- Provide semantic, location-independent aliases for internal 'site:' URIs, eg +<a href="site:changes"> links to changes.html (or ../changes.html if in + subdir). +- Provide aliases for external URLs in the external-refs section. Eg, <a + href="ext:cocoon"> links to https://xml.apache.org/cocoon/ + +See https://xml.apache.org/forrest/linking.html for more info +--> +<site label="POI" xmlns="http://apache.org/forrest/linkmap/1.0"> + <home label="Overview" tab="home"> + <index label="Home" href="index.html"/> + <download label="Download" href="download.html"/> + <changes label="Changelog" href="changes.html"/> + <javadocs label="Javadocs" href="apidocs/index.html"/> + <extraction label="Text Extraction" href="text-extraction.html"/> + <encryption label="Encryption support" href="encryption.html"/> + <encryption label="Secure processing" href="security.html"/> + <casestudies label="Case Studies" href="casestudies.html"/> + <related label="Related projects" href="related-projects.html"/> + <legal label="Legal" href="legal.html"/> + </home> + <apache label="Apache Wide" tab="home"> + <asf label="Apache Software Foundation" href="https://www.apache.org/"/> + <license label="License" href="https://www.apache.org/licenses/"/> + <sponsor label="Sponsorship" href="https://www.apache.org/foundation/sponsorship.html"/> + <thanks label="Thanks" href="https://www.apache.org/foundation/thanks.html"/> + <security label="Security" href="https://www.apache.org/security/"/> + <privacy label="Privacy" href="https://privacy.apache.org/policies/privacy-policy-public.html"/> + </apache> + <components label="Component APIs" href="components/" tab="components"> + <index label="Overview" href="index.html"> + <batikpdf href="#components"/> + </index> + <javadocs label="Javadocs" href="site:javadocs"/> + <spreadsheet label="Excel (HSSF/XSSF)" href="spreadsheet/"> + <index label="Overview" href="index.html"/> + <ssquickguide label="Quick Guide" href="quick-guide.html"/> + <sshowto label="HOWTO" href="how-to.html"/> + <sscommon label="HSSF to SS Converting" href="converting.html"/> + <formsupp label="Formula Support" href="formula.html"/> + <formeval label="Formula Evaluation" href="eval.html"/> + <evalguide label="Eval Dev Guide" href="eval-devguide.html"/> + <ssexamples label="Examples" href="examples.html"/> + <usecases label="Use Case" href="use-case.html"/> + <picdocs label="Pictorial Docs" href="diagrams.html"/> + <limits label="Limitations" href="limitations.html"/> + <udf label="User Defined Functions" href="user-defined-functions.html"/> + <excelant label="ExcelAnt Tests" href="excelant.html"/> + <hackhssf label="Hacking HSSF" href="hacking-hssf.html"/> + <recordgen label="Record Generator" href="record-generator.html"/> + <charts label="Charts" href="chart.html"/> + </spreadsheet> + <slideshow label="PowerPoint (HSLF/XSLF)" href="slideshow/"> + <index label="Overview" href="index.html"/> + <slquickguide label="Quick Guide" href="quick-guide.html"/> + <hslfcook label="HSLF Cookbook" href="how-to-shapes.html"/> + <xslfcook label="XSLF Cookbook" href="xslf-cookbook.html"/> + <slrender label="Render SL/WMF/EMF" href="ppt-wmf-emf-renderer.html"/> + <format label="PPT File Format" href="ppt-file-format.html"/> + </slideshow> + <document label="Word (HWPF/XWPF)" href="document/"> + <index label="Overview" href="index.html"/> + <hwpfquick label="HWPF Quick Guide" href="quick-guide.html"/> + <xwpfquick label="XWPF Quick Guide" href="quick-guide-xwpf.html"/> + <docformat label="HWPF Format" href="docoverview.html"/> + <hwpfplan label="HWPF Project plan" href="projectplan.html"/> + </document> + <hsmf label="Outlook (HSMF)" href="hsmf/index.html"/> + <diagram label="Visio (HDGF+XDGF)" href="diagram/index.html"/> + <hpbf label="Publisher (HPBF)" href="hpbf/"> + <index label="Overview" href="index.html"/> + <hpbformat label="File Format" href="file-format.html"/> + </hpbf> + <poifs label="OLE2 Filesystem (POIFS)" href="poifs/"> + <index label="Overview" href="index.html"/> + <howto label="How To" href="how-to.html"/> + <embedded label="Embedded Documents" href="embeded.html"/> + <format label="File System Documentation" href="fileformat.html"/> + <usecases label="Use Cases" href="usecases.html"/> + <design label="Design" href="design.html"/> + </poifs> + <hpsf label="OLE2 Document Props (HPSF)" href="hpsf/"> + <index label="Overview" href="index.html"/> + <howto label="How To" href="how-to.html"/> + <thumbnails label="Thumbnails" href="thumbnails.html"/> + <internals label="Internals" href="internals.html"/> + <todo label="To Do" href="todo.html"/> + </hpsf> + <hmef label="TNEF (HMEF) for winmail.dat" href="hmef/index.html"/> + <oxml4j label="OpenXML4J (OOXML)" href="oxml4j/index.html"/> + <log label="Logging framework" href="logging.html"/> + <config label="Configuration" href="configuration.html"/> + </components> + <help label="Help" tab="help" href="help/"> + <mailinglists label="Mailing Lists" href="index.html"/> + <faq label="FAQ" href="faq.html"/> + <bugs label="Bug Database" href="https://bz.apache.org/bugzilla/buglist.cgi?product=POI"/> + </help> + <!-- can't use directory "community" because of forrest default rules in sitemap.xmap -> revisions --> + <community label="Getting Involved" href="devel/" tab="community"> + <howtobuild label="How To Build" href="index.html"/> + <nightly label="Nightly Builds" href="nightly.html"/> + <git label="Git Repository" href="git.html"/> + <guidelines label="Contribution Guidelines" href="guidelines.html"/> + <whoweare label="Who We Are" href="who.html"/> + <plan label="Planning Documents" href="plan/"> + <planning label="Overview" href="index.html"/> + <vision10 label="1.0 Vision" href="vision10.html"/> + <vision20 label="2.0 Vision" href="vision20.html"/> + </plan> + <references label="References" href="references/"> + <index label="Overview" href="index.html"/> + <logocontest label="Logo Submissions" href="logocontest.html"/> + <xlsspec label="XLS spec [PDF]" href="https://sc.openoffice.org/excelfileformat.pdf"/> + <cocoon label="Apache Cocoon" href="https://xml.apache.org/cocoon/"/> + </references> + <resolutions label="Resolutions" href="resolutions/"> + <index label="Overview" href="index.html"/> + <res001 label="Minimal Coding Standards" href="res001.html"/> + </resolutions> + <history label="History" href="history/"> + <historyfuture label="The early years" href="index.html"/> + <changes3x label="Changelog 3.x" href="changes-3x.html"/> + <changespre3x label="Changelog 0-2.x" href="changes-pre3x.html"/> + </history> + </community> + + <external-refs> + <forrest href="http://forrest.apache.org/"> + <aing href="docs/linking.html"/> + <validation href="docs/validation.html"/> + <webapp href="docs/your-project.html#webapp"/> + <dtd-docs href="docs/dtd-docs.html"/> + </forrest> + <cocoon href="https://cocoon.apache.org/"/> + <xml.apache.org href="https://xml.apache.org/"/> + <junit href="junit/index.html"/> + <jdepend href="jdepend/index.html"/> + <download href="https://www.apache.org/dyn/closer.lua/poi/"/> + <apidocs href="https://poi.apache.org/apidocs/"> + <v317 href="3.17/"/> + <v40 href="4.0/"/> + <v41 href="4.1/"/> + <v50 href="5.0/"/> + <dev href="dev/"/> + </apidocs> + </external-refs> +</site> diff --git a/src/documentation/content/xdocs/status.copy_module_from_bugzilla.py b/src/documentation/content/xdocs/status.copy_module_from_bugzilla.py new file mode 100644 index 0000000000..b7bf8f979e --- /dev/null +++ b/src/documentation/content/xdocs/status.copy_module_from_bugzilla.py @@ -0,0 +1,89 @@ +#!/usr/bin/env python3 +""" + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +""" + +"""This is a really crude throwaway script to get data out of Bugzilla and into status.xml +It'd be far better to have Forrest look this information up whenever the site is rebuilt. +Hopefully this is a one time effort +If a closed bug's component is changed in Bugzilla, this script could be used to keep the changelog in sync. + +requires Python 3.1+ +(Python 2.x doesn't do Unicode in CSVs nicely) +""" + +import csv, io +import sys +import requests + +def get_fixesbug_attr(line): + pieces = [x.strip() for x in line.split('"')] + bugs = pieces[pieces.index('fixes-bug=') + 1] + return bugs + +def get_bugzilla_bug_to_component(): + print("Fetching details of POI bugs, please wait...") + bugzilla_bug_to_component = {} + r = requests.get('https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__all__&limit=0&no_redirect=1&product=POI&query_format=advanced&ctype=csv&human=1') + with io.StringIO(r.text) as f: + csvreader = csv.DictReader(f) + for row in csvreader: + bugzilla_bug_to_component[row['Bug ID']] = row['Component'] + return bugzilla_bug_to_component + + +def unique(seq): + seen = set() + for x in seq: + if x not in seen: + seen.add(x) + yield x + +def add_module_frombugzilla_attr(line): + """Add module_frombugzilla="XSSF" to <action ...> tag + + line is a string, containing the <action> opening tag + """ + global bugzilla_bug_to_component + assert 'module=' not in line, \ + "Invalid action line, should not already contain module: %s" % line + + bugs = [x.strip() for x in get_fixesbug_attr(line).split(',')] + modules = filter(bool, [bugzilla_bug_to_component.get(bug) for bug in bugs]) + module_frombugzilla = ','.join(unique(modules)) + line_with_module_frombugzilla = line.replace('>', ' module="{}">'.format(module_frombugzilla), 1) + return line_with_module_frombugzilla + +def add_module_attribute(inputfile, outputfile): + print("Generating %s from %s and Bugzilla details"%(outputfile,inputfile)) + with open(inputfile, 'r') as infile, open(outputfile, 'w') as outfile: + for line in infile: + if '<action ' in line and ' fixes-bug=' in line and ' module=' not in line: + # append "module="XXXX" at end of <action> tag + outfile.write(add_module_frombugzilla_attr(line)) + else: + outfile.write(line) + + +if __name__ == '__main__': + if len(sys.argv) != 3: + print('Usage: python changelog.py inputfile outputfile') + else: + bugzilla_bug_to_component = get_bugzilla_bug_to_component() + add_module_attribute(sys.argv[1], sys.argv[2]) + print("Generation complete!") diff --git a/src/documentation/content/xdocs/tabs.xml b/src/documentation/content/xdocs/tabs.xml new file mode 100644 index 0000000000..fbfae1ccbd --- /dev/null +++ b/src/documentation/content/xdocs/tabs.xml @@ -0,0 +1,35 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE tabs PUBLIC "-//APACHE//DTD Cocoon Documentation Tab V1.1//EN" "http://forrest.apache.org/dtd/tab-cocoon-v11.dtd"> + +<tabs software="POI" title="POI" copyright="The Apache Software Foundation"> + + <!-- The rules are: + @dir will always have /index.html added. + @href is not modified unless it is root-relative and obviously specifies a + directory (ends in '/'), in which case /index.html will be added + --> + + <tab id="home" label="Home" dir=""/> + <tab id="help" label="Help" dir="help/"/> + <tab id="components" label="Component APIs" dir="components/"/> + <tab id="community" label="Getting Involved" dir="devel/"/> + +</tabs> diff --git a/src/documentation/content/xdocs/text-extraction.xml b/src/documentation/content/xdocs/text-extraction.xml new file mode 100644 index 0000000000..e93636aef7 --- /dev/null +++ b/src/documentation/content/xdocs/text-extraction.xml @@ -0,0 +1,186 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd"> + +<document> + <header> + <title>Apache POI™ - Text Extraction</title> + <authors> + <person id="NB" name="Nick Burch" email="nick@apache.org"/> + </authors> + </header> + + <body> + <section><title>Overview</title> + <p>For a number of years now, Apache POI has provided basic + text extraction for all the project supported file formats. In + addition, as well as the (plain) text, these provides access to + the metadata associated with a given file, such as title and + author.</p> + <p>For more advanced text extraction needs, including Rich Text + extraction (such as formatting and styling), along with XML and + HTML output, Apache POI works closely with + <a href="https://tika.apache.org/">Apache Tika</a> to deliver + POI-powered Tika Parsers for all the project supported file formats.</p> + <p>If you are after turn-key text extraction, including the latest + support, styles etc, you are strongly advised to make use of + <a href="https://tika.apache.org/">Apache Tika</a>, which builds + on top of POI to provide Text and Metadata extraction. If you wish + to have something very simple and stand-alone, or you wish to make + heavy modifications, then the POI provided text extractors documented + below might be a better fit for your needs.</p> + </section> + + <section><title>Common functionality</title> + <p>All of the POI text extractors extend from + <em>org.apache.poi.extractor.POITextExtractor</em>. This provides a common + method across all extractors, getText(). For many cases, the text + returned will be all you need. However, many extractors do provide + more targeted text extraction methods, so you may wish to use + these in some cases.</p> + <p>All POIFS / OLE 2 based text extractors also extend from + <em>org.apache.poi.extractor.POIOLE2TextExtractor</em>. This additionally + provides common methods to get at the <a href="hpfs/">HPFS + document metadata</a>.</p> + <p>All OOXML based text extractors also extend from + <em>org.apache.poi.POIOOXMLTextExtractor</em>. This additionally + provides common methods to get at the OOXML metadata.</p> + </section> + + <section><title>Text Extractor Factory</title> + <p>POI provides a common class to select the appropriate text extractor + for you, based on the supplied document's contents. + <em>ExtractorFactory</em> provides a + similar function to WorkbookFactory. You simply pass it an + InputStream, a File, a POIFSFileSystem or a OOXML Package. It + figures out the correct text extractor for you, and returns it.</p> + <p>For complete detection and text extractor auto-selection, users + are strongly encouraged to investigate + <a href="https://tika.apache.org/">Apache Tika</a>.</p> + </section> + + <section><title>Excel</title> + <p>For .xls files, there is + <em>org.apache.poi.hssf.extractor.ExcelExtractor</em>, which will + return text, optionally with formulas instead of their contents. + Similarly, for .xlsx files there is + <em>org.apache.poi.xssf.extractor.XSSFExcelExtractor</em>, which + provides the same functionality.</p> + <p>For those working in constrained memory footprints, there are + two more Excel text extractors available. For .xls files, it's + <em>org.apache.poi.hssf.extractor.EventBasedExcelExtractor</em>, + based on the streaming EventUserModel code, and will generally + deliver a lower memory footprint for extraction. However, it will + have problems correctly outputting more complex formulas, as it + works with records as they pass, and so doesn't have access to all + parts of complex and shared formulas. For .xlsx files the equivalent is + <em>org.apache.poi.xssf.extractor.XSSFEventBasedExcelExtractor</em>, + which is based on the XSSF SAX Event codebase.</p> + </section> + + <section><title>Word</title> + <p>For .doc files from Word 97 - Word 2003, in scratchpad there is + <em>org.apache.poi.hwpf.extractor.WordExtractor</em>, which will + return text for your document.</p> + <p>You can also extract simple textual content from + older Word 6 and Word 95 files, using the scratchpad class + <em>org.apache.poi.hwpf.extractor.Word6Extractor</em>.</p> + <p>For .docx files, the relevant class is + <em>org.apache.poi.xwpf.extractor.XWPFWordExtractor</em></p> + </section> + + <section><title>PowerPoint</title> + <p>For .ppt and .pptx files, there is common extractor + <em>org.apache.poi.sl.extractor.SlideShowExtractor.SlideShowExtractor</em>, which + will return text for your slideshow, optionally restricted to just + slides text or notes text. For .ppt you need to add the poi-scratchpad.jar + and for .pptx the poi-ooxml.jar and its dependencies are needed</p> + </section> + + <section><title>Publisher</title> + <p>For .pub files, in scratchpad there is + <em>org.apache.poi.hpbf.extractor.PublisherExtractor</em>, which + will return text for your file.</p> + </section> + + <section><title>Visio</title> + <p>For .vsd files, in scratchpad there is + <em>org.apache.poi.hdgf.extractor.VisioTextExtractor</em>, which + will return text for your file.</p> + </section> + + <section><title>Embedded Objects</title> + <p>Extractors already exist for Excel, Word, PowerPoint and Visio; + if one of these objects is embedded into a worksheet, the ExtractorFactory class can be used to recover an extractor for it. + </p> + <source> +FileInputStream fis = new FileInputStream(inputFile); +POIFSFileSystem fileSystem = new POIFSFileSystem(fis); +// Firstly, get an extractor for the Workbook +POIOLE2TextExtractor oleTextExtractor = + ExtractorFactory.createExtractor(fileSystem); +// Then a List of extractors for any embedded Excel, Word, PowerPoint +// or Visio objects embedded into it. +POITextExtractor[] embeddedExtractors = + ExtractorFactory.getEmbededDocsTextExtractors(oleTextExtractor); +for (POITextExtractor textExtractor : embeddedExtractors) { + // If the embedded object was an Excel spreadsheet. + if (textExtractor instanceof ExcelExtractor) { + ExcelExtractor excelExtractor = (ExcelExtractor) textExtractor; + System.out.println(excelExtractor.getText()); + } + // A Word Document + else if (textExtractor instanceof WordExtractor) { + WordExtractor wordExtractor = (WordExtractor) textExtractor; + String[] paragraphText = wordExtractor.getParagraphText(); + for (String paragraph : paragraphText) { + System.out.println(paragraph); + } + // Display the document's header and footer text + System.out.println("Footer text: " + wordExtractor.getFooterText()); + System.out.println("Header text: " + wordExtractor.getHeaderText()); + } + // PowerPoint Presentation. + else if (textExtractor instanceof PowerPointExtractor) { + PowerPointExtractor powerPointExtractor = + (PowerPointExtractor) textExtractor; + System.out.println("Text: " + powerPointExtractor.getText()); + System.out.println("Notes: " + powerPointExtractor.getNotes()); + } + // Visio Drawing + else if (textExtractor instanceof VisioTextExtractor) { + VisioTextExtractor visioTextExtractor = + (VisioTextExtractor) textExtractor; + System.out.println("Text: " + visioTextExtractor.getText()); + } +} + </source> + </section> + </body> + + <footer> + <legal> + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. + <br /> + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + </legal> + </footer> +</document> diff --git a/src/documentation/publish-poi-site.txt b/src/documentation/publish-poi-site.txt new file mode 100644 index 0000000000..d080b4c186 --- /dev/null +++ b/src/documentation/publish-poi-site.txt @@ -0,0 +1,75 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + + + ============================== + Publishing POI Web Site + ============================== + +The Apache POI web site is https://poi.apache.org/ + +The HTML and other files for the web site are stored in git at https://github.com/apache/poi/tree/asf-site +Committing files to the `publish` directory of this repo will automatically lead to the web site being updated. +There may be a small delay and you might need to force a refresh in your browser. + +The site is built from using the main POI git at https://github.com/apache/poi/tree/trunk + +Prerequisites +------------- + +You will need an up to date version of Apache Ant installed (Ant 1.10 works well). +You also need to install Apache Forrest. Forrest is no longer maintained but PJ has a fork with a few small changes. +This is at https://github.com/pjfanning/apache-forrest-0.9 + +You can use the last official Apache Forrest release but you may notice some diffs when you build the site and try to +publish it. https://forrest.apache.org/ + +You will need to create an environment variable called FORREST_HOME and set it to match the directory location +where you installed Apache Forrest. + +Building and Deploying the Site +------------------------------- + +It is recommended that you open a command prompt and set up Java 8 as your default. The web site build will fail +if you use a very recent Java version. + +In your local copy of the POI git (https://github.com/apache/poi/tree/trunk), run using Java 8: + +ant site + +If you use a newer version, you will get warnings and the output will have issues. + +After this completes, you can switch to the `asf-site` branch. + +The `ant site` command will have created a directory called `build/site` in your local POI git checkout. +You can copy the files in `build/site` to the `content` directory. +This `content` directory is where the files for the web site are stored +and only appears in the `asf-site` branch. + +A command like this might work. + +cp -R build/site/* content/ + +It is recommended that you use `git status` and `git diff` before committing the changes to asf-site. + +It is probably a good idea to check the site locally before committing the changes by opening the +content/index.html file in a browser. + +Once you are happy with the changes, you can commit them to the `asf-site` branch. + +It is probably a good idea to merge the changes from the `trunk` branch into the `asf-site` branch as well +but that won't affect the web site. diff --git a/src/documentation/release-guide.txt b/src/documentation/release-guide.txt new file mode 100644 index 0000000000..53cac95f08 --- /dev/null +++ b/src/documentation/release-guide.txt @@ -0,0 +1,367 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + + + ============================== + POI Release Guide + ============================== + + +(I) Prerequisites + + 1. You should read the <a href="https://www.apache.org/dev/release.html">Apache Release FAQ</a> + 2a. You must have shell access to people.apache.org; and you should + have key-based authentication set up + 1. Generate ssh key with ssh-keygen -t rsa -b 4096 + (e.g. <a href="http://www.linuxproblem.org/art_9.html">how to</a>.) + 2. Add contents of id_rsa.pub to SSH Key (authorized_keys) line on https://id.apache.org/ + 3. ssh -v username@people.apache.org + Verify authenticity of host: https://www.apache.org/dev/machines + 4. Only sftp access is necessary + 2b. You must be a member of the committee group + 3. Release manager must have their public key appended to the KEYS file checked in to SVN and the key published on one of the public key servers. + More info can be found here: <a href="https://www.apache.org/dev/release-signing.html">https://www.apache.org/dev/release-signing.html</a> + 4. You must have Java JDK 1.8 installed and active. + 5. You must have the following utilities installed on your local machine and available in your path: + * <a href="www.openssh.com">ssh</a> + * <a href="www.gnupg.org">gnupg</a> + * <a href="www.openssl.org">openssl</a> + For Windows users, install Cygwin and make sure you have the above utilities + 6a. The POI build system requires two components to perform a build + * <a href="https://ant.apache.org">Ant</a> 1.9.x or higher + * <a href="https://forrest.apache.org/">Forrest</a> 0.9. + Make sure ANT_HOME and FORREST_HOME are set. + + 6b. Ensure you can log in to https://repository.apache.org/ with your Apache + credentials, and that you can see the "Staging Repositories" area on + the left hand side. + + 6c. It's a good idea to check at https://ci-builds.apache.org/job/POI/ + that Jenkins is in a good state (i.e. most recent build passed + and is up to date with SVN). You probably also want to e-mail + the dev list with a note to say you're building a release. + + 7. Before building, you should run the "rat-check" build task, which + uses <a href="https://creadur.apache.org/rat/">Apache Rat</a> + to check the source tree for files lacking license headers. Files + without headers should be either fixed, or added to the exclude list + + 8. Check file permissions are correct in SVN. + There can be files in the SVN tree marked executable (have the + svn:executable property set), but which should not be. Checking them + out will cause the executable bit to be set for them on filesystems + which support it. The flag can be removed in batch using + +{code:sh} +svn pd 'svn:executable' $(find -name .svn -prune -or -type f ! -name \*.sh \ + -print0 | xargs -0 svn pg 'svn:executable' | cut -d ' ' -f 1) +{code} + + 9. Before building, ensure that the year in the NOTICE file is correct, + and review any new or updated dependencies to ensure that if they + required LICENSE or NOTICE updates then these were done. + + 10. Ensure that the changelog is up to date + + 11. Ensure that the KEYS files in the dist areas are up-to-date with the + latest ones in svn: + https://dist.apache.org/repos/dist/dev/poi/KEYS + https://dist.apache.org/repos/dist/release/poi/KEYS + Dist is a regular svn repo that can be checked out and committed to. + To upload to dist: https://www.apache.org/dev/release-distribution + +You can use these commands to do a sparse checkout of dist.apache.org. +There are so many files from all the Apache projects that it is not recommended to do a full checkout. + +{code:sh} +svn checkout https://dist.apache.org/repos/dist/ --depth immediates +svn update --set-depth infinity dist/dev/poi/ +svn update --set-depth infinity dist/release/poi/ +{code} + + +(II) Making release artifacts + Run these commands from a clean checkout of https://github.com/apache/poi/tree/trunk + + 1. Update the version number in these files and commit the changes to svn. + - build.xml (version.id) + - build.gradle + - osgi/pom.xml (version and poi.version) + + 2. Force a new build at https://ci-builds.apache.org/job/POI/job/POI-DSL-1.8 + - when build completes, download the built jars from + https://ci-builds.apache.org/job/POI/job/POI-DSL-1.8/lastSuccessfulBuild/artifact/ + + 3. To produce the source distributions, run + - ./gradlew srcDistZip + - ./gradlew srcDistTar + + 4. Copy the build/dist files to your svn checkout of dist.apache.org (dist/dev/poi/src) +{code:sh} +svn co https://dist.apache.org/repos/dist/release/poi /opt/poi-dist +cp build/dist/*.zip build/*.tgz /opt/poi-dist/dev/ +{code} + + 5. Generate SHA512 checksums + +{code:sh} +for f in *.zip *.tgz +do + sha512sum $f > $f.sha512 +done +{code} + + 6. Generate signatures + - The 1556F3A4 key in the command below is just an example, replace the value with your own key id + +{code:sh} +for f in *.zip *.tgz; do gpg --default-key 1556F3A4 -ab $f; done +{code} + + 7. Validate the checksums and signatures + +{code:sh} +find . -name "*.sha512" -type f -execdir sha512sum -c {} \; +find . -name "*.asc" -exec gpg --no-secmem-warning --verify {} \; +{code} + + 8. Deploy the source distribution files to the dev area of dist.apache.org + - Remove any old release candidates (only need to keep the latest one) + - svn commit the changes + +(III) Deploy Jars to Maven Staging + + 1. Ensure that there has been a build with the right svn commit and then download the jars + - https://ci-builds.apache.org/job/POI/job/POI-DSL-1.8 + - https://ci-builds.apache.org/job/POI/job/POI-DSL-1.8/lastSuccessfulBuild/artifact/ + + 2. Set up a `poi-prep` directory and copy all the jars other than the `test` jars into it. + - The artifacts in the archive.zip that you can download (see 1 above) are grouped in different dirs + - you can unzip the archive.zip and use the sample script from the `poi-prep` dir +This is an example script: +{code:sh} +export DOWNLOADED_JARS_DIR=/path/to/unzipped/archive +mv $DOWNLOADED_JARS_DIR/build/dist/maven/poi/*.jar . +mv $DOWNLOADED_JARS_DIR/build/dist/maven/poi-excelant/*.jar . +mv $DOWNLOADED_JARS_DIR/build/dist/maven/poi-examples/*.jar . +mv $DOWNLOADED_JARS_DIR/build/dist/maven/poi-ooxml/*.jar . +mv $DOWNLOADED_JARS_DIR/build/dist/maven/poi-ooxml-full/*.jar . +mv $DOWNLOADED_JARS_DIR/build/dist/maven/poi-ooxml-lite/*.jar . +mv $DOWNLOADED_JARS_DIR/build/dist/maven/poi-scratchpad/*.jar . +mv $DOWNLOADED_JARS_DIR/build/dist/maven/poi-javadoc/*.jar . +mv $DOWNLOADED_JARS_DIR/build/dist/maven/poi-examples-javadoc/*.jar . +mv $DOWNLOADED_JARS_DIR/build/dist/maven/poi-excelant-javadoc/*.jar . +mv $DOWNLOADED_JARS_DIR/build/dist/maven/poi-ooxml-javadoc/*.jar . +mv $DOWNLOADED_JARS_DIR/build/dist/maven/poi-scratchpad-javadoc/*.jar . +{code:sh} + + 3. We need to create pom files. Copy the ones from the last release into the directory with the jars. + - ensure the pom file names match the jar names (same version) + +This is an example script: +{code:sh} +export POI_RELEASE=5.3.0 +export POI_LAST_RELEASE=5.2.5 +curl https://repo1.maven.org/maven2/org/apache/poi/poi/$POI_LAST_RELEASE/poi-$POI_LAST_RELEASE.pom --output poi-$POI_RELEASE.pom +curl https://repo1.maven.org/maven2/org/apache/poi/poi-scratchpad/$POI_LAST_RELEASE/poi-scratchpad-$POI_LAST_RELEASE.pom --output poi-scratchpad-$POI_RELEASE.pom +curl https://repo1.maven.org/maven2/org/apache/poi/poi-ooxml/$POI_LAST_RELEASE/poi-ooxml-$POI_LAST_RELEASE.pom --output poi-ooxml-$POI_RELEASE.pom +curl https://repo1.maven.org/maven2/org/apache/poi/poi-ooxml-lite/$POI_LAST_RELEASE/poi-ooxml-lite-$POI_LAST_RELEASE.pom --output poi-ooxml-lite-$POI_RELEASE.pom +curl https://repo1.maven.org/maven2/org/apache/poi/poi-ooxml-full/$POI_LAST_RELEASE/poi-ooxml-full-$POI_LAST_RELEASE.pom --output poi-ooxml-full-$POI_RELEASE.pom +curl https://repo1.maven.org/maven2/org/apache/poi/poi-excelent/$POI_LAST_RELEASE/poi-excelent-$POI_LAST_RELEASE.pom --output poi-excelent-$POI_RELEASE.pom +curl https://repo1.maven.org/maven2/org/apache/poi/poi-examples/$POI_LAST_RELEASE/poi-examples-$POI_LAST_RELEASE.pom --output poi-examples-$POI_RELEASE.pom +{code:sh} + + 4. Fix up the version values in the poms + - I would recommend using an IDE and loading up the full `poi-prep` directory + - Replace all instances of the old version number with the new one + - if using 'Replace All', approve each change just in case the old version number might also match the version of a non-POI dependency + - update the dependency versions + - check if we need to remove or add dependencies + - great care must be taken at this stage because this step is very error prone + - feel free to generate the poms using the Gradle build instead but the Gradle build will get some aspects wrong + - the poi-ooxml-lite build is one aspect that messes up the generated poms + - you can hand modify the poms to fix issues (compare against the poms from the last release) + + 5. Generate signatures (no need for SHA checksums because they are automatically created later) + - The 1556F3A4 key in the command below is just an example, replace the value with your own key id + +{code:sh} +for f in *.jar *.pom; do gpg --default-key 1556F3A4 -ab $f; done +{code} + + 6. Create bundle jars + +{code:sh} +jar -cvf poi-bundle.jar poi-5*.pom poi-5*.pom.asc poi-5*.jar poi-5*.jar.asc +jar -cvf poi-ooxml-bundle.jar poi-ooxml-5*.pom poi-ooxml-5*.pom.asc poi-ooxml-5*.jar poi-ooxml-5*.jar.asc +jar -cvf poi-ooxml-full-bundle.jar poi-ooxml-full*.pom poi-ooxml-full*.pom.asc poi-ooxml-full*.jar poi-ooxml-full*.jar.asc +jar -cvf poi-ooxml-lite-bundle.jar poi-ooxml-lite*.pom poi-ooxml-lite*.pom.asc poi-ooxml-lite*.jar poi-ooxml-lite*.jar.asc +jar -cvf poi-scratchpad-bundle.jar poi-scratchpad*.pom poi-scratchpad*.pom.asc poi-scratchpad*.jar poi-scratchpad*.jar.asc +jar -cvf poi-excelant-bundle.jar poi-excelant*.pom poi-excelant*.pom.asc poi-excelant*.jar poi-excelant*.jar.asc +jar -cvf poi-examples-bundle.jar poi-examples*.pom poi-examples*.pom.asc poi-examples*.jar poi-examples*.jar.asc +{code} + + 7. Deploy bundle jars to repository.apache.org + - Login with your Apache username and password + - If you have never deployed a bundle artifact then read + https://help.sonatype.com/repomanager2/staging-releases/artifact-bundles + - deploy each of the 7 bundle jars - watch out for exceptions when loading them + +(IV) Calling the vote: + + 1. The release manager should call the vote + 2. Include the URL of the release artifacts + 3. Include the time for the vote to run (3 day minimum, can be longer) + 4. Provide guidance on what needs to be checked + 5. Complete a tally, and send a result once the time has passed + +(V) After the vote: + +Deploy the artifacts from the staging area (https://dist.apache.org/repos/dist/dev/poi/) +to the release area of the dist repo: + https://dist.apache.org/repos/dist/release/poi/release/ + +And remove any old releases from the staging area if they exist (should have been deleted by Step 11) +Staging area: https://dist.apache.org/repos/dist/dev/poi/ + +{code:sh} +svn rm https://dist.apache.org/repos/dist/dev/poi/FIXME3.16-RC1 -m "remove old release from staging area" +{code:sh} + +You should get an email from the Apache Reporter Service (no-reply@reporter.apache.org) +at your Apache email address. +The email instructions will ask you to log on to https://reporter.apache.org/addrelease.html?poi +and add your release data (version and date) to the database. + +Log into https://repository.apache.org/ and go to the "Staging Repositories" area. +Find the "orgapachepoi" entry, check it has the right content, then Close the repository +(it was probably already closed by release-prep3). +Select all artifacts and Release (and Automatically Drop) them. +Refresh to verify that the artifacts are no longer in the Staging Repositories area. + +2. Wait for the distributions to appear on your favourite mirror (anywhere from 3-24 hours) + https://www.apache.org/dyn/closer.lua/poi/dev/ + +3. Wait for the maven artifacts to appear on Maven Central, and ensure they work: + Maven Central: https://search.maven.org/#search|ga|1|g%3A%22org.apache.poi%22 + +Create a simple project and make sure the release artifacts are accessible +by maven: + +{code:sh} +mvn archetype:create -DgroupId=org.apache.poi.scratchpad -DartifactId=maven-test +cd maven-test +{code} + +edit pom.xml and add the release artifacts to the project dependencies: + +{code:xml} + <dependency> + <groupId>org.apache.poi</groupId> + <artifactId>poi-ooxml</artifactId> + <version>4.0.0</version> + </dependency> + <dependency> + <groupId>org.apache.poi</groupId> + <artifactId>poi-scratchpad</artifactId> + <version>4.0.0</version> + </dependency> +{code} + +edit src/main/java/Test.java and add this: + +{code:java} +import org.apache.poi.ss.usermodel.Workbook; +import org.apache.poi.ss.usermodel.WorkbookFactory; + +public class Test {} +{code} + +{code:sh} +mvn compile +{code} + +You should see [INFO] BUILD SUCCESSFUL in the end, which tells you that +the jars could be downloaded fine. + +4. Edit the website homepage and list the new release there. + * poi/site/src/documentation/content/xdocs/index.xml + * poi/site/src/documentation/content/xdocs/changes.xml + remove older releases. + +5. Edit the website download page, and list the new release there. This should + reference the checksums, so take care when updating + * poi/site/src/documentation/content/xdocs/download.xml +{code:sh} +# the following generates a download-snipplet.xml to be copy&pasted in the download.xml +ant update-download -Dversion.id="3.15" -Dreltype=dev -Drel_date="02 July 2016" -Dfile_date="20160702" +{code} + And copy the contents from the output, download-snipplet.xml, to the appropriate section + in poi/site/src/documentation/content/xdocs/download.xml. + + Additionally there are some further files to be updated ... check the results and commit them: +{code:sh} +# the following updates various references from the previous release to the current release +ant release-finish -Dfile_date="20160702" +{code} + + +6. Build site using a recent version of Java 1.8 + Commit the site changes to svn, and publish live + +7. Copy the build javadocs to a stable location under /apidocs/{ver}/ + - For a major release, create a new subfolder to hold the javadocs for + this release family, eg 4.1 for 4.1.x + - For a minor release, replace the existing subfolder for the release + family, eg 4.1.2 uses 4.1 replacing the previous 4.1.1 + +8. Don't forget to upload the latest version of the site and javadocs + +9. Send announcements: +From: your @apache.org e-mail address +To: user@poi.apache.org, dev@poi.apache.org, general@poi.apache.org, and announce@apache.org +Subject: [ANNOUNCE] Apache POI FIXME3.16 released +Body: +""" +The Apache POI PMC is pleased to announce the release of Apache POI FIXME3.16. + +Apache POI is a Java library for reading and writing Microsoft Office files. + +For detailed changes in this release, refer to the release notes [1] and the changelog [2]. + +Thank you to all our contributors for making this release possible. + +On behalf of the Apache POI PMC, +Your Name + +[1] Release notes: https://www.apache.org/dyn/closer.lua/poi/dev/RELEASE-NOTES-FIXME3.16.txt +[2] Changelog: https://poi.apache.org/changes.html#FIXME3.16 +""" + +Note, announcements should be sent from your @apache.org e-mail address. + +10. In Bugzilla, add a new version and the next "...-dev" version. Also close the n-2 -dev version to new bugs. + +11. Add the version to the DOAP file too + https://github.com/apache/poi/tree/trunk/doap_POI.rdf + +12. Delete directory that held RC. + +e.g. +{code:sh} +svn delete -m "delete empty RC directory for 4.0.0" https://dist.apache.org/repos/dist/dev/poi/4.0.0-RC1 +{code} diff --git a/src/documentation/resources/images/ApacheConEu08.jpg b/src/documentation/resources/images/ApacheConEu08.jpg Binary files differnew file mode 100644 index 0000000000..7c330579b6 --- /dev/null +++ b/src/documentation/resources/images/ApacheConEu08.jpg diff --git a/src/documentation/resources/images/BlockClassDiagram.gif b/src/documentation/resources/images/BlockClassDiagram.gif Binary files differnew file mode 100644 index 0000000000..2433adc92c --- /dev/null +++ b/src/documentation/resources/images/BlockClassDiagram.gif diff --git a/src/documentation/resources/images/POIFSAddDocument.gif b/src/documentation/resources/images/POIFSAddDocument.gif Binary files differnew file mode 100644 index 0000000000..d9b2002824 --- /dev/null +++ b/src/documentation/resources/images/POIFSAddDocument.gif diff --git a/src/documentation/resources/images/POIFSClassDiagram.gif b/src/documentation/resources/images/POIFSClassDiagram.gif Binary files differnew file mode 100644 index 0000000000..c4ddfff228 --- /dev/null +++ b/src/documentation/resources/images/POIFSClassDiagram.gif diff --git a/src/documentation/resources/images/POIFSInitialization.gif b/src/documentation/resources/images/POIFSInitialization.gif Binary files differnew file mode 100644 index 0000000000..d23bf29226 --- /dev/null +++ b/src/documentation/resources/images/POIFSInitialization.gif diff --git a/src/documentation/resources/images/POIFSLifeCycle.gif b/src/documentation/resources/images/POIFSLifeCycle.gif Binary files differnew file mode 100644 index 0000000000..3626dcc1b9 --- /dev/null +++ b/src/documentation/resources/images/POIFSLifeCycle.gif diff --git a/src/documentation/resources/images/POIFSPropertyTablePreWrite.gif b/src/documentation/resources/images/POIFSPropertyTablePreWrite.gif Binary files differnew file mode 100644 index 0000000000..801c1d8a14 --- /dev/null +++ b/src/documentation/resources/images/POIFSPropertyTablePreWrite.gif diff --git a/src/documentation/resources/images/POIFSRootPropertyPreWrite.gif b/src/documentation/resources/images/POIFSRootPropertyPreWrite.gif Binary files differnew file mode 100644 index 0000000000..3927bcce76 --- /dev/null +++ b/src/documentation/resources/images/POIFSRootPropertyPreWrite.gif diff --git a/src/documentation/resources/images/POIFSWriteArchive.gif b/src/documentation/resources/images/POIFSWriteArchive.gif Binary files differnew file mode 100644 index 0000000000..eac7fd7a2e --- /dev/null +++ b/src/documentation/resources/images/POIFSWriteArchive.gif diff --git a/src/documentation/resources/images/POIFSWriteFilesystem.gif b/src/documentation/resources/images/POIFSWriteFilesystem.gif Binary files differnew file mode 100644 index 0000000000..d5011a0f72 --- /dev/null +++ b/src/documentation/resources/images/POIFSWriteFilesystem.gif diff --git a/src/documentation/resources/images/PropertySet.jpg b/src/documentation/resources/images/PropertySet.jpg Binary files differnew file mode 100644 index 0000000000..c0d1461020 --- /dev/null +++ b/src/documentation/resources/images/PropertySet.jpg diff --git a/src/documentation/resources/images/PropertyTableClassDiagram.gif b/src/documentation/resources/images/PropertyTableClassDiagram.gif Binary files differnew file mode 100644 index 0000000000..8a72c51ee5 --- /dev/null +++ b/src/documentation/resources/images/PropertyTableClassDiagram.gif diff --git a/src/documentation/resources/images/built-with-forrest-button.png b/src/documentation/resources/images/built-with-forrest-button.png Binary files differnew file mode 100644 index 0000000000..4a787abe4d --- /dev/null +++ b/src/documentation/resources/images/built-with-forrest-button.png diff --git a/src/documentation/resources/images/businessplan.jpg b/src/documentation/resources/images/businessplan.jpg Binary files differnew file mode 100644 index 0000000000..9bfaf4c7b2 --- /dev/null +++ b/src/documentation/resources/images/businessplan.jpg diff --git a/src/documentation/resources/images/calculatePayment.jpg b/src/documentation/resources/images/calculatePayment.jpg Binary files differnew file mode 100644 index 0000000000..221433e93d --- /dev/null +++ b/src/documentation/resources/images/calculatePayment.jpg diff --git a/src/documentation/resources/images/calendar.jpg b/src/documentation/resources/images/calendar.jpg Binary files differnew file mode 100644 index 0000000000..4f11878290 --- /dev/null +++ b/src/documentation/resources/images/calendar.jpg diff --git a/src/documentation/resources/images/hslf_shapes.gif b/src/documentation/resources/images/hslf_shapes.gif Binary files differnew file mode 100644 index 0000000000..ee5eec9f15 --- /dev/null +++ b/src/documentation/resources/images/hslf_shapes.gif diff --git a/src/documentation/resources/images/loancalc.jpg b/src/documentation/resources/images/loancalc.jpg Binary files differnew file mode 100644 index 0000000000..fdc62e82dd --- /dev/null +++ b/src/documentation/resources/images/loancalc.jpg diff --git a/src/documentation/resources/images/logoAdria1.png b/src/documentation/resources/images/logoAdria1.png Binary files differnew file mode 100644 index 0000000000..16a6f113af --- /dev/null +++ b/src/documentation/resources/images/logoAdria1.png diff --git a/src/documentation/resources/images/logoAdria2.png b/src/documentation/resources/images/logoAdria2.png Binary files differnew file mode 100644 index 0000000000..d1ad50bc58 --- /dev/null +++ b/src/documentation/resources/images/logoAdria2.png diff --git a/src/documentation/resources/images/logoAdria3.png b/src/documentation/resources/images/logoAdria3.png Binary files differnew file mode 100644 index 0000000000..4247b97bfe --- /dev/null +++ b/src/documentation/resources/images/logoAdria3.png diff --git a/src/documentation/resources/images/logoAndrewClements.png b/src/documentation/resources/images/logoAndrewClements.png Binary files differnew file mode 100644 index 0000000000..0bc88e4f0a --- /dev/null +++ b/src/documentation/resources/images/logoAndrewClements.png diff --git a/src/documentation/resources/images/logoAndrewClements2.png b/src/documentation/resources/images/logoAndrewClements2.png Binary files differnew file mode 100644 index 0000000000..eaccaf0d9e --- /dev/null +++ b/src/documentation/resources/images/logoAndrewClements2.png diff --git a/src/documentation/resources/images/logoDanielFernandez.png b/src/documentation/resources/images/logoDanielFernandez.png Binary files differnew file mode 100644 index 0000000000..1ed7ff9268 --- /dev/null +++ b/src/documentation/resources/images/logoDanielFernandez.png diff --git a/src/documentation/resources/images/logoGlenStampoutlzis.png b/src/documentation/resources/images/logoGlenStampoutlzis.png Binary files differnew file mode 100644 index 0000000000..f7707c7f27 --- /dev/null +++ b/src/documentation/resources/images/logoGlenStampoutlzis.png diff --git a/src/documentation/resources/images/logoGustafsson1.png b/src/documentation/resources/images/logoGustafsson1.png Binary files differnew file mode 100644 index 0000000000..ff13834ff5 --- /dev/null +++ b/src/documentation/resources/images/logoGustafsson1.png diff --git a/src/documentation/resources/images/logoGustafsson2.png b/src/documentation/resources/images/logoGustafsson2.png Binary files differnew file mode 100644 index 0000000000..a3f5c86d24 --- /dev/null +++ b/src/documentation/resources/images/logoGustafsson2.png diff --git a/src/documentation/resources/images/logoJanssen1.png b/src/documentation/resources/images/logoJanssen1.png Binary files differnew file mode 100644 index 0000000000..e02fe52f47 --- /dev/null +++ b/src/documentation/resources/images/logoJanssen1.png diff --git a/src/documentation/resources/images/logoJanssen2.png b/src/documentation/resources/images/logoJanssen2.png Binary files differnew file mode 100644 index 0000000000..c7b406ed22 --- /dev/null +++ b/src/documentation/resources/images/logoJanssen2.png diff --git a/src/documentation/resources/images/logoKarmokar1.png b/src/documentation/resources/images/logoKarmokar1.png Binary files differnew file mode 100644 index 0000000000..232b22e8e5 --- /dev/null +++ b/src/documentation/resources/images/logoKarmokar1.png diff --git a/src/documentation/resources/images/logoKarmokar1s.png b/src/documentation/resources/images/logoKarmokar1s.png Binary files differnew file mode 100644 index 0000000000..41742031ce --- /dev/null +++ b/src/documentation/resources/images/logoKarmokar1s.png diff --git a/src/documentation/resources/images/logoKarmokar2.png b/src/documentation/resources/images/logoKarmokar2.png Binary files differnew file mode 100644 index 0000000000..7168b70e98 --- /dev/null +++ b/src/documentation/resources/images/logoKarmokar2.png diff --git a/src/documentation/resources/images/logoKarmokar2s.png b/src/documentation/resources/images/logoKarmokar2s.png Binary files differnew file mode 100644 index 0000000000..93977b087d --- /dev/null +++ b/src/documentation/resources/images/logoKarmokar2s.png diff --git a/src/documentation/resources/images/logoKarmokar3.png b/src/documentation/resources/images/logoKarmokar3.png Binary files differnew file mode 100644 index 0000000000..ef8b14668a --- /dev/null +++ b/src/documentation/resources/images/logoKarmokar3.png diff --git a/src/documentation/resources/images/logoKarmokar3s.png b/src/documentation/resources/images/logoKarmokar3s.png Binary files differnew file mode 100644 index 0000000000..e9e86bdfa5 --- /dev/null +++ b/src/documentation/resources/images/logoKarmokar3s.png diff --git a/src/documentation/resources/images/logoKarmokar4.png b/src/documentation/resources/images/logoKarmokar4.png Binary files differnew file mode 100644 index 0000000000..90a915a3a9 --- /dev/null +++ b/src/documentation/resources/images/logoKarmokar4.png diff --git a/src/documentation/resources/images/logoKarmokar4s.png b/src/documentation/resources/images/logoKarmokar4s.png Binary files differnew file mode 100644 index 0000000000..33391cd963 --- /dev/null +++ b/src/documentation/resources/images/logoKarmokar4s.png diff --git a/src/documentation/resources/images/logoKarmokar5.png b/src/documentation/resources/images/logoKarmokar5.png Binary files differnew file mode 100644 index 0000000000..e2d1f3f858 --- /dev/null +++ b/src/documentation/resources/images/logoKarmokar5.png diff --git a/src/documentation/resources/images/logoKarmokar5s.png b/src/documentation/resources/images/logoKarmokar5s.png Binary files differnew file mode 100644 index 0000000000..5ea300d16f --- /dev/null +++ b/src/documentation/resources/images/logoKarmokar5s.png diff --git a/src/documentation/resources/images/logoKarmokar6.png b/src/documentation/resources/images/logoKarmokar6.png Binary files differnew file mode 100644 index 0000000000..0407c35823 --- /dev/null +++ b/src/documentation/resources/images/logoKarmokar6.png diff --git a/src/documentation/resources/images/logoKarmokar6s.png b/src/documentation/resources/images/logoKarmokar6s.png Binary files differnew file mode 100644 index 0000000000..b13fb1890d --- /dev/null +++ b/src/documentation/resources/images/logoKarmokar6s.png diff --git a/src/documentation/resources/images/logoLoicLefevre.png b/src/documentation/resources/images/logoLoicLefevre.png Binary files differnew file mode 100644 index 0000000000..520840dff7 --- /dev/null +++ b/src/documentation/resources/images/logoLoicLefevre.png diff --git a/src/documentation/resources/images/logoLoicLefevre2.png b/src/documentation/resources/images/logoLoicLefevre2.png Binary files differnew file mode 100644 index 0000000000..ce8efa3113 --- /dev/null +++ b/src/documentation/resources/images/logoLoicLefevre2.png diff --git a/src/documentation/resources/images/logoMichaelMosmann.png b/src/documentation/resources/images/logoMichaelMosmann.png Binary files differnew file mode 100644 index 0000000000..08424c7bf8 --- /dev/null +++ b/src/documentation/resources/images/logoMichaelMosmann.png diff --git a/src/documentation/resources/images/logoRaPiGmbH1.png b/src/documentation/resources/images/logoRaPiGmbH1.png Binary files differnew file mode 100644 index 0000000000..3bef8bb6e9 --- /dev/null +++ b/src/documentation/resources/images/logoRaPiGmbH1.png diff --git a/src/documentation/resources/images/logoRaPiGmbH10.png b/src/documentation/resources/images/logoRaPiGmbH10.png Binary files differnew file mode 100644 index 0000000000..46fd998659 --- /dev/null +++ b/src/documentation/resources/images/logoRaPiGmbH10.png diff --git a/src/documentation/resources/images/logoRaPiGmbH11.png b/src/documentation/resources/images/logoRaPiGmbH11.png Binary files differnew file mode 100644 index 0000000000..c92d32688e --- /dev/null +++ b/src/documentation/resources/images/logoRaPiGmbH11.png diff --git a/src/documentation/resources/images/logoRaPiGmbH12.png b/src/documentation/resources/images/logoRaPiGmbH12.png Binary files differnew file mode 100644 index 0000000000..c006c7c562 --- /dev/null +++ b/src/documentation/resources/images/logoRaPiGmbH12.png diff --git a/src/documentation/resources/images/logoRaPiGmbH2.png b/src/documentation/resources/images/logoRaPiGmbH2.png Binary files differnew file mode 100644 index 0000000000..d842217557 --- /dev/null +++ b/src/documentation/resources/images/logoRaPiGmbH2.png diff --git a/src/documentation/resources/images/logoRaPiGmbH5.png b/src/documentation/resources/images/logoRaPiGmbH5.png Binary files differnew file mode 100644 index 0000000000..f96ef9ef91 --- /dev/null +++ b/src/documentation/resources/images/logoRaPiGmbH5.png diff --git a/src/documentation/resources/images/logoRaPiGmbH6.png b/src/documentation/resources/images/logoRaPiGmbH6.png Binary files differnew file mode 100644 index 0000000000..53ee5e9eab --- /dev/null +++ b/src/documentation/resources/images/logoRaPiGmbH6.png diff --git a/src/documentation/resources/images/logoRaPiGmbH7.png b/src/documentation/resources/images/logoRaPiGmbH7.png Binary files differnew file mode 100644 index 0000000000..498499d9df --- /dev/null +++ b/src/documentation/resources/images/logoRaPiGmbH7.png diff --git a/src/documentation/resources/images/logoRaPiGmbH8.png b/src/documentation/resources/images/logoRaPiGmbH8.png Binary files differnew file mode 100644 index 0000000000..7df1b28d6e --- /dev/null +++ b/src/documentation/resources/images/logoRaPiGmbH8.png diff --git a/src/documentation/resources/images/logoRaPiGmbH9.png b/src/documentation/resources/images/logoRaPiGmbH9.png Binary files differnew file mode 100644 index 0000000000..7df1b28d6e --- /dev/null +++ b/src/documentation/resources/images/logoRaPiGmbH9.png diff --git a/src/documentation/resources/images/logoRandyStanard01.png b/src/documentation/resources/images/logoRandyStanard01.png Binary files differnew file mode 100644 index 0000000000..f236c10a6e --- /dev/null +++ b/src/documentation/resources/images/logoRandyStanard01.png diff --git a/src/documentation/resources/images/logoRandyStanard02.png b/src/documentation/resources/images/logoRandyStanard02.png Binary files differnew file mode 100644 index 0000000000..d20c8bacc7 --- /dev/null +++ b/src/documentation/resources/images/logoRandyStanard02.png diff --git a/src/documentation/resources/images/logoRandyStanard03.png b/src/documentation/resources/images/logoRandyStanard03.png Binary files differnew file mode 100644 index 0000000000..45850fa744 --- /dev/null +++ b/src/documentation/resources/images/logoRandyStanard03.png diff --git a/src/documentation/resources/images/logoRandyStanard04.png b/src/documentation/resources/images/logoRandyStanard04.png Binary files differnew file mode 100644 index 0000000000..da62011014 --- /dev/null +++ b/src/documentation/resources/images/logoRandyStanard04.png diff --git a/src/documentation/resources/images/logoRandyStanard05.png b/src/documentation/resources/images/logoRandyStanard05.png Binary files differnew file mode 100644 index 0000000000..0b63989f94 --- /dev/null +++ b/src/documentation/resources/images/logoRandyStanard05.png diff --git a/src/documentation/resources/images/logoRandyStanard06.png b/src/documentation/resources/images/logoRandyStanard06.png Binary files differnew file mode 100644 index 0000000000..9474220a1c --- /dev/null +++ b/src/documentation/resources/images/logoRandyStanard06.png diff --git a/src/documentation/resources/images/logoRandyStanard07.png b/src/documentation/resources/images/logoRandyStanard07.png Binary files differnew file mode 100644 index 0000000000..c7b6aca5bc --- /dev/null +++ b/src/documentation/resources/images/logoRandyStanard07.png diff --git a/src/documentation/resources/images/logoRandyStanard08.png b/src/documentation/resources/images/logoRandyStanard08.png Binary files differnew file mode 100644 index 0000000000..83d5bf9ca9 --- /dev/null +++ b/src/documentation/resources/images/logoRandyStanard08.png diff --git a/src/documentation/resources/images/logoRussellBeattie1.png b/src/documentation/resources/images/logoRussellBeattie1.png Binary files differnew file mode 100644 index 0000000000..228d13c4e3 --- /dev/null +++ b/src/documentation/resources/images/logoRussellBeattie1.png diff --git a/src/documentation/resources/images/logoRussellBeattie2.png b/src/documentation/resources/images/logoRussellBeattie2.png Binary files differnew file mode 100644 index 0000000000..052209ec6f --- /dev/null +++ b/src/documentation/resources/images/logoRussellBeattie2.png diff --git a/src/documentation/resources/images/logoRussellBeattie3.png b/src/documentation/resources/images/logoRussellBeattie3.png Binary files differnew file mode 100644 index 0000000000..9a4e98c2da --- /dev/null +++ b/src/documentation/resources/images/logoRussellBeattie3.png diff --git a/src/documentation/resources/images/logoRussellBeattie4.png b/src/documentation/resources/images/logoRussellBeattie4.png Binary files differnew file mode 100644 index 0000000000..5a6b0fb334 --- /dev/null +++ b/src/documentation/resources/images/logoRussellBeattie4.png diff --git a/src/documentation/resources/images/logoRussellBeattie5.png b/src/documentation/resources/images/logoRussellBeattie5.png Binary files differnew file mode 100644 index 0000000000..71ef63c6fc --- /dev/null +++ b/src/documentation/resources/images/logoRussellBeattie5.png diff --git a/src/documentation/resources/images/logoWendyWise.png b/src/documentation/resources/images/logoWendyWise.png Binary files differnew file mode 100644 index 0000000000..43f7569cd5 --- /dev/null +++ b/src/documentation/resources/images/logoWendyWise.png diff --git a/src/documentation/resources/images/logoWendyWise2.png b/src/documentation/resources/images/logoWendyWise2.png Binary files differnew file mode 100644 index 0000000000..8ab6eaa07a --- /dev/null +++ b/src/documentation/resources/images/logoWendyWise2.png diff --git a/src/documentation/resources/images/old-project-logo.gif b/src/documentation/resources/images/old-project-logo.gif Binary files differnew file mode 100644 index 0000000000..b9c2ee1391 --- /dev/null +++ b/src/documentation/resources/images/old-project-logo.gif diff --git a/src/documentation/resources/images/pb-poi.cdr b/src/documentation/resources/images/pb-poi.cdr Binary files differnew file mode 100644 index 0000000000..ad5ce44c25 --- /dev/null +++ b/src/documentation/resources/images/pb-poi.cdr diff --git a/src/documentation/resources/images/poi-logo.png b/src/documentation/resources/images/poi-logo.png Binary files differnew file mode 100644 index 0000000000..73c02a5603 --- /dev/null +++ b/src/documentation/resources/images/poi-logo.png diff --git a/src/documentation/resources/images/project-header.svg b/src/documentation/resources/images/project-header.svg new file mode 100644 index 0000000000..b5d65e8cd9 --- /dev/null +++ b/src/documentation/resources/images/project-header.svg @@ -0,0 +1,1108 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="486.55063" + height="140" + viewBox="0 0 128.73318 37.041668" + version="1.1" + id="svg8" + inkscape:version="0.92.3 (2405546, 2018-03-11)" + sodipodi:docname="project-header.svg"> + <defs + id="defs2"> + <linearGradient + inkscape:collect="always" + id="linearGradient2004"> + <stop + style="stop-color:#00007f;stop-opacity:1" + offset="0" + id="stop2000" /> + <stop + style="stop-color:#5993dc;stop-opacity:1" + offset="1" + id="stop2002" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient2004" + id="linearGradient2006" + x1="101.42879" + y1="296.19818" + x2="101.42879" + y2="272.8121" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.88144753,0,0,0.88144753,0,35.210091)" /> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter1940" + x="-0.36" + width="1.72" + y="-0.36" + height="1.72"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406177" + id="feGaussianBlur1942" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248" + x="-0.18" + width="1.36" + y="-0.18" + height="1.36"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.032203086" + id="feGaussianBlur2250" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2260" + x="-0.06" + width="1.12" + y="-0.06" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.044266516" + id="feGaussianBlur2262" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276" + x="-0.06" + width="1.12" + y="-0.06" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2278" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2292" + x="-0.06" + width="1.12" + y="-0.06" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.0242213" + id="feGaussianBlur2294" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2308" + x="-0.06" + width="1.12" + y="-0.06" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.012210993" + id="feGaussianBlur2310" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2324" + x="-0.06" + width="1.12" + y="-0.06" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.016787887" + id="feGaussianBlur2326" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2340" + x="-0.18" + width="1.36" + y="-0.18" + height="1.36"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.05036366" + id="feGaussianBlur2342" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2260-7" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.044266516" + id="feGaussianBlur2262-6" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2278-0" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2278-0-9" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2278-0-9-4" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5-5" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2278-0-9-4-9" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5-5-6" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2278-0-9-4-9-9" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5-5-2" + x="-0.18" + width="1.36" + y="-0.18" + height="1.36"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.10523737" + id="feGaussianBlur2278-0-9-4-9-4" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5-5-7" + x="-0.18" + width="1.36" + y="-0.18" + height="1.36"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.10523737" + id="feGaussianBlur2278-0-9-4-9-5" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5-5-8" + x="-0.18" + width="1.36" + y="-0.18" + height="1.36"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.10523737" + id="feGaussianBlur2278-0-9-4-9-1" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5-5-9" + x="-0.36" + width="1.72" + y="-0.36" + height="1.72"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.21047475" + id="feGaussianBlur2278-0-9-4-9-3" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2531" + x="-0.06" + width="1.12" + y="-0.06" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2533" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2531-0" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2533-5" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2531-0-1" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2533-5-0" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2531-0-5" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2533-5-06" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2531-0-5-6" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2533-5-06-2" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2276-3-0-5-5-6-8" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2278-0-9-4-9-9-6" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2531-0-8" + x="-0.059999999" + width="1.12" + y="-0.059999999" + height="1.12"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.035079125" + id="feGaussianBlur2533-5-4" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2" + x="-0.18000001" + width="1.36" + y="-0.18000001" + height="1.36"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.032203086" + id="feGaussianBlur2250-4" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6" + x="-0.36" + width="1.72" + y="-0.36" + height="1.72"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-1" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-0" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-4" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-03" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-19" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-6" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-3" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-8" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-5" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-66" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-0" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-04" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-2" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-67" /> + </filter> + <filter + inkscape:collect="always" + style="color-interpolation-filters:sRGB" + id="filter2248-2-6-9-1-6" + x="-0.36000001" + width="1.72" + y="-0.36000001" + height="1.72"> + <feGaussianBlur + inkscape:collect="always" + stdDeviation="0.064406173" + id="feGaussianBlur2250-4-2-0-3-9" /> + </filter> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="5.6" + inkscape:cx="203.54441" + inkscape:cy="55.534135" + inkscape:document-units="mm" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:window-width="3770" + inkscape:window-height="2096" + inkscape:window-x="70" + inkscape:window-y="27" + inkscape:window-maximized="1" + units="px" + showguides="true" + inkscape:guide-bbox="true" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" /> + <metadata + id="metadata5"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(0,-259.95833)"> + <path + style="display:inline;fill:url(#linearGradient2006);fill-opacity:1;stroke-width:0.20389491" + d="m 30.8636,290.15182 v -6.83048 h 17.134825 17.134827 l -0.05863,-1.88602 -0.05863,-1.88603 -17.082662,-0.0521 -17.082659,-0.0521 0.05743,-2.39462 0.05743,-2.39458 h 17.53496 c 17.398544,0 17.542181,0.003 18.462848,0.42933 1.288934,0.59637 2.256419,1.4999 2.849566,2.66116 0.464354,0.9091 0.503744,1.20566 0.496786,3.73998 -0.0081,2.98535 -0.164305,3.6106 -1.211479,4.85255 -0.311956,0.36996 -1.036939,0.92047 -1.611078,1.22335 l -1.04389,0.55068 -15.037251,0.0561 -15.037248,0.0561 v 4.37867 4.37867 h -2.752593 -2.752581 z m 49.402346,6.53512 c -1.680457,-0.52523 -3.321164,-2.09528 -3.730904,-3.5702 -0.112804,-0.40608 -0.201098,-3.67164 -0.201739,-7.46154 l -6.89e-4,-6.73949 0.535936,-1.07545 c 0.593512,-1.19105 2.037214,-2.47148 3.284185,-2.9128 0.613366,-0.2171 3.85938,-0.27165 16.161589,-0.27165 15.191006,0 15.406186,0.006 16.311606,0.42651 1.25674,0.58422 2.14731,1.37736 2.80755,2.50048 l 0.55671,1.566 v 6.61928 c 0,7.07569 -0.01,7.25717 -0.45024,8.07999 -0.63745,1.19173 -2.16277,2.46529 -3.3886,2.82934 -1.42819,0.42412 -30.530637,0.43282 -31.884957,0.01 z m 30.218624,-10.81692 v -6.32073 l -14.323612,-0.0524 -14.323627,-0.0524 v 6.28814 c 0,3.45847 0.06179,6.34993 0.137301,6.42543 0.07552,0.0755 6.521154,0.11383 14.323634,0.085 l 14.186304,-0.0523 z m 12.74344,-0.10194 v -11.21422 h 2.75258 2.7526 v 11.21422 11.21424 h -2.7526 -2.75258 z" + id="path882" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccccccsccsccccccccccccccscscccsccccccccsccccccccccccc" + inkscape:label="POI" /> + <g + id="g1998" + transform="matrix(0.03684468,0,0,0.03684468,55.411645,259.03345)" + inkscape:label="Apache_logo"> + <path + style="fill:#6d6e71;stroke-width:0.26458332" + inkscape:connector-curvature="0" + id="path1216" + d="m 796.58994,92.598947 c 4.0482,4.04812 6.059,8.916463 6.059,14.605003 0,5.68854 -2.0108,10.55687 -6.059,14.65792 -4.0481,4.07458 -8.9429,6.11187 -14.7108,6.11187 -5.7679,0 -10.6362,-2.01083 -14.6579,-6.05896 -3.9952,-4.04812 -6.006,-8.91646 -6.006,-14.605 0,-5.68854 2.0108,-10.556873 6.0589,-14.657913 4.0481,-4.07459 8.9165,-6.11188 14.6579,-6.11188 5.715,0 10.6098,2.01083 14.6579,6.05896 z m -1.7462,27.543123 c 3.519,-3.59833 5.2917,-7.88458 5.2917,-12.8852 0,-5.00063 -1.7463,-9.260423 -5.2388,-12.832303 -3.4925,-3.54541 -7.7787,-5.31812 -12.8587,-5.31812 -5.08,0 -9.3663,1.77271 -12.8852,5.34458 -3.519,3.57188 -5.2653,7.858133 -5.2653,12.885213 0,5.02708 1.7463,9.31333 5.2123,12.85875 3.4661,3.54542 7.7523,5.31813 12.8323,5.31813 5.08,0 9.3663,-1.79917 12.9117,-5.37105 z m -2.9104,-16.88041 c 0,3.70416 -1.614,6.0325 -4.8684,6.985 l 5.9532,8.06979 h -4.8154 l -5.3711,-7.48771 h -4.9212 v 7.48771 h -3.8894 V 95.932697 h 8.4137 c 3.3867,0 5.8209,0.58208 7.3025,1.74625 1.4817,1.16417 2.1961,3.016253 2.1961,5.582713 z m -5.0006,3.14854 c 0.7937,-0.635 1.1641,-1.71979 1.1641,-3.175 0,-1.45521 -0.3969,-2.48708 -1.1906,-3.06917 -0.7938,-0.582083 -2.2225,-0.846663 -4.2333,-0.846663 h -4.7625 v 8.069793 h 4.6302 c 2.1431,-0.0265 3.6248,-0.34396 4.3921,-0.97896 z" + inkscape:label="Apache_Reg" /> + <path + style="fill:#d22128;stroke-width:0.26458332" + inkscape:connector-curvature="0" + id="path1234" + d="m 727.77184,335.3277 v 23.04521 H 550.44814 V 94.451027 h 173.99 v 23.045213 h -148.3254 v 95.17063 h 129.3812 v 21.93395 h -129.3812 v 100.75334 h 151.6591 z" + inkscape:label="Apache_E" /> + <path + style="fill:#d22128;stroke-width:0.26458332" + inkscape:connector-curvature="0" + id="path1230" + d="m 143.75707,92.942907 c 46.83125,0 81.04188,23.786043 97.39313,57.626253 l -20.82271,12.64708 c -16.72167,-34.95146 -49.45063,-46.83125 -78.07854,-46.83125 -63.208955,0 -97.763535,56.515 -97.763535,109.66979 0,58.36709 42.75666,111.15146 98.874785,111.15146 29.73916,0 64.69062,-14.86958 81.41229,-49.08021 l 21.56354,11.13896 c -17.09208,39.39646 -63.94979,61.33042 -104.4575,61.33042 -72.495825,0 -123.428115,-69.13563 -123.428115,-136.04875 0.0264,-63.55292 45.74645,-131.603753 125.306655,-131.603753 z" + inkscape:label="Apache_C" /> + <path + style="fill:#d22128;stroke-width:0.26458332" + inkscape:connector-curvature="0" + id="path1232" + d="M 490.83754,94.451027 V 358.39936 h -26.0351 V 234.97124 H 308.30145 V 358.39936 H 282.66332 V 94.451027 h 25.63813 V 211.92603 H 464.80244 V 94.451027 Z" + inkscape:label="Apache_H" /> + <path + style="fill:#d22128;stroke-width:0.26458332" + inkscape:connector-curvature="0" + id="path1228" + d="M -223.16709,358.39936 -112.75647,94.451027 h 21.193135 L 18.847285,358.39936 H -9.0397951 L -43.250425,275.87582 H -161.83668 l -33.84021,82.52354 z m 121.20562,-233.46833 -54.26604,130.4925 h 107.076875 z" + inkscape:label="Apache_A" /> + <path + style="fill:#d22128;stroke-width:0.26458332" + inkscape:connector-curvature="0" + id="path1226" + d="M -396.09876,358.39936 V 94.451027 h 109.29937 c 45.34959,0 78.07855,42.015843 78.07855,82.893963 0,43.12708 -30.48,83.63479 -75.82959,83.63479 h -85.88375 v 97.39313 h -25.66458 z m 25.66458,-120.46479 h 84.37563 c 31.22083,0 51.30271,-28.62791 51.30271,-60.58958 0,-33.09937 -24.52688,-59.84875 -53.52521,-59.84875 h -82.15313 z" + inkscape:label="Apache_P" /> + <path + style="fill:#d22128;stroke-width:0.26458332" + inkscape:connector-curvature="0" + id="path1224" + d="M -666.60876,358.39936 -556.19814,94.451027 h 21.19313 l 110.41062,263.948333 h -27.88708 l -34.21062,-82.52354 h -118.58625 l -33.84021,82.52354 z m 121.20562,-233.46833 -54.26603,130.4925 h 107.07687 z" + inkscape:label="Apache_A" /> + </g> + <path + style="fill:#ff0000;stroke-width:0.26239252" + d="M 0.22478167,296.69425 C -0.379672,296.08979 3.0323407,289.369 5.4873429,286.32832 c 0.9964616,-1.23419 2.6509606,-2.94631 3.6766812,-3.80469 1.0256829,-0.8584 1.8671259,-1.74559 1.8698529,-1.97158 0.0028,-0.22592 -0.457613,-0.67086 -1.022989,-0.98863 -1.9433073,-1.09218 -4.7996151,-4.05708 -6.3190538,-6.55929 -1.0155839,-1.6725 -1.5714485,-2.711 -2.0792707,-2.89629 -0.4444639,0.23725 -0.80465057,-0.1997 -0.80121127,-0.47973 -0.46621398,-1.15382 1.67771137,-2.34568 2.58067267,-2.05909 0.8610852,0.14845 1.1129164,1.72819 1.3493901,2.35192 0.5469896,1.44276 0.4739798,1.30132 1.0532993,2.45879 1.2734608,2.54425 3.3269097,4.72783 5.4576827,5.80342 1.629954,0.82281 2.212093,1.62715 1.862171,2.57304 -0.118077,0.31924 -1.967448,2.32655 -4.1096873,4.46067 -3.9719932,3.95696 -5.8076354,6.3483 -7.0364396,9.16646 -0.3683617,0.8448 -0.7596258,1.70607 -0.8694588,1.91395 -0.22871497,0.4329 -0.64793329,0.62325 -0.87420063,0.39698 z M 26.70206,296.14508 c -0.209502,-0.2095 0.0279,-0.61936 0.3582,-0.61936 0.135741,0 0.247,0.17728 0.247,0.39359 0,0.40577 -0.309602,0.52128 -0.605108,0.22562 z m -1.60764,-3.55798 c -0.653823,-1.37123 -1.810818,-3.25116 -2.571096,-4.17759 -1.429037,-1.74124 -5.987281,-5.72608 -6.254249,-6.00344 -0.559386,-0.58118 -1.568162,-0.84702 -1.391911,-2.27921 0.08089,-0.30899 1.152595,-1.24896 2.438546,-2.13859 3.319256,-2.29636 4.904581,-4.45099 5.928223,-8.05704 0.529082,-1.86381 1.141469,-2.61142 1.933264,-2.36011 0.702417,0.22283 0.696126,0.51722 -0.05547,2.58756 -1.292145,3.55984 -3.32567,6.01619 -7.063986,8.53287 -1.118446,0.75294 -2.055055,1.31693 -2.033525,1.78082 0.0365,0.78645 0.711842,1.18158 2.755122,2.99787 1.796252,1.59674 4.027468,4.14872 5.381169,6.15479 1.606397,2.38059 2.733365,4.84448 2.378264,5.1996 -0.166113,0.16612 -0.672726,-0.61895 -1.444439,-2.23753 z" + id="path1466" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccccsccccccccssccccsccccccsccccc" + inkscape:label="hourglass" /> + <g + id="g2864" + inkscape:label="color_dots"> + <circle + inkscape:label="green1" + r="0.88533032" + cy="273.89798" + cx="13.948128" + id="path1483" + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.13229166;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2260)" /> + <circle + inkscape:label="green2" + r="0.70158249" + cy="275.59299" + cx="15.638769" + id="path1483-3" + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276)" /> + <circle + inkscape:transform-center-y="-0.24220642" + inkscape:transform-center-x="-1.1418613" + inkscape:label="green3" + r="0.48442599" + cy="275.61847" + cx="14.06506" + id="path1483-3-0" + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.072386;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2292)" /> + <circle + inkscape:transform-center-y="-0.16789611" + inkscape:transform-center-x="-0.79142984" + inkscape:label="green4" + r="0.33575773" + cy="277.57547" + cx="15.014526" + id="path1483-3-0-4" + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.05017104;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2324)" /> + <circle + inkscape:transform-center-y="-0.1221404" + inkscape:transform-center-x="-0.57566127" + inkscape:label="green5" + r="0.24421985" + cy="276.88751" + cx="14.125602" + id="path1483-3-0-4-8" + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.03649288;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2308)" /> + <circle + inkscape:transform-center-y="-0.16789611" + inkscape:transform-center-x="-0.79142984" + inkscape:label="green6" + r="0.33575773" + cy="279.63672" + cx="13.949684" + id="path1483-3-0-4-88" + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.05017104;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2340)" /> + <circle + inkscape:transform-center-y="-0.10736249" + inkscape:transform-center-x="-0.50604888" + inkscape:label="green7" + r="0.21468724" + cy="281.6181" + cx="14.34833" + id="path1483-3-0-4-88-9" + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248)" /> + <circle + inkscape:transform-center-y="-0.10736249" + inkscape:transform-center-x="-0.50604888" + inkscape:label="green8" + r="0.21468726" + cy="283.44598" + cx="12.798038" + id="path1483-3-0-4-88-9-7" + style="opacity:1;fill:#007f00;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter1940)" /> + <circle + inkscape:transform-center-y="-1.2110651" + inkscape:transform-center-x="-2.9065562" + inkscape:label="red1" + r="0.88533032" + cy="275.20081" + cx="11.592816" + id="path1483-4" + style="opacity:1;fill:#ff0000;fill-opacity:0.94117647;stroke:none;stroke-width:0.13229166;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2260-7)" /> + <circle + inkscape:label="red2" + r="0.70158249" + cy="274.95859" + cx="9.529829" + id="path1483-3-3" + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3)" /> + <circle + transform="matrix(0.88839286,0,0,0.88839286,1.4058873,30.932131)" + inkscape:transform-center-y="-1.9588817" + inkscape:transform-center-x="1.7956426" + inkscape:label="red3" + r="0.70158249" + cy="277.33896" + cx="12.03548" + id="path1483-3-3-2" + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0)" /> + <circle + transform="matrix(0.47385204,0,0,0.47385204,4.3279237,144.86906)" + inkscape:transform-center-y="-1.0448304" + inkscape:transform-center-x="0.95776193" + inkscape:label="red3" + r="0.70158249" + cy="277.33896" + cx="12.03548" + id="path1483-3-3-2-0" + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5)" /> + <circle + transform="matrix(0.34630101,0,0,0.34630101,6.798504,180.89532)" + inkscape:transform-center-y="-0.76358713" + inkscape:transform-center-x="0.69995244" + inkscape:label="red4" + r="0.70158249" + cy="277.33896" + cx="12.03548" + id="path1483-3-3-2-0-4" + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5-5)" /> + <circle + transform="matrix(0.34630101,0,0,0.34630101,10.707321,182.43211)" + inkscape:transform-center-y="-0.76358713" + inkscape:transform-center-x="0.69995244" + inkscape:label="red5" + r="0.70158249" + cy="277.33896" + cx="12.03548" + id="path1483-3-3-2-0-4-2" + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5-5-6)" /> + <circle + transform="matrix(0.34630101,0,0,0.34630101,9.9305688,184.55356)" + inkscape:transform-center-y="-0.76358713" + inkscape:transform-center-x="0.69995244" + inkscape:label="red6" + r="0.70158249" + cy="277.33896" + cx="12.03548" + id="path1483-3-3-2-0-4-7" + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5-5-2)" /> + <circle + transform="matrix(0.34630101,0,0,0.34630101,8.8865472,186.35764)" + inkscape:transform-center-y="-0.76358713" + inkscape:transform-center-x="0.69995244" + inkscape:label="red7" + r="0.70158249" + cy="277.33896" + cx="12.03548" + id="path1483-3-3-2-0-4-4" + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5-5-7)" /> + <circle + transform="matrix(0.34630101,0,0,0.34630101,10.181134,186.3994)" + inkscape:transform-center-y="-0.76358713" + inkscape:transform-center-x="0.69995244" + inkscape:label="red8" + r="0.70158249" + cy="277.33896" + cx="12.03548" + id="path1483-3-3-2-0-4-28" + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5-5-8)" /> + <circle + transform="matrix(0.44025121,0,0,0.44025121,10.986824,155.23165)" + inkscape:transform-center-y="-0.97074837" + inkscape:transform-center-x="0.88984675" + inkscape:label="red10" + r="0.70158249" + cy="277.33896" + cx="12.03548" + id="path1483-3-3-2-0-4-2-2" + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5-5-6-8)" /> + <circle + transform="matrix(0.34630101,0,0,0.34630101,11.233508,187.66058)" + inkscape:transform-center-y="-0.76358713" + inkscape:transform-center-x="0.69995244" + inkscape:label="red9" + r="0.70158249" + cy="277.33896" + cx="12.03548" + id="path1483-3-3-2-0-4-6" + style="opacity:1;fill:#ff0000;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2276-3-0-5-5-9)" /> + <circle + transform="matrix(1.1352883,0,0,1.1352883,-2.3642295,-37.146036)" + inkscape:label="blue1" + r="0.70158249" + cy="274.56949" + cx="17.475492" + id="path1483-3-1" + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2531)" /> + <circle + inkscape:transform-center-y="-0.72177105" + inkscape:transform-center-x="-0.059854253" + transform="matrix(0.67681132,0,0,0.67681132,5.9136463,90.544934)" + inkscape:label="blue2" + r="0.70158249" + cy="274.56949" + cx="17.475492" + id="path1483-3-1-1" + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2531-0)" /> + <circle + inkscape:transform-center-y="-0.51337868" + inkscape:transform-center-x="-0.042571968" + transform="matrix(0.48139489,0,0,0.48139489,10.50982,142.52895)" + inkscape:label="blue3" + r="0.70158249" + cy="274.56949" + cx="17.475492" + id="path1483-3-1-1-8" + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2531-0-1)" /> + <circle + inkscape:transform-center-y="-0.31298695" + inkscape:transform-center-x="-0.025955496" + transform="matrix(0.29349449,0,0,0.29349449,13.651731,195.042)" + inkscape:label="blue4" + r="0.70158249" + cy="274.56949" + cx="17.475492" + id="path1483-3-1-1-4" + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2531-0-5)" /> + <circle + inkscape:transform-center-y="-0.34504766" + inkscape:transform-center-x="-0.028614186" + transform="matrix(0.32355855,0,0,0.32355855,7.3976455,186.79913)" + inkscape:label="blue5" + r="0.70158249" + cy="274.56949" + cx="17.475492" + id="path1483-3-1-1-4-5" + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2531-0-5-6)" /> + <circle + inkscape:transform-center-y="-0.81698114" + inkscape:transform-center-x="-0.067749861" + transform="matrix(0.76609135,0,0,0.76609135,0.30399118,67.713821)" + inkscape:label="blue6" + r="0.70158249" + cy="274.56949" + cx="17.475492" + id="path1483-3-1-1-7" + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.1048349;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2531-0-8)" /> + <circle + inkscape:transform-center-y="-0.10736249" + inkscape:transform-center-x="-0.50604888" + inkscape:label="blue7" + r="0.21468724" + cy="281.60339" + cx="13.559896" + id="path1483-3-0-4-88-9-0" + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2)" /> + <circle + inkscape:transform-center-y="-0.10736249" + inkscape:transform-center-x="-0.50604888" + inkscape:label="blue8" + r="0.21468724" + cy="283.19205" + cx="13.819755" + id="path1483-3-0-4-88-9-0-9" + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6)" /> + <circle + inkscape:transform-center-y="-0.10736249" + inkscape:transform-center-x="-0.50604888" + inkscape:label="blue9" + r="0.21468724" + cy="282.93811" + cx="15.130859" + id="path1483-3-0-4-88-9-0-9-8" + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9)" /> + <circle + inkscape:transform-center-y="-0.10736249" + inkscape:transform-center-x="-0.50604888" + inkscape:label="coffee1" + r="0.21468724" + cy="283.69995" + cx="12.012555" + id="path1483-3-0-4-88-9-0-9-8-1" + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1)" /> + <circle + inkscape:transform-center-y="-0.10736249" + inkscape:transform-center-x="-0.50604888" + inkscape:label="coffee2" + r="0.21468724" + cy="284.78076" + cx="11.510556" + id="path1483-3-0-4-88-9-0-9-8-1-3" + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-1)" /> + <circle + inkscape:transform-center-y="-0.10736249" + inkscape:transform-center-x="-0.50604888" + inkscape:label="coffee3" + r="0.21468724" + cy="284.50906" + cx="12.561803" + id="path1483-3-0-4-88-9-0-9-8-1-9" + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-4)" /> + <circle + inkscape:transform-center-y="-0.10736249" + inkscape:transform-center-x="-0.50604888" + inkscape:label="coffee4" + r="0.21468724" + cy="284.76303" + cx="13.311849" + id="path1483-3-0-4-88-9-0-9-8-1-93" + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-19)" /> + <circle + inkscape:transform-center-y="-0.10736249" + inkscape:transform-center-x="-0.50604888" + inkscape:label="coffee5" + r="0.21468724" + cy="283.97754" + cx="13.613049" + id="path1483-3-0-4-88-9-0-9-8-1-0" + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-3)" /> + <circle + inkscape:transform-center-y="-0.10736249" + inkscape:transform-center-x="-0.50604888" + inkscape:label="coffee6" + r="0.21468724" + cy="283.96573" + cx="14.605236" + id="path1483-3-0-4-88-9-0-9-8-1-4" + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-5)" /> + <circle + inkscape:transform-center-y="-0.10736249" + inkscape:transform-center-x="-0.50604888" + inkscape:label="coffee7" + r="0.21468724" + cy="284.78073" + cx="14.871001" + id="path1483-3-0-4-88-9-0-9-8-1-6" + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-0)" /> + <circle + inkscape:transform-center-y="-0.10736249" + inkscape:transform-center-x="-0.50604888" + inkscape:label="coffee8" + r="0.21468724" + cy="284.77481" + cx="15.6742" + id="path1483-3-0-4-88-9-0-9-8-1-5" + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-2)" /> + <circle + inkscape:transform-center-y="-0.10736249" + inkscape:transform-center-x="-0.50604888" + inkscape:label="coffee9" + r="0.21468724" + cy="284.49725" + cx="16.418341" + id="path1483-3-0-4-88-9-0-9-8-1-8" + style="opacity:1;fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.03207992;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter2248-2-6-9-1-6)" /> + </g> + <g + transform="matrix(3.1596989,0,0,3.1596989,-392.84452,-284.9539)" + id="g3054" + inkscape:label="cup" + style="display:inline"> + <g + transform="translate(0.01169304,-1.727816)" + id="g2998"> + <ellipse + style="opacity:1;fill:#000000;fill-opacity:1;stroke:#5993dc;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + id="path2951-9" + cx="128.77695" + cy="184.27515" + rx="2.2179031" + ry="0.64501309" /> + <ellipse + style="opacity:1;fill:#000000;fill-opacity:1;stroke:#5993dc;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + id="path2951-9-0" + cx="128.77747" + cy="184.3564" + rx="2.2179034" + ry="0.64501309" /> + <ellipse + style="opacity:1;fill:#ccaf5f;fill-opacity:1;stroke:#5993dc;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + id="path2951" + cx="128.77689" + cy="184.27364" + rx="2.1833072" + ry="0.61824954" /> + </g> + <path + sodipodi:nodetypes="cccczcccccccccc" + inkscape:connector-curvature="0" + id="path3012" + transform="scale(0.26458333)" + d="m 486.9043,682.01953 c -2.50186,-0.048 -5.12716,0.67257 -5.125,1.49024 l 0.004,1.44335 h 0.002 c 0.37644,3.65723 2.27859,6.05321 4.87059,6.03812 2.592,-0.0151 3.60697,-1.28146 4.563,-3.19632 4.12974,-2.05232 2.78561,-3.41817 0.43164,-3.0957 l 0.0332,-1.28906 c 0.0227,-0.79491 -2.27789,-1.34255 -4.77929,-1.39063 z m 5.67382,3.14258 c 0.69846,0.0585 0.66798,0.67417 0.20899,1.13281 l -1.44727,1.08399 c 0.10281,-0.65923 0.26206,-0.69907 0.36524,-2.17774 z" + style="display:inline;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.03779528;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + <path + sodipodi:nodetypes="czcc" + inkscape:connector-curvature="0" + id="path3033" + d="m 127.51611,181.29623 c 0.0272,0.28871 0.2976,1.45684 1.25955,1.48215 0.96194,0.0253 1.27955,-0.97941 1.26773,-1.47933 -0.83083,0.45557 -1.88688,0.29236 -2.52728,-0.003 z" + style="fill:#ccaf5f;fill-opacity:1;stroke:none;stroke-width:0.01;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + <path + sodipodi:nodetypes="czcczcc" + inkscape:connector-curvature="0" + id="path3035" + d="m 127.51166,181.23764 c 0.18196,0.10413 0.86168,0.30435 1.25671,0.29869 0.39503,-0.006 0.64044,-3.2e-4 1.27229,-0.29087 l 0.006,-0.25539 c -0.0394,0.10285 -0.67435,0.32561 -1.27739,0.32734 -0.60304,0.002 -1.0452,-0.12585 -1.25972,-0.33363 z" + style="fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.01;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + <ellipse + transform="matrix(1,0,-0.00411815,0.99999152,0,0)" + ry="0.36997855" + rx="1.2750689" + cy="180.86237" + cx="129.53156" + id="path3037" + style="display:inline;opacity:1;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.01257183;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + <path + sodipodi:nodetypes="czczc" + inkscape:connector-curvature="0" + id="path3039" + d="m 127.71432,181.06203 c 0.21614,0.0876 0.47779,0.21433 1.05092,0.19878 0.57313,-0.0155 0.93983,-0.11187 1.11084,-0.20902 -0.23422,-0.15242 -0.45794,-0.24172 -1.05092,-0.24847 -0.59298,-0.007 -0.93477,0.10876 -1.11084,0.25871 z" + style="fill:#c0af83;fill-opacity:1;stroke:none;stroke-width:0.01;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + </g> + <g + transform="matrix(3.0789987,0,0,3.0789987,-490.69707,-327.69557)" + id="g3733" + inkscape:label="documents"> + <path + sodipodi:nodetypes="ccccccccccccccccccccsccccccccccccccccccccccccccccccccccccccccccccccccccccscccccccccccccccccccccccccccccccccccccccsccccc" + inkscape:label="light gray" + inkscape:connector-curvature="0" + id="path3233" + transform="scale(0.26458333)" + d="m 614.56836,722.91602 c 0.002,0.004 0.003,0.008 0.006,0.0137 v -0.008 c -2.3e-4,-2.7e-4 2.3e-4,-0.002 0,-0.002 -10e-4,-0.002 -0.005,-0.002 -0.006,-0.004 z m 5.42578,0.0117 c -0.002,1.2e-4 -0.004,0.002 -0.006,0.002 -0.1937,0.015 -0.41023,0.095 -0.76953,0.16601 -0.10717,0.0216 -0.21816,0.0376 -0.35742,0.0547 -0.0666,0.008 -0.12593,0.0171 -0.20117,0.0234 -0.22608,0.0193 -0.48216,0.0314 -0.80274,0.0254 -0.96726,-0.0188 -1.60126,-0.0356 -2.0918,-0.0586 -0.31591,-0.0155 -0.60455,-0.0331 -0.77539,-0.0605 -0.0128,-0.002 -0.0445,-0.004 -0.0566,-0.006 0.0281,0.18475 0.0803,0.4784 0.0586,0.93945 0.0126,10e-6 0.0188,0.002 0.0312,0.002 0.40748,7e-4 0.69076,0.0115 0.91406,0.0313 0.002,1.6e-4 0.006,-1.8e-4 0.008,0 0.8289,-0.006 1.30116,0.31165 3.53907,-0.10938 0.78424,-0.13351 1.11772,0.35153 1.40751,0.60657 1.07734,0.94809 2.09321,1.54497 2.99288,1.11413 0.8859,-0.21646 1.35349,-0.96306 2.28711,-1.36718 0.005,-0.36089 -0.0122,-0.68485 -0.0684,-0.9004 -0.0575,0.0439 -0.0813,0.0652 -0.1504,0.11524 -0.2538,0.18525 -0.58093,0.40701 -1.02539,0.66797 -0.7936,0.37882 -1.30115,0.7521 -1.86914,0.73047 -0.14265,-0.005 -0.28748,-0.0362 -0.44336,-0.0977 -0.30958,-0.12215 -0.65735,-0.3673 -1.08398,-0.7832 -0.21381,-0.20842 -0.44754,-0.45931 -0.70703,-0.75977 h -0.002 c -0.1815,-0.12569 -0.31465,-0.19926 -0.43555,-0.25195 -0.0298,-0.0131 -0.0603,-0.0238 -0.0879,-0.0332 -0.1097,-0.0378 -0.20697,-0.0574 -0.30274,-0.0508 -6e-4,5e-5 -10e-4,-4e-5 -0.002,0 z m -3.60547,1.22071 c 0.0152,0.008 0.0364,0.0159 0.0488,0.0254 -0.013,-0.009 -0.0333,-0.0174 -0.0488,-0.0254 z m 0.11719,0.0918 c 0.0279,0.0463 0.0488,0.0951 0.0488,0.16211 0,-0.0653 -0.0184,-0.11719 -0.0488,-0.16211 z m -0.4082,0.93555 c -0.35394,0.0763 -0.84461,-0.0283 -1.3086,0.0625 -1.24811,0 -2.34218,0.41393 -3.45117,1.29883 -0.5884,0.46949 -1.00688,0.59193 -1.92383,0.90234 -0.4734,0.16026 -0.8412,0.29665 -1.15429,0.40821 -0.20318,0.0716 -0.3993,0.13804 -0.54102,0.17382 -0.002,5.5e-4 -0.006,10e-4 -0.008,0.002 -0.0983,0.0248 -0.19086,0.0444 -0.26172,0.0469 l 0.33984,1.15625 c 0.0232,3.9e-4 0.0468,0.008 0.0742,0.0449 1.2116,-0.62653 1.31838,-0.71948 2.17774,-0.92773 0,0 0.66835,2.23444 0.71484,2.58594 0.0464,0.35134 0.92017,2.45074 1.25391,3.35351 0.33354,0.90278 1.20365,2.5793 1.32421,3.06055 0.19658,0.19695 0.18808,0.006 2.16602,-0.71094 0.86293,-0.43711 1.7418,-0.80741 1.95312,-0.94726 -0.037,-0.13335 -0.072,-0.32803 -0.10937,-0.48438 -0.0285,0.22021 -0.14999,0.26349 -0.39648,0.35742 l -3.41407,1.60547 -0.2832,-0.73633 c -0.15553,-0.40414 -0.54891,-1.28429 -1.02539,-2.26757 -0.53401,-1.10193 -1.02095,-2.43748 -1.19141,-3.37696 l -0.63476,-2.58398 c 1.19584,-0.94571 3.1848,-1.84002 4.5,-2.07813 l 1.19922,-0.21679 z m -1.14258,1.50195 c -0.67536,0.0796 -1.891,0.63431 -2.9043,1.37891 -0.90792,0.66728 -0.98351,0.84509 -0.74805,1.78906 0.43382,1.73832 0.91084,3.16881 1.65039,4.95313 h 0.002 c 0.38645,0.93241 0.7439,1.69531 0.79492,1.69531 0.0509,0 2.0813,-0.88412 2.89062,-1.27734 0.1304,-0.16929 0.12256,-0.25807 -0.0215,-0.95899 -0.091,-0.44281 -0.34121,-2.24389 -0.55664,-4.0039 -0.21532,-1.75998 -0.5042,-3.32873 -0.64062,-3.48633 -0.0776,-0.0894 -0.24168,-0.11649 -0.4668,-0.0898 z m 0.0234,0.39063 c 0.50294,-0.16078 0.90556,4.02711 1.26953,6.55078 0.006,0.23962 0.30726,1.1777 -0.0723,1.31641 l -2.21875,0.95117 -0.67383,-1.77149 c -0.40535,-0.92284 -0.9257,-2.48879 -1.15625,-3.48046 -0.40898,-1.75971 -0.4,-1.81602 0.33985,-2.30079 0.41695,-0.27318 2.04339,-1.0876 2.51172,-1.26562 z m 9.18164,0.51953 c -0.10742,0.13097 -0.19843,0.43318 -0.28321,0.83789 l 1.14649,0.18945 c 0.63537,0.10508 1.8186,0.19335 2.63086,0.19532 1.00739,0.002 1.74678,0.21378 2.32422,0.66797 l 1.08203,0.71484 c 0.1978,-0.33447 0.32853,-0.62243 0.33984,-1.06055 -0.005,-0.002 -0.0182,-0.01 -0.0234,-0.0117 -0.25455,-0.10181 -0.58631,-0.28506 -1.11914,-0.57421 -0.165,-0.0828 -0.38513,-0.16696 -0.64062,-0.25 -0.51099,-0.16609 -1.16506,-0.32421 -1.81446,-0.4375 -0.32469,-0.0566 -0.64776,-0.10284 -0.95117,-0.13282 -1.16295,-0.11481 -2.36301,-0.0875 -2.6914,-0.13867 z m 0.0723,1.48438 -0.61328,3.79296 c -0.4252,3.679 -0.8807,4.03516 -0.17578,3.72071 -2.3e-4,-1.0944 0.38782,-3.86556 0.53711,-4.22461 l 0.50391,-2.84375 1.00781,0.31836 c 0.55366,0.17575 1.43684,0.30613 1.96484,0.29101 2.25732,0.25334 1.90883,0.29584 1.08399,2.54493 h 0.002 c -0.41843,1.25833 -0.63416,2.89481 -1.1543,4.18359 -0.27364,0.8945 -0.24083,0.80859 -0.082,0.80859 0.45562,0 0.93095,-2.05232 1.25977,-3.51953 0.16478,-0.73531 0.53262,-1.89602 0.81836,-2.58008 0.52236,-1.25019 0.35743,-1.71536 -0.64649,-1.8125 -1.18628,-0.11444 -2.08425,-0.23813 -3.21289,-0.44336 z" + style="display:inline;fill:#cdcdcd;stroke-width:0.31999999" /> + <path + style="display:inline;opacity:1;vector-effect:none;fill:#616162;fill-opacity:1;stroke:none;stroke-width:0.31999999;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + d="m 626.15039,722.23828 c -0.14691,0.008 -0.33657,0.0733 -0.57617,0.20703 -0.0343,0.0259 -0.0336,0.0296 -0.0664,0.0547 0.38795,-0.18092 0.68437,-0.26853 0.80664,-0.23438 -0.0486,-0.0175 -0.10043,-0.0306 -0.16406,-0.0273 z m 0.22266,0.0586 c 0.12023,0.27135 0.19498,0.41351 0.22656,0.50585 -0.0197,-0.24909 -0.0913,-0.42249 -0.22656,-0.50585 z m -11.79883,0.62304 -0.006,0.15039 c 0.0586,0.39974 0.11165,0.72251 0.01,0.97266 0.12842,-0.0114 0.2595,-0.0288 0.38086,-0.0293 0.0136,0 0.0198,-1e-5 0.0332,0 0.0217,-0.46105 -0.0305,-0.7547 -0.0586,-0.93945 -0.19719,-0.0351 -0.30099,-0.0865 -0.35937,-0.1543 z m 12.01953,0.0605 c -0.0201,0.0274 -0.0441,0.0537 -0.0879,0.0918 -0.0787,0.0683 -0.23959,0.19403 -0.40234,0.31835 0.15981,0.61344 0.12008,1.9391 -0.4043,3.27344 0.16535,8.8e-4 0.26398,-0.009 0.42187,-0.01 0.0681,-1.24363 0.47946,-2.77778 0.47266,-3.67383 z m -10.09961,1.82226 c -0.0247,0.0975 -0.0488,0.17774 -0.0488,0.17774 0.24607,0.0359 0.53324,0.0793 0.68555,0.10156 -0.0135,0.19358 -0.0176,0.38986 -0.0293,0.58399 -0.19721,-0.0281 -0.39458,-0.0669 -0.59179,-0.0918 l -0.004,0.008 c -0.0218,-0.29767 -0.0399,-0.41047 -0.0606,-0.60156 -0.0752,0.099 -0.19947,0.15041 -0.34765,0.17578 v 1.59961 c 0.2313,3.30557 0.38456,3.93259 0.79687,5.97656 0.3035,2.36652 0.85626,4.33856 1.05469,3.75977 -0.0301,-0.23244 -0.17148,-0.92772 -0.25977,-1.4043 0.28908,0.0415 0.57832,0.0846 0.86914,0.14453 -0.0129,0.12232 -0.0208,0.24484 -0.0351,0.36719 v 0.004 l 0.19726,-0.0527 c 0.012,-0.089 0.0233,-0.18205 0.0352,-0.27148 0.31303,0.069 0.62621,0.1366 0.94141,0.22851 0.13038,0.0527 0.23996,0.0862 0.36132,0.13086 -0.0236,0.15167 -0.0424,0.30349 -0.0684,0.45508 l 0.002,0.006 0.19922,-0.043 c 0.0213,-0.11338 0.0413,-0.23158 0.0625,-0.3457 0.44049,0.15355 0.82488,0.25811 1.17968,0.33594 -0.0364,0.16869 -0.068,0.33741 -0.10742,0.50585 v 0.006 l 0.20117,-0.0312 c 0.0365,-0.14521 0.0713,-0.29666 0.10743,-0.44336 0.21287,0.0424 0.4227,0.0826 0.6289,0.11914 -0.0515,0.16763 -0.0959,0.34695 -0.15234,0.50586 0.30879,0.25097 0.18438,0.11058 0.37109,-0.1914 0.26079,-0.42202 0.76162,-3.30859 1.22461,-7.06446 0.13238,-1.0739 0.27097,-1.64313 0.45313,-1.86523 -0.0143,-0.002 -0.0752,-0.001 -0.0859,-0.004 -0.15022,-0.0358 -0.28444,-0.0541 -0.31641,-0.23828 -0.003,0.003 -10e-4,0.002 -0.004,0.006 -0.18592,-0.0366 -0.37038,-0.0778 -0.55469,-0.11914 0.0477,-0.18362 0.0904,-0.37084 0.14062,-0.55273 0.11144,0.0194 0.32348,0.0739 0.50391,0.11719 0.0203,-0.0696 0.0222,-0.1071 0.0508,-0.19141 v -0.002 c 0.0162,0.002 0.0962,0.002 0.11719,0.004 -0.29845,-0.0544 -0.65568,-0.11849 -0.82422,-0.1543 -0.59074,-0.13474 -1.17005,-0.30158 -1.74609,-0.48046 l -0.19532,-0.0625 c -0.37223,-0.1181 -0.74609,-0.232 -1.11523,-0.35938 -0.22725,-0.0761 -0.45439,-0.13883 -0.68164,-0.20117 l -0.19727,-0.0566 c -0.63665,-0.16467 -1.27349,-0.26855 -1.91015,-0.36328 l -0.20313,-0.0332 c -0.13758,-0.0194 -0.41922,-0.0616 -0.64453,-0.0937 z m -4.92969,0.16407 c -0.23426,0.0811 -0.46164,0.17563 -0.66992,0.31445 0.222,-0.11618 0.44609,-0.2107 0.66992,-0.31445 z m 5.76758,0.14648 c 0.62706,0.098 1.25768,0.22985 1.89063,0.39258 -0.0282,0.17857 -0.0496,0.35984 -0.0762,0.53906 -0.61509,-0.15695 -1.22864,-0.25569 -1.84375,-0.34765 0.0111,-0.19395 0.0153,-0.39129 0.0293,-0.58399 z m 2.08789,0.44338 c 0.20915,0.0561 0.41709,0.0941 0.62696,0.1582 0.4176,0.17683 0.79717,0.31852 1.15234,0.4375 -0.0344,0.16347 -0.0627,0.33003 -0.0957,0.49414 -0.34441,-0.1102 -0.69139,-0.21212 -1.03321,-0.33007 -0.24151,-0.0809 -0.48309,-0.14943 -0.72461,-0.21485 0.0262,-0.18111 0.0456,-0.36515 0.0742,-0.54492 z m -2.90234,0.20313 c 0.19106,0.0266 0.38304,0.0636 0.57422,0.0918 -0.0125,0.21903 -0.024,0.4382 -0.0332,0.65821 -0.16601,-0.0239 -0.33198,-0.053 -0.49804,-0.0781 -0.0144,-0.23095 -0.0286,-0.46702 -0.043,-0.67187 z m 0.77734,0.12304 c 0.60423,0.0951 1.21063,0.22186 1.82031,0.37696 -0.0295,0.20485 -0.0593,0.4092 -0.0859,0.61523 -0.58836,-0.14899 -1.17726,-0.24282 -1.76563,-0.33203 0.008,-0.22136 0.0198,-0.44048 0.0312,-0.66016 z m 4.09961,0.32813 c 0.64638,0.20535 1.2145,0.33822 1.74414,0.43554 -0.0493,0.17948 -0.093,0.3626 -0.14062,0.54297 -0.57469,-0.13531 -1.13806,-0.30457 -1.69922,-0.48047 0.0326,-0.16569 0.0611,-0.33361 0.0957,-0.49804 z m -2.07812,0.0996 c 0.22372,0.0595 0.44537,0.10134 0.66992,0.16992 0.38544,0.16319 0.73671,0.29482 1.06836,0.4082 -0.0375,0.19116 -0.0765,0.38186 -0.11133,0.57422 -0.32223,-0.10377 -0.64679,-0.20011 -0.9668,-0.31055 -0.24913,-0.0834 -0.49695,-0.15368 -0.74609,-0.2207 0.0252,-0.20894 0.0573,-0.414 0.0859,-0.62109 z m -2.74414,0.30859 c 0.15893,0.0257 0.31786,0.0524 0.47656,0.0762 -0.008,0.21689 -0.0273,0.43031 -0.0312,0.64844 -0.13472,-0.0194 -0.26951,-0.041 -0.4043,-0.0625 -0.0138,-0.24156 -0.0269,-0.42968 -0.041,-0.66211 z m 0.68164,0.10938 c 0.57959,0.0927 1.16147,0.21332 1.74609,0.36132 -0.0249,0.20228 -0.0568,0.40174 -0.0781,0.60547 -0.56362,-0.13957 -1.12584,-0.23095 -1.68946,-0.3164 0.002,-0.21898 0.0152,-0.43312 0.0215,-0.65039 z m 3.99804,0.22265 c 0.62838,0.20422 1.18156,0.33936 1.69532,0.4375 -0.053,0.20412 -0.1081,0.40759 -0.15821,0.61328 -0.55747,-0.13478 -1.10338,-0.30451 -1.64844,-0.47656 0.0335,-0.19358 0.075,-0.3824 0.11133,-0.57422 z m -2.05078,0.18945 c 0.23091,0.0611 0.45962,0.105 0.69141,0.17579 0.36294,0.15367 0.69097,0.27559 1.00586,0.38476 -0.0326,0.18711 -0.0701,0.372 -0.0996,0.56055 -0.28411,-0.0925 -0.57107,-0.17597 -0.85352,-0.27344 -0.27075,-0.0907 -0.54174,-0.1688 -0.8125,-0.24023 0.0198,-0.204 0.0452,-0.40524 0.0684,-0.60743 z m 3.94922,0.28321 c 0.19209,0.0346 0.384,0.0686 0.57227,0.0996 -0.0397,0.20343 -0.0805,0.4101 -0.11719,0.65234 -0.20538,-0.0407 -0.40997,-0.084 -0.61328,-0.13086 0.0493,-0.20935 0.10556,-0.41405 0.1582,-0.62109 z m -6.52539,0.0449 c 0.13102,0.0222 0.26186,0.0429 0.39258,0.0625 -0.003,0.24824 -0.002,0.49782 0.002,0.74805 -0.15903,-0.0236 -0.2503,-0.0511 -0.34961,-0.0781 -0.0171,-0.31108 -0.0263,-0.40281 -0.0449,-0.73242 z m 0.61133,0.0977 c 0.55306,0.0888 1.10839,0.20272 1.66601,0.34179 -0.0231,0.23644 -0.0434,0.47405 -0.0605,0.71289 -0.52982,-0.1333 -1.05807,-0.22103 -1.58789,-0.30468 -0.004,-0.24917 -0.0188,-0.50311 -0.0176,-0.75 z m 3.85937,0.20313 c 0.61033,0.20172 1.14356,0.33098 1.64258,0.42969 -0.0472,0.1987 -0.0988,0.39512 -0.14258,0.5957 -0.53836,-0.13488 -1.06652,-0.30045 -1.59375,-0.46875 0.028,-0.18739 0.0633,-0.37095 0.0937,-0.55664 z m -6.20703,0.0742 c -0.13001,-0.0265 -0.55675,0.13977 -0.87109,0.30078 -0.35188,0.18028 -0.85495,0.47515 -1.11914,0.6543 -0.26419,0.17915 -0.86243,0.57544 -0.66211,0.57812 0.20069,0.003 1.22197,-0.45764 2.47851,-1.24023 0.22262,-0.19465 0.25169,-0.27785 0.17383,-0.29297 z m 16.55469,0 c 0.1773,0.0898 0.39366,0.18554 0.51562,0.26563 0.1493,0.0983 0.0816,0.58475 0.0801,0.68359 -0.11266,0.41136 -0.28085,0.47549 -0.63867,0.33789 -0.0189,0.75318 -0.29408,0.92866 -0.88867,1.98047 -0.56096,1.30858 -0.61518,1.52649 -1.29492,3.46289 -0.008,0.68542 -1.86633,3.83984 -2.26368,3.83984 -0.1829,0 -0.23912,0.14955 -0.125,0.33399 0.35263,0.57044 1.15822,-0.36321 2.08594,-2.41602 0.47721,-1.056 0.97152,-2.42307 1.09961,-3.03906 0.12813,-0.61603 0.65113,-1.75695 1.16016,-2.53516 1.06057,-1.62138 1.22175,-2.90499 0.36523,-2.9082 -0.0218,-7e-5 -0.0704,-0.006 -0.0957,-0.006 z m -12.32422,0.12109 c 0.24771,0.0648 0.49347,0.11155 0.74219,0.1875 0.32627,0.13815 0.61737,0.24397 0.90429,0.34571 -0.0336,0.22596 -0.0676,0.45119 -0.0957,0.67968 -0.28549,-0.0929 -0.57361,-0.17745 -0.85742,-0.27539 -0.24666,-0.0826 -0.49357,-0.15225 -0.74023,-0.21875 0.0167,-0.23907 0.0254,-0.48222 0.0469,-0.71875 z m -11.85547,0.0723 c 0.1332,0.58702 0.38873,1.56717 0.95899,3.36914 1.38047,4.08113 2.87774,7.00112 3.72851,7.26758 0.31106,0.0975 0.24734,-0.10812 -0.19336,-0.61719 -1.22101,-1.41124 -1.95489,-2.62617 -3.19726,-6.19922 l -1.11133,-3.78711 c -0.0757,0.003 -0.1388,-0.006 -0.18555,-0.0332 z m 15.67774,0.20312 c 0.21672,0.0404 0.42961,0.0766 0.64062,0.11133 -0.0299,0.20623 -0.0605,0.41527 -0.0898,0.64258 -0.2295,-0.0459 -0.45888,-0.0923 -0.68555,-0.14648 0.043,-0.20392 0.0885,-0.40576 0.13477,-0.60743 z m -6.26172,0.15235 c 0.0957,0.0267 0.1905,0.0509 0.33984,0.0742 0.005,0.23278 0.0195,0.46828 0.0312,0.70312 -0.15023,-0.0214 -0.23313,-0.0241 -0.32617,-0.0293 -0.0143,-0.24588 -0.028,-0.44064 -0.0449,-0.74804 z m 0.57812,0.11133 c 0.51953,0.0875 1.04087,0.19988 1.56446,0.33203 -0.0135,0.21376 -0.0156,0.43239 -0.0234,0.64844 -0.50855,-0.12242 -1.01684,-0.20432 -1.52539,-0.28126 -0.01,-0.23488 -0.0105,-0.46638 -0.0156,-0.69921 z m 3.70899,0.0703 c 0.59255,0.2009 1.1038,0.32723 1.58789,0.42773 -0.0485,0.23019 -0.0977,0.46015 -0.14063,0.69336 -0.51953,-0.13151 -1.02983,-0.29067 -1.53906,-0.45312 0.0273,-0.22459 0.0603,-0.44588 0.0918,-0.66797 z m -5.82032,0.26758 c -0.0816,-0.008 -0.18983,0.0196 -0.20117,0.0234 l -2.10156,1.01954 c -0.23206,0.13266 -0.26909,0.10921 -0.42383,0.24414 -0.15458,0.13682 -0.0114,0.16173 0.12696,0.16211 0.26416,6.4e-4 2.29504,-1.01883 2.63671,-1.27735 0.0994,-0.12623 0.0449,-0.16387 -0.0371,-0.16992 z m 3.91016,0.0547 c 0.22434,0.0596 0.44671,0.10116 0.67188,0.16993 0.32835,0.13902 0.62159,0.24548 0.91015,0.34765 -0.0222,0.19558 -0.0333,0.39599 -0.0508,0.59375 -0.27242,-0.0858 -0.54753,-0.16342 -0.81836,-0.2539 -0.25115,-0.0814 -0.50275,-0.15016 -0.75391,-0.21485 0.01,-0.21655 0.0274,-0.42816 0.041,-0.64258 z m 3.71289,0.15235 c 0.2384,0.0463 0.46914,0.0847 0.69922,0.12305 -0.0286,0.22624 -0.0625,0.50047 -0.0918,0.74218 -0.24602,-0.049 -0.49169,-0.0998 -0.73437,-0.1582 0.0432,-0.23516 0.0794,-0.47492 0.12695,-0.70703 z m -6.0332,0.26367 c 0.0911,0.007 0.18116,0.0117 0.32422,0.0332 0.0104,0.18065 0.0142,0.35898 0.0293,0.54102 0.007,0.0799 0.0105,0.16028 0.0176,0.24023 -0.14637,-0.0208 -0.23041,-0.0373 -0.32617,-0.0547 -0.0102,-0.12388 -0.0311,-0.52924 -0.0449,-0.75977 z m 0.54297,0.0664 c 0.50192,0.0809 1.00586,0.18573 1.51172,0.30859 -0.004,0.14889 -0.0146,0.2952 -0.0156,0.44531 8e-5,0.0977 -0.004,0.19531 -0.004,0.29297 -0.48076,-0.11476 -0.9626,-0.19303 -1.44336,-0.26562 -0.0155,-0.11595 -0.0216,-0.20986 -0.0391,-0.33008 -0.009,-0.15282 -0.002,-0.29925 -0.01,-0.45117 z m 3.5664,0.11523 h 0.002 c 0.56834,0.19209 1.06007,0.31162 1.52734,0.41016 -0.0332,0.18955 -0.0571,0.38427 -0.0859,0.57617 -0.50461,-0.12323 -1.00554,-0.25743 -1.5,-0.41016 0.0186,-0.19232 0.0349,-0.38572 0.0566,-0.57617 z m -11.13867,0.0371 -1.42773,0.56445 0.12109,0.13672 1.42188,-0.54883 z m 5.45899,0.0977 -1.30664,0.65039 c -0.61599,0.29518 -1.18063,0.58853 -1.25391,0.65429 v 0.002 c -0.0673,0.16932 -0.015,0.20936 0.0625,0.2207 0.28233,-0.22639 2.16708,-0.99679 2.58203,-1.34375 z m 3.83593,0.11132 c 0.22876,0.0583 0.45589,0.10007 0.68555,0.16797 0.31733,0.1301 0.60221,0.22882 0.88086,0.32422 -0.0109,0.13923 -0.0288,0.27558 -0.0371,0.41602 -0.005,0.0945 -0.0144,0.18872 -0.0195,0.2832 -0.26456,-0.0831 -0.53194,-0.15846 -0.79492,-0.24609 -0.24306,-0.0786 -0.48546,-0.14476 -0.72852,-0.20703 -0.006,-0.13461 -0.002,-0.24425 -0.01,-0.38477 0.003,-0.1202 0.0188,-0.23398 0.0234,-0.35352 z m -9.09375,0.19532 -1.42773,0.56445 0.12109,0.13672 1.41992,-0.55078 z m 12.69922,0.0215 c 0.25516,0.0499 0.50234,0.0919 0.74805,0.13281 -0.0247,0.20424 -0.0503,0.40702 -0.0762,0.61914 -0.26093,-0.0528 -0.51702,-0.11958 -0.77539,-0.17968 0.0309,-0.19319 0.0696,-0.38117 0.10351,-0.57227 z m 2.1543,0.28125 -0.0801,0.17188 3.99805,0.58789 0.0879,-0.15821 z m -7.9707,0.002 c 0.0943,0.0183 0.18643,0.0334 0.32812,0.0547 0.0203,0.2347 0.0325,0.47017 0.0508,0.70508 -0.10919,-0.0172 -0.18546,-0.0264 -0.26172,-0.0371 -0.022,-0.12265 -0.10074,-0.50715 -0.10742,-0.56055 -0.002,-0.0142 -0.008,-0.14173 -0.01,-0.16211 z m 3.9746,0.0645 c 0.56497,0.18476 1.03186,0.28419 1.49415,0.37695 -0.0222,0.15685 -0.0514,0.31014 -0.0703,0.46875 -0.009,0.0783 -0.0223,0.15609 -0.0312,0.23438 -0.48208,-0.11668 -0.96127,-0.24174 -1.43359,-0.38672 10e-4,-0.1321 0.01,-0.23907 0.01,-0.37696 0.008,-0.10663 0.0218,-0.21036 0.0312,-0.3164 z m -3.41796,0.0254 c 0.47159,0.0762 0.9447,0.17431 1.41992,0.28906 -8.7e-4,0.23117 -0.009,0.46215 -0.0117,0.69336 -0.44201,-0.11631 -0.88417,-0.1945 -1.32617,-0.26953 -0.0232,-0.22789 -0.0507,-0.46714 -0.082,-0.71289 z m -7.27539,0.0312 -1.42774,0.56445 0.12109,0.13477 1.41993,-0.54883 z m 8.92187,0.3125 c 0.21517,0.0549 0.42853,0.0945 0.64453,0.1582 0.30878,0.12624 0.58681,0.22429 0.85742,0.31641 -0.0134,0.23715 -0.0333,0.47385 -0.0488,0.71094 -0.25022,-0.0875 -0.5032,-0.16754 -0.75196,-0.25977 -0.22728,-0.0818 -0.45436,-0.15153 -0.68164,-0.2168 -0.002,-0.22484 -0.011,-0.46625 -0.0195,-0.70898 z m 3.47656,0.0488 c 0.2603,0.0487 0.53439,0.10857 0.78711,0.15039 -0.0316,0.25695 -0.0572,0.48184 -0.0918,0.74609 -0.2694,-0.0491 -0.52962,-0.12454 -0.79493,-0.18555 0.007,-0.10629 0.0191,-0.1907 0.0254,-0.30078 0.0198,-0.1401 0.0528,-0.27117 0.0742,-0.41015 z m 2.17578,0.0273 -0.0801,0.17188 3.99804,0.58593 0.0879,-0.15625 z m -7.70312,0.39453 c 0.0724,0.0114 0.14292,0.019 0.24023,0.0352 0.022,0.29293 0.0467,0.58549 0.0645,0.8789 -0.12439,-0.0186 -0.12691,-0.0225 -0.13477,-0.0273 -0.0671,-0.34147 -0.1283,-0.66195 -0.16992,-0.88672 z m 0.50781,0.082 c 0.43193,0.0787 0.86571,0.17887 1.30078,0.29492 -0.004,0.27226 -0.006,0.54408 -0.0137,0.81641 -0.40797,-0.10108 -0.81467,-0.17012 -1.22266,-0.23633 -0.0164,-0.28049 -0.0353,-0.56632 -0.0644,-0.875 z m 3.26758,0 c 0.53335,0.17163 0.97767,0.26291 1.41602,0.34961 -0.0298,0.25686 -0.0674,0.5129 -0.0996,0.76953 -0.44853,-0.12116 -0.89428,-0.25079 -1.33399,-0.40039 0.01,-0.22687 0.0131,-0.47327 0.0176,-0.71875 z m 3.77734,0.0664 -0.0781,0.17187 3.99805,0.58594 0.0879,-0.15625 z m -14.10937,0.18359 -1.42774,0.56446 0.1211,0.13476 1.42187,-0.54883 z m 8.63281,0.11719 c 0.20063,0.0572 0.40019,0.098 0.60156,0.16406 0.2923,0.13296 0.55382,0.23446 0.81055,0.33203 -0.0171,0.24881 -0.0324,0.49739 -0.0527,0.7461 -0.25056,-0.0819 -0.50294,-0.15761 -0.75196,-0.24414 -0.20816,-0.0702 -0.41684,-0.12895 -0.625,-0.18555 0.008,-0.26309 0.0182,-0.52392 0.0176,-0.8125 z m 3.33399,0.0254 c 0.24521,0.045 0.50743,0.10521 0.74414,0.14258 l 0.0625,-0.10352 c -0.0408,0.31041 -0.10209,0.62462 -0.14844,0.93946 -0.24606,-0.0505 -0.48392,-0.12596 -0.72656,-0.1875 0.0257,-0.25037 0.0481,-0.51734 0.0684,-0.79102 z m 2.01367,0.24414 -0.0781,0.17188 3.99805,0.58593 0.0879,-0.1582 z m -13.7793,0.0176 -1.42773,0.56445 0.11914,0.13477 1.42187,-0.54883 z m 10.10547,0.30859 c 0.49217,0.17447 0.90692,0.27296 1.31445,0.36328 -0.0309,0.24031 -0.0598,0.48068 -0.0937,0.72071 -0.4292,-0.1075 -0.85669,-0.22018 -1.27734,-0.35352 0.0202,-0.23938 0.0428,-0.46967 0.0566,-0.73047 z m -3.54688,0.008 c 0.0188,0.006 0.0257,0.01 0.11329,0.0234 0.0145,0.25428 0.0266,0.50893 0.0371,0.76368 -0.0713,-0.35957 -0.0879,-0.47009 -0.1504,-0.78711 z m 0.37891,0.0664 c 0.40199,0.0699 0.8061,0.15821 1.21094,0.25977 -0.009,0.28122 -0.0187,0.56242 -0.0332,0.84375 -0.38076,-0.0882 -0.76178,-0.16479 -1.14257,-0.22266 -0.004,-0.27647 -0.0196,-0.57887 -0.0352,-0.88086 z m -6.77344,0.041 -1.42773,0.56445 0.11914,0.13672 1.42187,-0.54883 z m 13.47657,0.17578 -0.0801,0.17187 3.99804,0.58789 0.0898,-0.1582 z m -5.23438,0.10937 c 0.18761,0.0503 0.37421,0.0847 0.5625,0.14258 0.29188,0.12448 0.55352,0.22238 0.80859,0.3125 -0.0221,0.25725 -0.0458,0.51438 -0.0723,0.77149 -0.21523,-0.0693 -0.43246,-0.13224 -0.64649,-0.20508 -0.23196,-0.0766 -0.46334,-0.12061 -0.69531,-0.17969 0.02,-0.26414 0.0315,-0.55356 0.043,-0.8418 z m 3.27539,0.0176 c 0.2247,0.0454 0.46612,0.10822 0.68359,0.14649 l 0.0488,-0.0937 c -0.13707,0.92285 -0.28541,1.84537 -0.49804,2.70507 -0.22267,-0.0474 -0.44178,-0.10593 -0.66211,-0.16015 0.0541,-0.24409 0.10445,-0.49939 0.15429,-0.76172 0.17789,0.0323 0.37176,0.0795 0.54493,0.10742 l 0.0684,-0.12109 c -0.19739,-0.036 -0.38742,-0.0945 -0.58204,-0.13867 0.0445,-0.24307 0.0817,-0.5182 0.1211,-0.78321 0.19797,0.0368 0.413,0.0894 0.60547,0.1211 l 0.0742,-0.13477 c -0.22177,-0.0413 -0.43571,-0.10715 -0.65429,-0.1582 0.0333,-0.23641 0.0674,-0.47062 0.0957,-0.72852 z m 1.88867,0.44531 -0.0801,0.17188 3.95313,0.52539 0.0898,-0.1582 z m -3.53906,0.0801 c 0.47531,0.15617 0.87751,0.24383 1.27148,0.32422 -0.0375,0.25858 -0.0734,0.51722 -0.11523,0.77539 -0.41458,-0.10139 -0.82641,-0.21116 -1.23242,-0.33789 0.0301,-0.23852 0.052,-0.5031 0.0762,-0.76172 z m -3.05859,0.15821 c 0.37641,0.0607 0.75373,0.1368 1.13281,0.22656 -0.0145,0.26229 -0.0268,0.5247 -0.0469,0.78711 -0.36295,-0.0772 -0.72493,-0.13791 -1.08789,-0.18946 0.006,-0.26215 0.004,-0.5444 0.002,-0.82421 z m -6.4336,0.0195 -1.42773,0.56445 0.12109,0.13672 1.42188,-0.55078 z m 7.8125,0.26757 c 0.21357,0.0543 0.42611,0.0955 0.64063,0.16016 0.25015,0.10443 0.47266,0.18417 0.69336,0.26172 -0.0262,0.24346 -0.0491,0.48716 -0.0801,0.73047 -0.13421,-0.0447 -0.27053,-0.0829 -0.4043,-0.12891 -0.30655,-0.10246 -0.61336,-0.16697 -0.91992,-0.23828 0.0278,-0.24944 0.0485,-0.51896 0.0703,-0.78516 z m 5.125,0.008 -0.0801,0.17187 3.89843,0.53516 0.0899,-0.1582 z m -12.73633,0.1289 -1.42773,0.56446 0.11914,0.13476 1.42188,-0.54883 z m 9.1875,0.3711 c 0.46377,0.15175 0.85179,0.23463 1.23243,0.31054 -0.0419,0.25212 -0.0819,0.50423 -0.12891,0.75586 -0.40607,-0.10613 -0.8088,-0.22198 -1.20703,-0.35156 0.037,-0.22819 0.0708,-0.47197 0.10351,-0.71484 z m -9.02343,0.0527 -1.42774,0.56445 0.11914,0.13672 1.42188,-0.54882 z m 12.49804,0.0215 -0.0801,0.17187 3.84375,0.53125 0.0898,-0.1582 z m -6.43554,0.0937 c 0.35822,0.0528 0.71743,0.1135 1.07812,0.19336 -0.0175,0.2165 -0.0387,0.43379 -0.0605,0.65039 -0.30252,-0.0596 -0.60556,-0.10288 -0.90821,-0.14454 -0.0397,-0.21227 -0.0679,-0.37019 -0.11328,-0.60546 9.3e-4,-0.0317 0.003,-0.062 0.004,-0.0937 z m 1.29883,0.25 c 0.29061,0.069 0.5806,0.13156 0.87304,0.2207 0.15988,0.0675 0.29651,0.11249 0.44336,0.16797 -0.0264,0.19998 -0.0597,0.39975 -0.0898,0.59961 -0.107,-0.0343 -0.21555,-0.0645 -0.32227,-0.0996 -0.32902,-0.10512 -0.6573,-0.17378 -0.98633,-0.24414 0.0279,-0.21303 0.0566,-0.42467 0.082,-0.64453 z m 5.06445,0.2539 -0.0801,0.17188 3.75,0.54883 0.0898,-0.15821 z m -3.53125,0.2168 c 0.44924,0.1598 0.83558,0.26297 1.19922,0.34375 -0.0366,0.1905 -0.0792,0.38013 -0.11914,0.57031 -0.39887,-0.10142 -0.7942,-0.21303 -1.18555,-0.33594 0.0351,-0.19193 0.0722,-0.38 0.10547,-0.57812 z m 3.40234,0.33594 -0.0801,0.17187 3.7168,0.59375 0.0898,-0.1582 z m -1.98047,0.0527 c 0.22305,0.0448 0.45024,0.0945 0.66602,0.13281 -0.052,0.20405 -0.11595,0.38915 -0.17383,0.58399 -0.2106,-0.0454 -0.41997,-0.0942 -0.6289,-0.14453 0.046,-0.18919 0.0922,-0.37626 0.13671,-0.57227 z" + transform="scale(0.26458333)" + id="path3720" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccccccccccccccccccccccccccccccccccccccccccccccccccscccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccscccccccccscccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccacccccccccccccccccccccccccccccccaccccccccccccccccccccccccc" + inkscape:label="dark gray" /> + <path + inkscape:label="orange" + inkscape:connector-curvature="0" + id="path3718" + transform="scale(0.26458333)" + d="m 619.05664,728.89648 c -0.0136,0.21442 -0.031,0.42603 -0.041,0.64258 0.25116,0.0647 0.50276,0.13345 0.75391,0.21485 0.27083,0.0905 0.54594,0.1681 0.81836,0.2539 0.0175,-0.19776 0.0286,-0.39817 0.0508,-0.59375 -0.28856,-0.10217 -0.5818,-0.20863 -0.91015,-0.34765 -0.22517,-0.0688 -0.44754,-0.11033 -0.67188,-0.16993 z" + style="fill:#f8f1d7;fill-opacity:1;stroke:none;stroke-width:0.99999994px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + inkscape:label="yellow" + inkscape:connector-curvature="0" + id="path3712" + transform="scale(0.26458333)" + d="m 617.25391,726.72852 c -0.006,0.21727 -0.0195,0.43141 -0.0215,0.65039 0.56362,0.0855 1.12584,0.17683 1.68946,0.3164 0.0213,-0.20373 0.0532,-0.40319 0.0781,-0.60547 -0.58462,-0.148 -1.1665,-0.26862 -1.74609,-0.36132 z" + style="fill:#ebeca1;fill-opacity:1;stroke:none;stroke-width:0.99999994px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + inkscape:label="green" + style="display:inline;fill:#218f21;stroke-width:0.08466666" + d="m 162.66447,193.95371 c -0.13988,-0.50689 -0.14183,-0.55038 -0.0263,-0.58889 0.0531,-0.0177 0.11799,0.10907 0.14812,0.28928 0.0295,0.17642 0.0771,0.4065 0.10589,0.51127 0.0289,0.1052 0.0144,0.1905 -0.0322,0.1905 -0.0465,0 -0.13443,-0.18097 -0.19547,-0.40216 z" + id="path3221" + inkscape:connector-curvature="0" /> + <path + inkscape:label="red" + sodipodi:nodetypes="ccscc" + style="display:inline;fill:#fe2e2e;stroke-width:0.08466666" + d="m 162.50287,194.46906 c -0.10611,-0.23139 -0.0911,-0.43226 -0.20126,-0.64538 0.0463,-0.0286 0.0882,-0.0701 0.12291,-0.0488 0.12358,0.0755 0.22998,0.52277 0.26279,0.66028 -0.11606,0.0585 -0.16428,0.0872 -0.18444,0.0339 z" + id="path3227" + inkscape:connector-curvature="0" /> + <path + inkscape:connector-curvature="0" + id="path3703" + d="m 165.0721,192.24716 c 0.11577,0.0167 0.70155,0.0255 0.88925,0.008 0.29837,-0.0217 1.00383,0.23252 1.24429,0.39042 0.0395,0.026 0.0216,0.15484 0.0212,0.18099 -0.0511,0.18658 -0.12311,0.12376 -0.47112,-0.0651 -0.17463,-0.0876 -0.58023,-0.18528 -0.90134,-0.21701 -0.3211,-0.0317 -0.66675,-0.0217 -0.73477,-0.0379 -0.068,-0.0162 -0.13557,5.4e-4 -0.0475,-0.25905 z m -4.43342,0.29225 c 0,-0.0999 -0.0618,-0.16543 -0.006,-0.22131 0.20363,-0.0637 0.29492,0.0258 0.57742,-0.17089 0.47957,-0.32451 1.07497,-0.58353 1.49778,-0.58535 0.34961,0 0.42224,0.0139 0.42224,0.10294 0,0.066 -0.029,0.153 -0.029,0.153 -0.0793,0.10437 -0.26688,0.0348 -0.43805,0.0683 -0.33023,0 -0.61963,0.10946 -0.91305,0.34359 -0.15568,0.12422 -0.26659,0.15663 -0.5092,0.23876 -0.44106,0.14931 -0.60233,0.25267 -0.60233,0.071 z m 3.62077,-1.17593 c -0.28458,-0.19709 -0.19911,-0.006 -0.78444,-0.017 -0.88366,-0.0172 -0.889,-0.0182 -0.889,-0.16053 0,-0.0952 0.12051,-0.11835 0.55038,-0.10584 0.30271,0.009 0.4036,-0.002 0.55033,-0.0475 0.062,-0.0266 0.17179,-0.0439 0.26948,-0.048 0.22225,-0.009 0.42781,0.0952 0.60128,0.27927 0.0961,0.0952 0.2389,0.31165 0.28835,0.28548 0.0348,0.0267 0.26569,-0.16317 0.39854,-0.24475 0.2255,-0.1511 0.43624,-0.23203 0.47979,-0.20512 0.0763,0.17481 0.0942,0.16525 0.0388,0.21343 -0.0555,0.0482 -0.18423,0.15408 -0.41773,0.29118 -0.41995,0.20046 -0.53647,0.39532 -1.08572,-0.24064 z" + style="display:inline;fill:#2e51a8;stroke-width:0.08466666" + sodipodi:nodetypes="ccsccczcccccsccccccccsccsccccscccc" + inkscape:label="blue" /> + </g> + </g> +</svg> diff --git a/src/documentation/resources/images/project-header.xcf b/src/documentation/resources/images/project-header.xcf Binary files differnew file mode 100644 index 0000000000..e99dea60b8 --- /dev/null +++ b/src/documentation/resources/images/project-header.xcf diff --git a/src/documentation/resources/images/remove.jpg b/src/documentation/resources/images/remove.jpg Binary files differnew file mode 100644 index 0000000000..e18d135b35 --- /dev/null +++ b/src/documentation/resources/images/remove.jpg diff --git a/src/documentation/resources/images/simple-xls-with-function.jpg b/src/documentation/resources/images/simple-xls-with-function.jpg Binary files differnew file mode 100644 index 0000000000..d5879ae026 --- /dev/null +++ b/src/documentation/resources/images/simple-xls-with-function.jpg diff --git a/src/documentation/resources/images/ss-features.png b/src/documentation/resources/images/ss-features.png Binary files differnew file mode 100644 index 0000000000..17554c7151 --- /dev/null +++ b/src/documentation/resources/images/ss-features.png diff --git a/src/documentation/resources/images/support-asf.png b/src/documentation/resources/images/support-asf.png Binary files differnew file mode 100644 index 0000000000..2103fc6d05 --- /dev/null +++ b/src/documentation/resources/images/support-asf.png diff --git a/src/documentation/resources/images/timesheet.jpg b/src/documentation/resources/images/timesheet.jpg Binary files differnew file mode 100644 index 0000000000..1ff512b1f9 --- /dev/null +++ b/src/documentation/resources/images/timesheet.jpg diff --git a/src/documentation/resources/images/unknown.jpg b/src/documentation/resources/images/unknown.jpg Binary files differnew file mode 100644 index 0000000000..75f357e6c2 --- /dev/null +++ b/src/documentation/resources/images/unknown.jpg diff --git a/src/documentation/resources/images/usermodel.gif b/src/documentation/resources/images/usermodel.gif Binary files differnew file mode 100644 index 0000000000..4f4c3606c3 --- /dev/null +++ b/src/documentation/resources/images/usermodel.gif diff --git a/src/documentation/resources/images/utilClasses.gif b/src/documentation/resources/images/utilClasses.gif Binary files differnew file mode 100644 index 0000000000..5cb07b79a5 --- /dev/null +++ b/src/documentation/resources/images/utilClasses.gif diff --git a/src/documentation/resources/images/vba-example.jpg b/src/documentation/resources/images/vba-example.jpg Binary files differnew file mode 100644 index 0000000000..0d95b90001 --- /dev/null +++ b/src/documentation/resources/images/vba-example.jpg diff --git a/src/documentation/resources/schema/catalog.xcat b/src/documentation/resources/schema/catalog.xcat new file mode 100644 index 0000000000..6df85e9583 --- /dev/null +++ b/src/documentation/resources/schema/catalog.xcat @@ -0,0 +1,23 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" +"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"> + +<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="public"> + <public publicId="-//APACHE//DTD Changes POI//EN" uri="changes-poi.dtd"/> +</catalog>
\ No newline at end of file diff --git a/src/documentation/resources/schema/changes-poi.dtd b/src/documentation/resources/schema/changes-poi.dtd new file mode 100644 index 0000000000..a652647433 --- /dev/null +++ b/src/documentation/resources/schema/changes-poi.dtd @@ -0,0 +1,71 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- =================================================================== + + Apache Changes POI DTD + +PURPOSE: + This DTD was developed to create a simple yet powerful document + type for software development changes for use with the Apache projects. + It is an XML-compliant DTD and it's maintained by the Apache POI + project. + +TYPICAL INVOCATION: + + <!DOCTYPE document PUBLIC + "-//APACHE//DTD Changes POI//EN" + "changes-poi.dtd"> + +NOTES: + It is important, expecially in open developped software projects, to keep + track of software changes both to give users indications of bugs that might + have been resolved, as well, and not less important, to provide credits + for the support given to the project. It is considered vital to provide + adequate payback using recognition and credits to let users and developers + feel part of the community, thus increasing development power. +==================================================================== --> + +<!-- =============================================================== --> +<!-- Include the Documentation DTD --> +<!-- =============================================================== --> + +<!ENTITY % document PUBLIC + "-//APACHE//ENTITIES Documentation V2.0//EN" + "document-v20.mod"> +%document; + +<!-- =============================================================== --> +<!-- Include the Common ISO Character Entity Sets --> +<!-- =============================================================== --> + +<!ENTITY % common-charents PUBLIC + "-//APACHE//ENTITIES Common Character Entity Sets V1.0//EN" + "common-charents-v10.mod"> +%common-charents; + +<!-- =============================================================== --> +<!-- Include the Changes module --> +<!-- =============================================================== --> + +<!ENTITY % changes PUBLIC + "-//APACHE//ENTITIES Changes POI//EN" + "changes-poi.mod"> +%changes; + +<!-- =============================================================== --> +<!-- End of DTD --> +<!-- =============================================================== --> diff --git a/src/documentation/resources/schema/changes-poi.mod b/src/documentation/resources/schema/changes-poi.mod new file mode 100644 index 0000000000..36428fa15c --- /dev/null +++ b/src/documentation/resources/schema/changes-poi.mod @@ -0,0 +1,81 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- =================================================================== + Apache Changes POI Module +PURPOSE: + This DTD was developed to create a simple yet powerful document + type for software development changes for use with the Apache projects. + It is an XML-compliant DTD and it's maintained by the Apache XML + project. +TYPICAL INVOCATION: + <!ENTITY % changes PUBLIC + "-//APACHE//ENTITIES Changes POI//EN" + "changes-poi.mod"> + %changes; +NOTES: + It is important, expecially in open developped software projects, to keep + track of software changes both to give users indications of bugs that mig + have been resolved, as well, and not less important, to provide credits + for the support given to the project. It is considered vital to provide + adequate payback using recognition and credits to let users and developer + feel part of the community, thus increasing development power. +==================================================================== --> + +<!-- =============================================================== --> +<!-- Document Type Definition --> +<!-- =============================================================== --> +<!ELEMENT changes (contexts, section?, release+)> +<!ATTLIST changes %common.att;> + +<!ELEMENT contexts (context+)> +<!ELEMENT context EMPTY> +<!ATTLIST context %common-idreq.att; + %title.att;> + +<!ELEMENT release (summary?,actions)> +<!ATTLIST release %common.att; + version CDATA #REQUIRED + date CDATA #REQUIRED> + +<!ELEMENT summary (summary-item+)> +<!ELEMENT summary-item (%content.mix;|bug)*> + +<!ELEMENT actions (action+)> +<!ELEMENT action (%content.mix;|bug)*> + +<!ENTITY % types "add|remove|update|fix"> +<!ENTITY % importances "enhancement|trivial|minor|normal|major|critical|blocker"> + + +<!ATTLIST action + %common.att; + type (%types;) #IMPLIED + context IDREFS #REQUIRED + importance (%importances;) "normal" + due-to CDATA #IMPLIED + due-to-email CDATA #IMPLIED + fixes-bug CDATA #IMPLIED + breaks-compatibility (true|false) #IMPLIED> + +<!ELEMENT bug EMPTY> +<!ATTLIST bug %common.att; + num CDATA #REQUIRED> + + +<!-- =============================================================== --> +<!-- End of DTD --> +<!-- =============================================================== --> diff --git a/src/documentation/resources/stylesheets/changes2document.xsl b/src/documentation/resources/stylesheets/changes2document.xsl new file mode 100644 index 0000000000..6cf0a13b4a --- /dev/null +++ b/src/documentation/resources/stylesheets/changes2document.xsl @@ -0,0 +1,210 @@ +<?xml version="1.0"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> + +<xsl:stylesheet + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + + <xsl:param name="bugtracking-url">https://bz.apache.org/bugzilla/</xsl:param> + <!-- FIXME : Get the Github URL from properties --> + <xsl:variable name="github-url">https://github.com/apache/poi</xsl:variable> + + <xsl:variable name="bugdetails" select="concat($bugtracking-url, 'show_bug.cgi?id=')"/> + <xsl:variable name="buglist" select="concat($bugtracking-url, 'buglist.cgi?bug_id=')"/> + + <xsl:template match="a"> + <!-- FIXME! This doesn't work for href or name. Use the externally defined link->a transform if possible --> + <a href="{@href}"> + <xsl:apply-templates/> + </a> + </xsl:template> + + <!-- usage: <bug num="12345"/> or <bug num="12345,12346"/> or <bug num="github-12"/> --> + <xsl:template match="bug"> + <xsl:choose> + <xsl:when test="contains(@num, ',')"> + <a href="{$buglist}{translate(normalize-space(@num),' ','')}"> + <xsl:text></xsl:text><xsl:value-of select="normalize-space( translate(@num, ',', ' ') )"/> + </a> + </xsl:when> + <xsl:otherwise> + <xsl:choose> + <xsl:when test="contains(@num, 'github-')"> + <a href="{$github-url}/pull/{translate(@num,'github-','')}"> + <xsl:text></xsl:text><xsl:value-of select="@num"/> + </a> + </xsl:when> + <xsl:otherwise> + <a href="{$bugdetails}{@num}"> + <xsl:text></xsl:text><xsl:value-of select="@num"/> + </a> + </xsl:otherwise> + </xsl:choose> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <xsl:template match="devs"/> + + <xsl:template match="changes"> + <document> + <header> + <title>History of Changes</title> + </header> + <body> + <xsl:apply-templates/> + </body> + </document> + </xsl:template> + + <xsl:template match="section"> + <xsl:copy-of select="." /> + </xsl:template> + + <xsl:template match="release"> + <section id="{@version}"> + <title>Version + <xsl:value-of select="@version"/> (<xsl:value-of select="@date"/>) + </title> + <xsl:apply-templates/> + </section> + </xsl:template> + + <xsl:template match="summary"> + <section> + <title>Summary</title> + <ul> <!-- create a new list for each noteable change in the summary --> + <xsl:apply-templates/> <!-- summary-item's --> + </ul> + </section> + </xsl:template> + + <xsl:template match="summary-item"> + <li> + <xsl:apply-templates/> + </li> + </xsl:template> + + <xsl:template match="actions"> + <section> + <title>Changes</title> + <table class="POITable"> + <colgroup> + <col width="100" /> + <col width="200" /> + <col width="150" /> + <col/> + </colgroup> + <thead> + <tr> + <th>Type</th> + <th>Bug</th> + <th>Module</th> + <th>Description</th> + </tr> + </thead> + + <tbody> + <!-- TODO: sort actions by type --> + <xsl:apply-templates/> <!-- action's --> + </tbody> + + </table> + </section> + </xsl:template> + + <xsl:template match="action"> + <tr class="action"> + + <td> + <icon src="images/{@type}.png" alt="{@type}" title="{@type}"/> + </td> + + <td> + <!-- TODO: duplicate code. replace with the <xsl:template match="bug"/> defined above --> + <xsl:if test="@fixes-bug"> + <xsl:choose> + <xsl:when test="contains(@fixes-bug, ',')"> + <a href="{$buglist}{translate(normalize-space(@fixes-bug),' ','')}"> + <xsl:text></xsl:text><xsl:value-of + select="normalize-space( translate(@fixes-bug, ',', ' ') )"/> + </a> + </xsl:when> + <xsl:otherwise> + <xsl:choose> + <xsl:when test="contains(@fixes-bug, 'github-')"> + <a href="{$github-url}/pull/{translate(@fixes-bug,'github-','')}"> + <xsl:text></xsl:text><xsl:value-of select="@fixes-bug"/> + </a> + </xsl:when> + <xsl:otherwise> + <a href="{$bugdetails}{@fixes-bug}"> + <xsl:text></xsl:text><xsl:value-of select="@fixes-bug"/> + </a> + </xsl:otherwise> + </xsl:choose> + </xsl:otherwise> + </xsl:choose> + </xsl:if> + </td> + + <td> + <!-- FIXME: is there any way that the module can be fetched from bugzilla using each bug's component? --> + <xsl:if test="@context"> + <xsl:value-of select="@context"/> + </xsl:if> + </td> + + <td> + + <!-- description: bold any backwards-breaking changes --> + <xsl:choose> + <xsl:when test="@breaks-compatibility"> + <b> + <xsl:apply-templates/> + <xsl:text> (breaks backwards compatibility)</xsl:text> + </b> + </xsl:when> + <xsl:otherwise> + <xsl:apply-templates/> + </xsl:otherwise> + </xsl:choose> + + <!-- thanks --> + <xsl:if test="@due-to and @due-to!=''"> + <xsl:text> Thanks to </xsl:text> + <xsl:choose> + <xsl:when test="@due-to-email and @due-to-email!=''"> + <a href="mailto:{@due-to-email}"> + <xsl:value-of select="@due-to"/> + </a> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="@due-to"/> + </xsl:otherwise> + </xsl:choose> + <xsl:text>.</xsl:text> + </xsl:if> + </td> + + </tr> + </xsl:template> + +</xsl:stylesheet> diff --git a/src/documentation/resources/stylesheets/snipplets2document.xsl b/src/documentation/resources/stylesheets/snipplets2document.xsl new file mode 100644 index 0000000000..8b428360e3 --- /dev/null +++ b/src/documentation/resources/stylesheets/snipplets2document.xsl @@ -0,0 +1,65 @@ +<?xml version="1.0"?> +<!-- + ==================================================================== + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + ==================================================================== +--> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" + xmlns:ext="http://exslt.org/common" + xmlns:math="http://exslt.org/math" + exclude-result-prefixes="ext math" +> + + <!-- the obligatory copy-everything --> + <xsl:template match="node() | @*"> + <xsl:copy> + <xsl:apply-templates select="@*"/> + <xsl:apply-templates/> + </xsl:copy> + </xsl:template> + + <xsl:variable name="ASCII">!"#$%&'()*+,-./0123456789:;=&<>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[]^_`abcdefghijklmnopqrstuvwxyz{|}~</xsl:variable> + <xsl:variable name="DOTS">..............................................................................................</xsl:variable> + + <xsl:template match="source"> + + <xsl:variable name="codelines"> + <xsl:apply-templates mode="source"/> + </xsl:variable> + + <xsl:variable name="indent" select="string-length(substring-before(translate(text(),$ASCII,$DOTS),'.'))"/> + + <div class="code"> + <xsl:for-each select="ext:node-set($codelines)/*"> + <div class="codeline"><span class="lineno"></span><span class="codebody"><xsl:value-of select="substring(.,$indent)"/></span></div> + </xsl:for-each> + </div> + </xsl:template> + + <xsl:template match="text()" name="split" mode="source"> + <xsl:param name="pText" select="."/> + <xsl:if test="string-length($pText) >0"> + <line> + <xsl:value-of select="substring-before(concat($pText, ' '), ' ')"/> + </line> + + <xsl:call-template name="split"> + <xsl:with-param name="pText" select="substring-after($pText, ' ')"/> + </xsl:call-template> + </xsl:if> + </xsl:template> +</xsl:stylesheet> diff --git a/src/documentation/sitemap.xmap b/src/documentation/sitemap.xmap new file mode 100644 index 0000000000..e7e03a57cd --- /dev/null +++ b/src/documentation/sitemap.xmap @@ -0,0 +1,56 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"> + <map:components> + <map:selectors default="parameter"> + <map:selector logger="sitemap.selector.parameter" + name="parameter" src="org.apache.cocoon.selection.ParameterSelector"/> + </map:selectors> + <map:actions> + <map:action logger="sitemap.action.sourcetype" name="sourcetype" + src="org.apache.forrest.sourcetype.SourceTypeAction"> + <sourcetype name="document-v20"> + <document-declaration public-id="-//APACHE//DTD Documentation V2.0//EN"/> + </sourcetype> + </map:action> + </map:actions> + </map:components> + + <map:pipelines> + <map:pipeline> + <map:match type="regexp" pattern="(.*/?changes.*)\.xml"> + <map:generate src="{properties:content.xdocs}{1}.xml"/> + <map:transform src="{properties:resources.stylesheets}/changes2document.xsl"/> + <map:serialize type="xml"/> + </map:match> + + <map:match type="regexp" pattern="(.*/.*|encryption|index|download|legal|news|related-projects|text-extraction)\.xml"> + <map:generate src="{properties:content.xdocs}{1}.xml"/> + <map:act type="sourcetype" src="{properties:content.xdocs}{1}.xml"> + <map:select type="parameter"> + <map:parameter name="parameter-selector-test" value="{sourcetype}"/> + <map:when test="document-v20"> + <map:transform src="{properties:resources.stylesheets}/snipplets2document.xsl"/> + </map:when> + </map:select> + </map:act> + <map:serialize type="xml"/> + </map:match> + </map:pipeline> + </map:pipelines> +</map:sitemap> diff --git a/src/documentation/skinconf.xml b/src/documentation/skinconf.xml new file mode 100644 index 0000000000..fe11a72134 --- /dev/null +++ b/src/documentation/skinconf.xml @@ -0,0 +1,549 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- +Skin configuration file. This file contains details of your project, +which will be used to configure the chosen Forrest skin. +--> +<!DOCTYPE skinconfig PUBLIC "-//APACHE//DTD Skin Configuration V0.8-2//EN" + "http://forrest.apache.org/dtd/skinconfig-v08-2.dtd"> + +<skinconfig> + <!-- To enable lucene search add provider="lucene" (default is google). + Add box-location="alt" to move the search box to an alternate location + (if the skin supports it) and box-location="all" to show it in all + available locations on the page. Remove the <search> element to show + no search box. @domain will enable sitesearch for the specific domain with google. + In other words google will search the @domain for the query string. + --> + <search name="Apache POI" domain="poi.apache.org" provider="google" box-location="default"/> + <!-- Disable the print link? If enabled, invalid HTML 4.0.1 --> + <disable-print-link>true</disable-print-link> + <!-- Disable the PDF link? --> + <disable-pdf-link>true</disable-pdf-link> + <!-- Disable the POD link? --> + <disable-pod-link>true</disable-pod-link> + <!-- Disable the Text link? FIXME: NOT YET IMPLEMENETED. --> + <disable-txt-link>true</disable-txt-link> + <!-- Disable the xml source link? --> + <!-- The xml source link makes it possible to access the xml rendition + of the source frim the html page, and to have it generated statically. + This can be used to enable other sites and services to reuse the + xml format for their uses. Keep this disabled if you don't want other + sites to easily reuse your pages.--> + <disable-xml-link>true</disable-xml-link> + <!-- Disable navigation icons on all external links? --> + <disable-external-link-image>true</disable-external-link-image> + <!-- Disable w3c compliance links? + Use e.g. align="center" to move the compliance links logos to + an alternate location default is left. + (if the skin supports it) --> + <disable-compliance-links>false</disable-compliance-links> + <!-- Render mailto: links unrecognisable by spam harvesters? --> + <obfuscate-mail-links>true</obfuscate-mail-links> + <obfuscate-mail-value>.at.</obfuscate-mail-value> + <!-- Disable the javascript facility to change the font size --> + <disable-font-script>true</disable-font-script> + <!-- mandatory project logo + default skin: renders it at the top --> + <project-name>Apache POI</project-name> + <project-description>Apache POI is well-known in the Java field as a library for reading and writing Microsoft Office file formats, such as Excel, PowerPoint, Word, Visio, Publisher and Outlook. It supports both the older (OLE2) and new (OOXML - Office Open XML) formats.</project-description> + <project-url>https://poi.apache.org</project-url> + <project-logo>images/project-header.png</project-logo> + <!-- optional group logo + default skin: renders it at the top-left corner --> + <group-name>Apache Software Foundation</group-name> + <group-description>The Apache Software Foundation is a cornerstone of the modern Open Source software ecosystem – supporting some of the most widely used and important software solutions powering today's Internet economy.</group-description> + <group-url>https://www.apache.org</group-url> + <group-logo>images/group-logo.png</group-logo> + <!-- optional host logo (e.g. sourceforge logo) + default skin: renders it at the bottom-left corner --> + <host-url></host-url> + <host-logo></host-logo> + <!-- relative url of a favicon file, normally favicon.ico --> + <favicon-url>images/favicon.ico</favicon-url> + <!-- The following are used to construct a copyright statement --> + <disable-copyright-footer>false</disable-copyright-footer> + <!-- @inception enable automatic generation of a date-range to current date --> + <year inception="true">2001</year> + <vendor>The Apache Software Foundation</vendor> + <!-- The optional copyright-link URL will be used as a link in the + copyright statement --> + <copyright-link>https://www.apache.org/</copyright-link> + <!-- Optional text trademark statement below the copyright statement --> + <trademark-statement> + Apache, Apache POI, the Apache feather logo, and the Apache POI + logos are trademarks of The Apache Software Foundation. + </trademark-statement> + <!-- Some skins use this to form a 'breadcrumb trail' of links. + Use location="alt" to move the trail to an alternate location + (if the skin supports it). + Omit the location attribute to display the trail in the default location. + Use location="none" to not display the trail (if the skin supports it). + For some skins just set the attributes to blank. + + NOTE: If a breadcrumb entry points at a local file the href must + be complete, that is it must point to the file itself, not to a + directory. + --> + <trail> + <link1 name="Apache Software Foundation" href="https://www.apache.org"/> + <link2 name="Apache POI" href="https://poi.apache.org"/> + <link3 name="" href=""/> + </trail> + <!-- Configure the TOC, i.e. the Table of Contents. + @max-depth + how many "section" levels need to be included in the + generated Table of Contents (TOC). + @min-sections + Minimum required to create a TOC. + @location ("page","menu","page,menu", "none") + Where to show the TOC. + --> + <toc max-depth="2" min-sections="1" location="none"/> + <!-- Heading types can be clean|underlined|boxed --> + <headings type="boxed"/> + <!-- The optional feedback element will be used to construct a + feedback link in the footer with the page pathname appended: + <a href="@href">{@to}</a> + --> + <feedback to="dev@poi.apache.org" + href="mailto:dev@poi.apache.org?subject=Feedback "> + Send feedback about the website to: + </feedback> + <!-- Optional message of the day (MOTD). + Note: This is only implemented in the pelt skin. + Note: Beware issue FOR-677 if you use an absolute path uri. + If the optional <motd> element is used, then messages will be appended + depending on the URI string pattern. + motd-option : Each option will match a pattern and apply its text. + The "pattern" attribute specifies the pattern to be matched. + This can be a specific page, or a general pattern to match a set of pages, + e.g. everything in the "samples" directory. + The @starts-with=true anchors the string to the start, otherwise contains + motd-title : This text will be added in brackets after the <html><title> + and this can be empty. + motd-page : This text will be added in a panel on the face of the page, + with the "motd-page-url" being the hyperlink "More". + Values for the "location" attribute are: + page : on the face of the page, e.g. in the spare space of the toc + alt : at the bottom of the left-hand navigation panel + both : both + --> + <!-- + <motd> + <motd-option pattern="samples/sample.html"> + <motd-title>sample</motd-title> + <motd-page location="both"> + This is an example of a Message of the day (MOTD). + </motd-page> + <motd-page-url>faq.html</motd-page-url> + </motd-option> + <motd-option pattern="samples/faq.html"> + <motd-page location="page"> + How to enable this MOTD is on this page. + </motd-page> + <motd-page-url>http://forrest.apache.org/docs/faq.html</motd-page-url> + </motd-option> + </motd> + --> + <!-- + extra-css - here you can define custom css-elements that are + A) overriding the fallback elements or + B) adding the css definition from new elements that you may have + used in your documentation. + --> + <extra-css> + <!--Example of reason B: + To define the css definition of a new element that you may have used + in the class attribute of a <p> node. + e.g. <p class="quote"/> + --> + p.quote { + margin-left: 2em; + padding: .5em; + background-color: #f0f0f0; + font-family: monospace; + } + <!--Example: + To override the colours of links only in the footer. + --> + #footer a { color: #0F3660; } + #footer a:visited { color: #009999; } + #top .projectlogo { float: none; text-align: center; width: auto; } + #menu { width: 200px } + #content { padding-left: 230px } + #content table.autosize { width: auto; } + #credit2 img { margin-top: 20px } + + .boxed { padding-left: 10px; border-radius: 10px 0px; } + h2.boxed { color: white; background-color: #036; } + h3.boxed { color: white; background-color: #888; } + table.POITable th { background-color: #bbb !important } + table.POITable tr:nth-child(even) { background-color: #ddd } + table.POITable tr:nth-child(odd) { background-color: #efefef } + .feature-yes { background-color: #9f9 } + .feature-na { background-color: #ddf } + .feature-no { background-color: #f99 } + + li.pro, li.con { + list-style: none; + padding-left: 0.7em; + text-indent: -0.3em; + } + + li.pro::before, li.con::before { + content: "\00a0"; + font-weight: bold; + display: inline-block; + width: 1em; + margin-left: -1em; + margin-right: 0.3em; + background-repeat: no-repeat; + background-position: center; + } + + li.pro::before { + background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path fill='green' d='M16.59 7.58L10 14.17l-3.59-3.58L5 12l5 5 8-8zM12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm0 18c-4.42 0-8-3.58-8-8s3.58-8 8-8 8 3.58 8 8-3.58 8-8 8z'/></svg>"); + } + + + li.con::before { + background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path fill='red' d='M12 2C6.47 2 2 6.47 2 12s4.47 10 10 10 10-4.47 10-10S17.53 2 12 2zm0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8zm3.59-13L12 10.59 8.41 7 7 8.41 10.59 12 7 15.59 8.41 17 12 13.41 15.59 17 17 15.59 13.41 12 17 8.41z'></path></svg>"); + } + + /* Bare bones style for the desired effect */ + div.code { + display: table; + white-space: pre-wrap; + border: solid 1px black; + font-family: monospace; + } + + div.code::before { + counter-reset: linenum; + } + + div.codeline { + display: table-row; + counter-increment: linenum; + } + + span.lineno { + display: table-cell; + user-select: none; + -moz-user-select: none; + -webkit-user-select: none; + width: 4em; + background: #f0f0f0; + padding: 3px; + padding-top: 0px; + border-right: solid 1px silver; + border-top: solid 1px silver; + } + + span.lineno::before { + content: counter(linenum) "."; + text-align: right; + display: block; + font-size: 90%; + color: #999; + } + + span.codebody { + display: table-cell; + padding: 3px 5em 3px 1em; + background: white; + } + + div.code div.codeline:nth-child(odd) .codebody { + background: #f0f8ff; + } + + dd { + margin-bottom: 1em; + } + + tr.action td:nth-child(1), tr.action td:nth-child(2), tr.action td:nth-child(3) { + text-align: center; + } + + .sebb, a.sebb:link, a.sebb:visited { + color: white; + } + </extra-css> + <colors> + <!-- These values are used for the generated CSS files. + They essentially "override" the default colors defined in the chosen skin. + There are four duplicate "groups" of colors below, denoted by comments: + Color group: Forrest, Krysalis, Collabnet, and Lenya using Pelt. + They are provided for example only. To customize the colors of any skin, + uncomment one of these groups of color elements and change the values + of the particular color elements that you wish to change. + Note that by default, all color groups are commented-out which means that + the default colors provided by the skin are being used. + --> + <!-- Color group: Forrest: example colors similar to forrest.apache.org + Some of the element names are obscure, so comments are added to show how + the "pelt" skin uses them, other skins might use these elements in a different way. + Tip: temporarily change the value of an element to red (#ff0000) and see the effect. + pelt: breadtrail: the strip at the top of the page and the second strip under the tabs + pelt: header: top strip containing project and group logos + pelt: heading|subheading: section headings within the content + pelt: navstrip: the strip under the tabs which contains the published date + pelt: menu: the left-hand navigation panel + pelt: toolbox: the selected menu item + pelt: searchbox: the background of the searchbox + pelt: border: line border around selected menu item + pelt: body: any remaining parts, e.g. the bottom of the page + pelt: footer: the second from bottom strip containing credit logos and published date + pelt: feedback: the optional bottom strip containing feedback link + --> + <!-- + <color name="breadtrail" value="#cedfef" font="#0F3660" link="#0F3660" vlink="#0F3660" hlink="#000066"/> + <color name="header" value="#294563"/> + <color name="tab-selected" value="#4a6d8c" link="#0F3660" vlink="#0F3660" hlink="#000066"/> + <color name="tab-unselected" value="#b5c7e7" link="#0F3660" vlink="#0F3660" hlink="#000066"/> + <color name="subtab-selected" value="#4a6d8c" link="#0F3660" vlink="#0F3660" hlink="#000066"/> + <color name="subtab-unselected" value="#4a6d8c" link="#0F3660" vlink="#0F3660" hlink="#000066"/> + <color name="heading" value="#294563"/> + <color name="subheading" value="#4a6d8c"/> + <color name="published" value="#4C6C8F" font="#FFFFFF"/> + <color name="feedback" value="#4C6C8F" font="#FFFFFF" align="center"/> + <color name="navstrip" value="#4a6d8c" font="#ffffff" link="#0F3660" vlink="#0F3660" hlink="#000066"/> + <color name="menu" value="#4a6d8c" font="#cedfef" link="#ffffff" vlink="#ffffff" hlink="#ffcf00"/> + <color name="toolbox" value="#4a6d8c"/> + <color name="border" value="#294563"/> + <color name="dialog" value="#4a6d8c"/> + <color name="searchbox" value="#4a6d8c" font="#000000"/> + <color name="body" value="#ffffff" link="#0F3660" vlink="#009999" hlink="#000066"/> + <color name="table" value="#7099C5"/> + <color name="table-cell" value="#f0f0ff"/> + <color name="highlight" value="#ffff00"/> + <color name="fixme" value="#cc6600"/> + <color name="note" value="#006699"/> + <color name="warning" value="#990000"/> + <color name="code" value="#CFDCED"/> + <color name="footer" value="#cedfef"/> + --> + <!-- Color group: Krysalis --> + <!-- + <color name="header" value="#FFFFFF"/> + + <color name="tab-selected" value="#a5b6c6" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="tab-unselected" value="#F7F7F7" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="subtab-selected" value="#a5b6c6" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="subtab-unselected" value="#a5b6c6" link="#000000" vlink="#000000" hlink="#000000"/> + + <color name="heading" value="#a5b6c6"/> + <color name="subheading" value="#CFDCED"/> + + <color name="navstrip" value="#CFDCED" font="#000000" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="toolbox" value="#a5b6c6"/> + <color name="border" value="#a5b6c6"/> + + <color name="menu" value="#F7F7F7" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="dialog" value="#F7F7F7"/> + + <color name="body" value="#ffffff" link="#0F3660" vlink="#009999" hlink="#000066"/> + + <color name="table" value="#a5b6c6"/> + <color name="table-cell" value="#ffffff"/> + <color name="highlight" value="#ffff00"/> + <color name="fixme" value="#cc6600"/> + <color name="note" value="#006699"/> + <color name="warning" value="#990000"/> + <color name="code" value="#a5b6c6"/> + + <color name="footer" value="#a5b6c6"/> + --> + <!-- Color group: Collabnet --> + <!-- + <color name="header" value="#003366"/> + + <color name="tab-selected" value="#dddddd" link="#555555" vlink="#555555" hlink="#555555"/> + <color name="tab-unselected" value="#999999" link="#ffffff" vlink="#ffffff" hlink="#ffffff"/> + <color name="subtab-selected" value="#cccccc" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="subtab-unselected" value="#cccccc" link="#555555" vlink="#555555" hlink="#555555"/> + + <color name="heading" value="#003366"/> + <color name="subheading" value="#888888"/> + + <color name="navstrip" value="#dddddd" font="#555555"/> + <color name="toolbox" value="#dddddd" font="#555555"/> + <color name="border" value="#999999"/> + + <color name="menu" value="#ffffff"/> + <color name="dialog" value="#eeeeee"/> + + <color name="body" value="#ffffff"/> + + <color name="table" value="#ccc"/> + <color name="table-cell" value="#ffffff"/> + <color name="highlight" value="#ffff00"/> + <color name="fixme" value="#cc6600"/> + <color name="note" value="#006699"/> + <color name="warning" value="#990000"/> + <color name="code" value="#003366"/> + + <color name="footer" value="#ffffff"/> + --> + <!-- Color group: Lenya using pelt--> + <!-- + + <color name="header" value="#ffffff"/> + + <color name="tab-selected" value="#E5E4D9" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="tab-unselected" value="#F5F4E9" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="subtab-selected" value="#000000" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="subtab-unselected" value="#E5E4D9" link="#000000" vlink="#000000" hlink="#000000"/> + + <color name="heading" value="#E5E4D9"/> + <color name="subheading" value="#000000"/> + <color name="published" value="#000000"/> + <color name="navstrip" value="#E5E4D9" font="#000000"/> + <color name="toolbox" value="#CFDCED" font="#000000"/> + <color name="border" value="#999999"/> + + <color name="menu" value="#E5E4D9" font="#000000" link="#000000" vlink="#000000" hlink="#000000"/> + <color name="dialog" value="#CFDCED"/> + <color name="body" value="#ffffff" /> + + <color name="table" value="#ccc"/> + <color name="table-cell" value="#ffffff"/> + <color name="highlight" value="#ffff00"/> + <color name="fixme" value="#cc6600"/> + <color name="note" value="#006699"/> + <color name="warning" value="#990000"/> + <color name="code" value="#003366"/> + + <color name="footer" value="#E5E4D9"/> + --> + </colors> + <!-- Settings specific to PDF output. --> + <pdf> + <!-- + Supported page sizes are a0, a1, a2, a3, a4, a5, executive, + folio, legal, ledger, letter, quarto, tabloid (default letter). + Supported page orientations are portrait, landscape (default + portrait). + Supported text alignments are left, right, justify (default left). + --> + <page size="letter" orientation="portrait" text-align="left"/> + <!-- + Pattern of the page numbering in the footer - Default is "Page x". + first occurrence of '1' digit represents the current page number, + second occurrence of '1' digit represents the total page number, + anything else is considered as the static part of the numbering pattern. + Examples : x is the current page number, y the total page number. + <page-numbering-format>none</page-numbering-format> Do not displays the page numbering + <page-numbering-format>1</page-numbering-format> Displays "x" + <page-numbering-format>p1.</page-numbering-format> Displays "px." + <page-numbering-format>Page 1/1</page-numbering-format> Displays "Page x/y" + <page-numbering-format>(1-1)</page-numbering-format> Displays "(x-y)" + --> + <page-numbering-format>Page 1</page-numbering-format> + <!-- + Margins can be specified for top, bottom, inner, and outer + edges. If double-sided="false", the inner edge is always left + and the outer is always right. If double-sided="true", the + inner edge will be left on odd pages, right on even pages, + the outer edge vice versa. + Specified below are the default settings. + --> + <margins double-sided="false"> + <top>1in</top> + <bottom>1in</bottom> + <inner>1.25in</inner> + <outer>1in</outer> + </margins> + <!-- + Print the URL text next to all links going outside the file + --> + <show-external-urls>false</show-external-urls> + <!-- + Normally all links inside a Forrest site are relative. This + does not work well in PDFs which are typically viewed outside of + the web site. Setting this option adds the given prefix to all + relative URLs, both to the link as well as the optional, additional text. + --> + <url-prefix></url-prefix> + <!-- + Disable the copyright footer on each page of the PDF. + A footer is composed for each page. By default, a "credit" with role=pdf + will be used, as explained below. Otherwise a copyright statement + will be generated. This latter can be disabled. + --> + <disable-copyright-footer>false</disable-copyright-footer> + + <!-- + Disable the generation of the table of content on the first page + of the PDF. By default the TOC is generated. + --> + <disable-toc>false</disable-toc> + </pdf> + <!-- + Credits are typically rendered as a set of small clickable + images in the page footer. + + Use box-location="alt" to move the credits to an alternate location + (if the skin supports it). + + For example, pelt skin: + - box-location="alt" will place the logo at the end of the + left-hand coloured menu panel. + - box-location="alt2" will place them underneath that panel + in the left-hand whitespace. + - Otherwise they are placed next to the compatibility icons + at the bottom of the screen. + + Comment out the whole <credit>-element if you want no credits in the + web pages + --> + <credits> + <credit box-location="alt"> + <name>Apache Event</name> + <url>https://www.apache.org/events/current-event.html</url> + <image>https://www.apache.org/events/current-event-125x125.png</image> + <width>125</width> + <height>125</height> + </credit> + <credit box-location="alt2"> + <name>Support Apache</name> + <url>https://donate.apache.org/</url> + <image>images/support-asf.png</image> + <width>125</width> + <height>125</height> + </credit> + <credit box-location="alt2"> + <name>powered by POI</name> + <url>https://www.apache.org/foundation/press/kit/#poweredby</url> + <image>images/poweredby-poi-logo.png</image> + <width>125</width> + <height>125</height> + </credit> + <!-- A credit with @role="pdf" will be used to compose a footer + for each page in the PDF, using either "name" or "url" or both. + --> + <!-- + <credit role="pdf"> + <name>Built with Apache Forrest</name> + <url>http://forrest.apache.org/</url> + </credit> + --> + </credits> +</skinconfig> diff --git a/test-data/document/bug-paragraph-alignment.docx b/test-data/document/bug-paragraph-alignment.docx Binary files differnew file mode 100644 index 0000000000..de4a468552 --- /dev/null +++ b/test-data/document/bug-paragraph-alignment.docx diff --git a/test-data/document/bug69628.docx b/test-data/document/bug69628.docx Binary files differnew file mode 100644 index 0000000000..359a3b3608 --- /dev/null +++ b/test-data/document/bug69628.docx diff --git a/test-data/document/deep-table-cell.docx b/test-data/document/deep-table-cell.docx Binary files differnew file mode 100644 index 0000000000..6bb54e6c6d --- /dev/null +++ b/test-data/document/deep-table-cell.docx diff --git a/test-data/document/table-alignment.docx b/test-data/document/table-alignment.docx Binary files differnew file mode 100644 index 0000000000..76fd85c338 --- /dev/null +++ b/test-data/document/table-alignment.docx diff --git a/test-data/document/table-indent.docx b/test-data/document/table-indent.docx Binary files differnew file mode 100644 index 0000000000..c4306aa937 --- /dev/null +++ b/test-data/document/table-indent.docx diff --git a/test-data/poifs/deep-data.bin b/test-data/poifs/deep-data.bin Binary files differnew file mode 100644 index 0000000000..a06aae8694 --- /dev/null +++ b/test-data/poifs/deep-data.bin diff --git a/test-data/slideshow/bug69697.ppt b/test-data/slideshow/bug69697.ppt Binary files differnew file mode 100644 index 0000000000..ff2cdcfbb8 --- /dev/null +++ b/test-data/slideshow/bug69697.ppt diff --git a/test-data/spreadsheet/bug69769.xlsx b/test-data/spreadsheet/bug69769.xlsx Binary files differnew file mode 100644 index 0000000000..39262dfff3 --- /dev/null +++ b/test-data/spreadsheet/bug69769.xlsx diff --git a/wrapper.gradle b/wrapper.gradle index 2dfca19e74..3c5eb309f7 100644 --- a/wrapper.gradle +++ b/wrapper.gradle @@ -30,7 +30,7 @@ wrapper { // Custom task to inject support for downloading the gradle wrapper jar if it doesn't exist. // This allows us to avoid checking in the jar to our repository. // Additionally adds a license header to the wrapper while editing the file contents. -task bootstrapWrapper() { +tasks.register('bootstrapWrapper') { // In the doLast block so this runs when the task is called and not during project configuration. doLast { def wrapperBasePath = "\$APP_HOME/gradle/wrapper" @@ -79,7 +79,7 @@ task bootstrapWrapper() { wrapper.finalizedBy bootstrapWrapper // Remove the generated batch file since we don't test building in the Windows environment. -task removeWindowsScript(type: Delete) { +tasks.register('removeWindowsScript', Delete) { delete "$rootDir/gradlew.bat" } wrapper.finalizedBy removeWindowsScript |
