| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
| <chapter id="known-issues"> |
| <title>Known Issues</title> |
| <section id="known-issues-jpa"> |
| <title>JPA Entity Scanning</title> |
| <para> |
| Classpath scanning for JPA entities annotated with <literal>@Entity</literal> does |
| not work. Describing entities with <literal>@Entity</literal> will work, but the |
| entities need to be listed explicitly. |
| </para> |
| </section> |
| <section id="known.issues.proxy"> |
| <title><classname>ClassNotFoundError</classname> When Creating a Proxy</title> |
| <para> |
| When creating proxies at runtime, there are circumstances where <classname>ClassNotFoundErrors</classname> |
| can be generated. These errors happen because the proxy creating bundle does not have visibility into every |
| type on the interface of the proxy. You can either put in import statements for all the relevant types or |
| add use a service (with visibility of all pertinent types) to create the proxy. Please see |
| <ulink url="http://www.osgi.org/blog/2008/08/classy-solutions-to-tricky-proxies.html">this blog entry</ulink> |
| for more details. |
| </para> |
| </section> |
| <section id="known.issues.cglib"> |
| <title>Creating proxies with CGLIB for Package Protected Types</title> |
| <para> |
| In traditional Java EE applications user types are loaded by the same <classname>ClassLoader</classname> as |
| CGLIB. This allows CGLIB to proxy package-protected types. In OSGi environments, user types and CGLIB will |
| most likely be packaged in separate bundles. This results in the user types and CGLIB being loaded by |
| different <classname>ClassLoaders</classname>. This prevents CGLIB from proxying any package-protected types. |
| </para> |
| <para> |
| The workaround for this issue is to make all types that require proxying public. |
| </para> |
| </section> |
| <section id="known-issues-jetty-restrictions"> |
| <title>@jetty.product.name@ Restrictions</title> |
| <para> |
| The following Jetty features are not supported. |
| <itemizedlist> |
| <listitem> |
| Tag Libraries other than the standard Apache Tag Library. |
| </listitem> |
| <listitem> |
| Jetty 7 does not support the Servlet 3.0 spec. When Jetty 8.0 is released the Virgo Jetty Server will |
| move up in a later release. |
| </listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| <section id="known-issues-web-bundle-default-headers"> |
| <title>Default Web Application Bundle Headers</title> |
| <para> |
| The Gemini Web container conforms to the OSGi Web Applications specification and does not apply default values |
| to the headers of a Web Application Bundle. However, SpringSource dm Server 2.0.x applies default values |
| to certain headers (see <link linkend="developing-applications-automatic-imports-web">Web Application Manifest |
| Processing</link> for details) and so Virgo Web Server 2.1.x modified the behaviour of Gemini Web so that it applied default |
| values consistently with dm Server 2.0.x. |
| </para> |
| <para> |
| This behaviour is changed as of @tomcat.product.name@ 3.0. @tomcat.product.name.short@ now conforms strictly to the |
| OSGi Web Applications specification. |
| </para> |
| <para> |
| As a migration aid, <emphasis>which may not be supported in a future release</emphasis>, users may configure the @tomcat.product.name.short@ Web Integration |
| Layer to apply default values to the headers of a Web Application Bundle. |
| See "Configuring the Web Integration Layer" in the <ulink url="../../virgo-user-guide/html/index.html">User Guide</ulink> for details. |
| </para> |
| </section> |
| <section id="hibernate-resolution-issue"> |
| <title>Hibernate Resolution Issue</title> |
| <para> |
| Applications using Hibernate 3.4.0.GA need to upgrade the JBoss Hibernate Entity manager fragment bundle to version 3.4.0.GA-A. |
| The symptoms are that the application will fail to resolve due to missing imports of packages such as <literal>org.hibernate.ejb.transaction</literal> |
| and JBoss Hibernate Annotations <literal>com.springsource.org.hibernate.annotations</literal>. |
| See <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=335174">bug 335174</ulink> for details. |
| </para> |
| <para> |
| The JBoss Hibernate Entity manager fragment bundle <literal>com.springsource.org.hibernate.ejb</literal> v3.4.0.GA in the |
| <ulink url="http://ebr.springsource.com/repository/app/">SpringSource Enterprise Bundle Repository</ulink> |
| depends on the package <literal>org.slf4j</literal> with a version range that excludes the version of the |
| package provided with Virgo. The net effect is that Hibernate EJB fragment bundle fails to attach to its host |
| <literal>com.springsource.org.hibernate</literal> and the host then does not export the packages the application |
| may need, such as <literal>org.hibernate.ejb.transaction</literal>. |
| </para> |
| <para> |
| An updated JBoss Hibernate Entity manager fragment and JBoss Hibernate Annotations with versions 3.4.0.GA-A which fixes this |
| problem is available from the <ulink url="http://ebr.springsource.com/repository/app/">SpringSource Enterprise Bundle Repository</ulink>. |
| </para> |
| </section> |
| <section id="scoping-and-substitutable-exports"> |
| <title>Scoping and Substitutable Exports</title> |
| <para> |
| The restriction described in <link linkend="developing-applications-plans-scoping">Plans and Scoping</link> that |
| no package may be exported by more than one bundle in a given scope can cause problems for bundles with |
| <emphasis>substitutable exports</emphasis>. A substitutable export is a package which is exported and imported |
| by the same bundle. The OSGi framework will discard either the import or the export of the package when the |
| bundle is resolved. |
| </para> |
| <para> |
| However, if more than one bundle in a scope has a substitutable export of the same package, then Virgo will fail |
| to deploy the scoped application because the above restriction appears to be broken. Virgo could only spot that |
| the restriction was not actually being broken by second guessing the resolution behaviour of the OSGi framework, |
| something that Virgo generally avoids because of the fragility of that approach. |
| </para> |
| <para> |
| It may be possible to work around this issue by omitting one of the bundles containing the substitutable export |
| from the scoped application. |
| </para> |
| <para> |
| It may also be possible to work around this issue by moving the bundles containing the substitutable exports outside the scope, |
| although this will not give correct behaviour if the bundles' exported packages need to be available for thread |
| context class loading. |
| </para> |
| <para> |
| See <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=330643">bug 330643</ulink> for an example of this issue. |
| </para> |
| </section> |
| <section id="eclipselink-resolution-issue"> |
| <title>EclipseLink Resolution Issue</title> |
| <para> |
| Applications using EclipseLink may fail to resolve if the <literal>osgi.enterprise</literal> bundle is allowed to |
| wire its <literal>javax.persistence</literal> package import to other than the EclipseLink <literal>javax.persistence</literal> bundle. |
| </para> |
| <para> |
| To avoid this, install EclipseLink's <literal>javax.persistence</literal> bundle early. To install this bundle before |
| any applications are deployed, list the bundle in the <literal>initialArtifacts</literal> property described in the |
| <ulink url="../../virgo-user-guide/html/index.html">User Guide</ulink>. |
| </para> |
| <para> |
| See <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=337826">bug 337826</ulink> for details. |
| </para> |
| </section> |
| </chapter> |