Skip to content
carlosame edited this page Sep 13, 2024 · 13 revisions

API

Can I render an SVG image that is inlined inside an HTML document?

If you use a transcoder that inherits from the XMLAbstractTranscoder class, you can. First of all, set the following hints:

transcoder.addTranscodingHint(XMLAbstractTranscoder.KEY_DOCUMENT_ELEMENT_NAMESPACE_URI,
    "http://www.w3.org/1999/xhtml");
transcoder.addTranscodingHint(XMLAbstractTranscoder.KEY_DOCUMENT_ELEMENT, "html");

The first SVG element found is used as the new root, although you can pick a specific svg element if you use the KEY_SVG_SELECTOR transcoding hint.

You could also use the CSSTranscodingHelper which works similarly, albeit in that case you do not need to set KEY_DOCUMENT_ELEMENT_NAMESPACE_URI nor KEY_DOCUMENT_ELEMENT.

In the rest of the old API, you can't (please see #40). You have to import the SVG subtree into a new SVG DOM document.


Exception: Root element namespace does not match that requested

See above, you have to appropriately set the KEY_DOCUMENT_ELEMENT_NAMESPACE_URI and KEY_DOCUMENT_ELEMENT hints.


Exception: NoClassDefFoundError: io/sf/carte/doc/style/css/nsac/Parser

This arises when your build process does not use the provided dependency metadata, and you do not have css4j in your classpath or modulepath.


Exception: NoClassDefFoundError: io/sf/carte/doc/xml/dtd/DefaultEntityResolver

This happens when your build process does not use the provided dependency metadata, and you do not have xml-dtd in your classpath or modulepath.


Android

Does it run on Android?

EchoSVG uses the java.awt package which is not available on Android. Although a library like android-awt may be used, this project is unaware of anyone succeeding. Also, a parser-related issue has been reported.


CSS

Can I set CSS properties from Java code?

Although EchoSVG implements an old version of the CSS Object Model, it allows programmatic manipulation of CSS style sheets.

If you want to use a more powerful CSS OM, you may want to pre-process your document with css4j first, then feed it to EchoSVG.


Does this project support Houdini's Typed OM?

Version 1.x uses the old (and deprecated) CSSValue API, while 2.0 is a first transition towards Typed OM.


SVG Basics

How do I scale part of an image?

The following tutorials may help:

As well as the MDN reference for the viewBox: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/viewBox


Distribution

Is this project available from Maven Central?

No it is not, as its maintainer does not accept Maven Central's Terms of Use (see issue #95). The distribution is through the css4j Maven repository instead.


Licensing

Why didn't you keep Batik's org.apache package names?

Only software coming from the Apache Software Foundation (ASF) source repositories can be used in org.apache packages. If you look at the point 6 of the ASF license 2.0:

  1. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.

The term "Apache" is a registered trademark by the ASF (registration number 5906264) and can only be used for attribution. "Apache Batik" is a product name and similar considerations apply.


Can I submit code from EchoSVG to the Apache Batik project?

No you cannot. Submitting code to any Apache Software Foundation (ASF) project implies assigning the copyright to the ASF. Instead, EchoSVG uses a Developer Certificate of Origin copyright model, so contributors keep their copyright.

You cannot assign to the ASF the copyright that you do not own.


Modules

Where are the write adapters like PNGTranscoderInternalCodecWriteAdapter?

The codec and transcoder jar files were a bit entangled in Apache Batik, as they have a runtime circular dependency. And this often confused people, see:

What's worse, in Batik a third module silently depends on codec at runtime but doesn't declare that in the POM, so in the end the circularity involves three modules.

To fix that mess, in EchoSVG the WriteAdapter implementations were moved from echosvg-codec to the transcoder.image package of echosvg-transcoder.


[0.1.x only] java.lang.module.FindException: Module xalan not found, required by io.sf.carte.echosvg.dom

The module system is refusing to create a filename-based module name from the Xalan jar file because it is finding a declaration of a non-existent service provider.

The solution is to upgrade to EchoSVG 0.2 or later (that do not depend on Xalan) but if you cannot do that, the workaround is to use a plugin to force the declaration of a module name.

With Gradle you can use either the extra-java-module-info plugin:

plugins {
  id 'org.gradlex.extra-java-module-info' version '1.4.2'
}

extraJavaModuleInfo {
  failOnMissingModuleInfo.set(false)
  automaticModule('xalan:xalan', 'xalan')
}

or the moditect-gradle-plugin.

With Maven, you could use the Moditect Maven plugin.


Security

My security scanner claims an XXE vulnerability in SAXDocumentFactory.java

It is a false positive. The security scanner expects a feature like load-external-dtd or disallow-doctype-decl being used, however those configurations lead to data loss when XML entities are used.

EchoSVG uses the xml-dtd resolver as described in the aforementioned post.


Examples

Any example of a project that uses EchoSVG?

Yes there are a few open source projects that use EchoSVG, and Carte is a relatively simple one that you could look at (see SVGtoRaster.java).

For a much simpler example, see EchoSVGTest.java.