From commits-return-44144-archive-asf-public=cust-asf.ponee.io@tomee.apache.org Sun Dec 2 01:13:02 2018 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx-eu-01.ponee.io (Postfix) with SMTP id A62E718064E for ; Sun, 2 Dec 2018 01:13:00 +0100 (CET) Received: (qmail 2471 invoked by uid 500); 2 Dec 2018 00:12:54 -0000 Mailing-List: contact commits-help@tomee.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@tomee.apache.org Delivered-To: mailing list commits@tomee.apache.org Received: (qmail 1887 invoked by uid 99); 2 Dec 2018 00:12:54 -0000 Received: from Unknown (HELO svn01-us-west.apache.org) (209.188.14.144) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 02 Dec 2018 00:12:54 +0000 Received: from svn01-us-west.apache.org (localhost [127.0.0.1]) by svn01-us-west.apache.org (ASF Mail Server at svn01-us-west.apache.org) with ESMTP id A5B443A2CA5 for ; Sun, 2 Dec 2018 00:12:52 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1847931 [19/22] - in /tomee/site/trunk/content: latest/docs/admin/cluster/ latest/docs/admin/configuration/ latest/docs/advanced/applicationcomposer/ latest/docs/advanced/client/ latest/docs/advanced/jms/ latest/docs/advanced/setup/ latest... Date: Sun, 02 Dec 2018 00:12:51 -0000 To: commits@tomee.apache.org From: dblevins@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20181202001252.A5B443A2CA5@svn01-us-west.apache.org> Added: tomee/site/trunk/content/tomee-8.0/docs/developer/classloading/index.html URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/tomee-8.0/docs/developer/classloading/index.html?rev=1847931&view=auto ============================================================================== --- tomee/site/trunk/content/tomee-8.0/docs/developer/classloading/index.html (added) +++ tomee/site/trunk/content/tomee-8.0/docs/developer/classloading/index.html Sun Dec 2 00:12:50 2018 @@ -0,0 +1,239 @@ + + + + + + + + Apache TomEE + + + + + + + + + + + + + + + + + + + + + +
+ Preloader image +
+ + + +
+
+
+
+ +
+
+ Download as PDF +
+
+ +

The TomEE ClassLoader

+
+
+
+
+ +
+
+

TomEE ClassLoading is directly mapped to Tomcat one.

+
+
+

[ + { + label: 'JVM', + description: 'The JVM classloader launching tomcat main(String[])', + children: [ + { + label:'common.loader', + description:'Customizable in conf/catalina.properties, the common loader is the Tomcat classloader', + children: [ + { + label:'shared.loader', + description:'Optional layer where you can add libraries for the web applications not seen by Tomcat. It is generally not used and not encouraged since Tomcat 6', + children: [ + { + label:'webapp1', + description:'loader of one of your wars, it container WEB-INF/classes, WEB-INF/lib/.jar' + }, + { + label:'webapp2', + description:'loader of another one of your wars, it container WEB-INF/classes, WEB-INF/lib/.jar' + }, + { + label:'application1', + description:'loader of another application, it can be an ear, it contains lib and ejbmodules of the ear', + children: [ + { + label:'earwebapp1', + description:'loader of one of the wars of the ear' + }, + { + label:'earwebapp2', + description:'loader of the other webapp of the ear' + } + ] + } + ] + } + ] + } + ] + } +]

+
+
+

Click on the tree (JVM) on the left to see the detail there.

+
+
+ +
+
+ + +
+ + +
+ + + + + + + + + + + + + + Propchange: tomee/site/trunk/content/tomee-8.0/docs/developer/classloading/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: tomee/site/trunk/content/tomee-8.0/docs/developer/configuration/cxf.html URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/tomee-8.0/docs/developer/configuration/cxf.html?rev=1847931&view=auto ============================================================================== --- tomee/site/trunk/content/tomee-8.0/docs/developer/configuration/cxf.html (added) +++ tomee/site/trunk/content/tomee-8.0/docs/developer/configuration/cxf.html Sun Dec 2 00:12:50 2018 @@ -0,0 +1,331 @@ + + + + + + + + Apache TomEE + + + + + + + + + + + + + + + + + + + + + +
+ Preloader image +
+ + + +
+
+
+
+ +
+
+ Download as PDF +
+
+ +

CXF Configuration - JAX-RS (RESTful Services) and JAX-WS (Web Services)

+
+
+
+
+ +
+
+
+
+

TomEE relies on Apache CXF for JAX-RS (RESTful Services) and JAX-WS (Web Services). It does not provide all CXF modules, but the most common ones for both specifications (JAX-RS is part of all distributions but JAX-WS is only part of plus one).

+
+
+
+
+

Configuration

+
+
+

CXF API is reusable but you can also configure the interceptors through openejb-jar.xml (located in WEB-INF).

+
+
+

If you want to configure JAX-RS you will use the prefix cxf.jaxrs and if you configure JAX-WS you use cxf.jaxws prefix.

+
+
+ + + + + +
+ + +to configure directly the bus use org.apache.openejb.cxf.bus. prefix and configure it in conf/system.properties. +
+
+
+

To configure JAX-RS you need to add in openejb-jar.xml a pojo-deployment:

+
+
+
+
<?xml version="1.0" encoding="UTF-8"?>
+<openejb-jar>
+ <pojo-deployment class-name="jaxrs-application">
+   <properties>
+     # here will go the config
+   </properties>
+ </pojo-deployment>
+</openejb-jar>
+
+
+
+

For JAX-WS you will use a pojo-deployment matching the webservice class name for POJO webservices +or an ejb-deployment instead of a pojo-deployment for EJB webservices:

+
+
+
+
<?xml version="1.0" encoding="UTF-8"?>
+<openejb-jar>
+ <ejb-deployment ejb-name="MyEJBWebService">
+   <properties>
+     # here will go the config
+   </properties>
+ </ejb-deployment>
+</openejb-jar>
+
+
+
+

Then once you selected your prefix and know where to write the config just use the following entries:

+
+
+
    +
  • +

    properties: server factory properties

    +
    • +
  • +

    features: CXF features

    +
    • +
  • +

    in-interceptors: CXF in interceptors

    +
    • +
  • +

    out-interceptors: CXF out interceptors

    +
    • +
  • +

    in-fault-interceptors: CXF in interceptors for fault handling

    +
    • +
  • +

    out-fault-interceptors: CXF out interceptors for fault handling

    +
    • +
  • +

    databinding: server databinding

    +
    • +
  • +

    providers (only for JAX-RS endpoint): list of JAX-RS providers

    +
    • +
  • +

    skip-provider-scanning (only for JAX-RS): is provider scanning on or not (default true)

    +
    • +
+
+
+

For features and interceptors the rule is the same: value is a list comma separated. Each value of the list is either a qualified class name or an id of a service in resources.xml.

+
+
+

Databinding is simply either a qualified name or a service id in resources.xml (located in WEB-INF).

+
+
+
+
+

Sample for JAX-WS

+
+
+

To configure WSS4J on the EJB CalculatorBean for instance add in openejb-jar.xml:

+
+
+
+
<openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1">
+  <ejb-deployment ejb-name="CalculatorBean">
+    <properties>
+      cxf.jaxws.in-interceptors = wss4j
+    </properties>
+  </ejb-deployment>
+</openejb-jar>
+
+
+
+

With associated resources.xml which will define precisely the wss4j configuration:

+
+
+
+
<resources>
+  <Service id="wss4j" class-name="org.apache.openejb.server.cxf.config.WSS4JInInterceptorFactory" factory-name="create">
+    action = UsernameToken
+    passwordType = PasswordText
+    passwordCallbackClass = org.superbiz.ws.security.PasswordCallbackHandler
+  </Service>
+</resources>
+
+
+
+
+
+

Sample for JAX-RS

+
+
+

JAX-RS JSON page shows a sample dedicated to JAX-RS.

+
+
+
+
+ +
+
+ + +
+ + +
+ + + + + + + + + + + + + + Propchange: tomee/site/trunk/content/tomee-8.0/docs/developer/configuration/cxf.html ------------------------------------------------------------------------------ svn:eol-style = native Added: tomee/site/trunk/content/tomee-8.0/docs/developer/ide/index.html URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/tomee-8.0/docs/developer/ide/index.html?rev=1847931&view=auto ============================================================================== --- tomee/site/trunk/content/tomee-8.0/docs/developer/ide/index.html (added) +++ tomee/site/trunk/content/tomee-8.0/docs/developer/ide/index.html Sun Dec 2 00:12:50 2018 @@ -0,0 +1,227 @@ + + + + + + + + Apache TomEE + + + + + + + + + + + + + + + + + + + + + +
+ Preloader image +
+ + + +
+
+
+
+ +
+
+ Download as PDF +
+
+ +

Integrated Development Environments (IDEs)

+
+
+
+
+ +
+
+
+
+

TomEE is supported by the main IDEs in the market:

+
+
+ +
+
+
+
+

Eclipse

+
+

Be the first to write this part!

+
+
+
+

Idea

+
+

Be the first to write this part!

+
+
+
+

Netbeans

+
+

Be the first to write this part!

+
+
+
+ +
+
+ + +
+ + +
+ + + + + + + + + + + + + + Propchange: tomee/site/trunk/content/tomee-8.0/docs/developer/ide/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: tomee/site/trunk/content/tomee-8.0/docs/developer/json/index.html URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/tomee-8.0/docs/developer/json/index.html?rev=1847931&view=auto ============================================================================== --- tomee/site/trunk/content/tomee-8.0/docs/developer/json/index.html (added) +++ tomee/site/trunk/content/tomee-8.0/docs/developer/json/index.html Sun Dec 2 00:12:50 2018 @@ -0,0 +1,456 @@ + + + + + + + + Apache TomEE + + + + + + + + + + + + + + + + + + + + + +
+ Preloader image +
+ + + +
+
+
+
+ +
+
+ Download as PDF +
+
+ +

TomEE and Apache Johnzon - JAX-RS JSON Provider

+
+
+
+
+ +
+
+
+
+

Since TomEE 7.0, TomEE comes with Apache Johnzon. +It means you can use JSON-P out of the box but also Johnzon Mapper +which is the default JAX-RS provider for JSON.

+
+
+

IMPORTANT - this is a breaking change with 1.x which was using jettison. +This last one was relying on JAXB model to generate JSON which often led +to unexpected JSON tree and some unexpected escaping too.

+
+
+
+
+

Getting started with Johnzon Mapper

+
+
+

http://johnzon.apache.org/ will get more informations than this quick +getting started but here are the basics of the mapping with Johnzon.

+
+
+

The mapper uses a direct java to json representation.

+
+
+

For instance this java bean:

+
+
+
+
public class MyModel {
+  private int id;
+  private String name;
+
+  // getters/setters
+}
+
+
+
+

will be mapped to:

+
+
+
+
{
+  "id": 1234,
+  "name": "Johnzon doc"
+}
+
+
+
+

Note that Johnzon supports several customization either directly on the MapperBuilder of through annotations.

+
+
+

@JohnzonIgnore

+
+

@JohnzonIgnore is used to ignore a field. You can optionally say you ignore the field until some version +if the mapper has a version:

+
+
+
+
public class MyModel {
+  @JohnzonIgnore
+  private String name;
+
+  // getters/setters
+}
+
+
+
+

Or to support name for version 3, 4, …​ but ignore it for 1 and 2:

+
+
+
+
public class MyModel {
+  @JohnzonIgnore(minVersion = 3)
+  private String name;
+
+  // getters/setters
+}
+
+
+
+
+

@JohnzonConverter

+
+

Converters are used for advanced mapping between java and json.

+
+
+

There are several converter types:

+
+
+
    +
  1. +

    Converter: map java to json and the opposite based on the string representation

    +
    2. +
  2. +

    Adapter: a converter not limited to String

    +
    3. +
  3. +

    ObjectConverter.Reader: to converter from json to java at low level

    +
    4. +
  4. +

    ObjectConverter.Writer: to converter from java to json at low level

    +
    5. +
  5. +

    ObjectConverter.Codec: a Reader and Writer

    +
    6. +
+
+
+

The most common is to customize date format but they all take. For that simple case we often use a Converter:

+
+
+
+
public class LocalDateConverter implements Converter<LocalDate> {
+    @Override
+    public String toString(final LocalDate instance) {
+        return instance.toString();
+    }
+
+    @Override
+    public LocalDate fromString(final String text) {
+        return LocalDate.parse(text);
+    }
+}
+
+
+
+

If you need a more advanced use case and modify the structure of the json (wrapping the value for instance) +you will likely need Reader/Writer or a Codec.

+
+
+

Then once your converter developed you can either register globally on the MapperBuilder or simply decorate +the field you want to convert with @JohnzonConverter:

+
+
+
+
public class MyModel {
+  @JohnzonConverter(LocalDateConverter.class)
+  private LocalDate date;
+
+  // getters/setters
+}
+
+
+
+
+

@JohnzonProperty

+
+

Sometimes the json name is not java friendly (_foo or foo-bar or even 200 for instance). For that cases +@JohnzonProperty allows to customize the name used:

+
+
+
+
public class MyModel {
+  @JohnzonProperty("__date")
+  private LocalDate date;
+
+  // getters/setters
+}
+
+
+
+
+

AccessMode

+
+

On MapperBuilder you have several AccessMode available by default but you can also create your own one.

+
+
+

The default available names are:

+
+
+
    +
  • +

    field: to use fields model and ignore getters/setters

    +
    • +
  • +

    method: use getters/setters (means if you have a getter but no setter you will serialize the property but not read it)

    +
    • +
  • +

    strict-method (default based on Pojo convention): same as method but getters for collections are not used to write

    +
    • +
+
+
+

You can use these names with setAccessModeName().

+
+
+
+

Your own mapper

+
+

Since johnzon is in tomee libraries you can use it yourself (if you use maven/gradle set johnzon-mapper as provided):

+
+
+
+
final MySuperObject object = createObject();
+
+final Mapper mapper = new MapperBuilder().build();
+mapper.writeObject(object, outputStream);
+
+final MySuperObject otherObject = mapper.readObject(inputStream, MySuperObject.class);
+
+
+
+
+
+
+

Johnzon and JAX-RS

+
+
+

TomEE uses by default Johnzon as JAX-RS provider for versions 7.x. If you want however to customize it you need to follow this procedure:

+
+
+
    +
  1. +

    Create a WEB-INF/openejb-jar.xml:

    +
    2. +
+
+
+
+
<?xml version="1.0" encoding="UTF-8"?>
+<openejb-jar>
+ <pojo-deployment class-name="jaxrs-application">
+   <properties>
+     # optional but requires to skip scanned providers if set to true
+     cxf.jaxrs.skip-provider-scanning = true
+     # list of providers we want
+     cxf.jaxrs.providers = johnzon,org.apache.openejb.server.cxf.rs.EJBAccessExceptionMapper
+   </properties>
+ </pojo-deployment>
+</openejb-jar>
+
+
+
+
    +
  1. +

    Create a WEB-INF/resources.xml to define johnzon service which will be use to instantiate the provider

    +
    2. +
+
+
+
+
<?xml version="1.0" encoding="UTF-8"?>
+<resources>
+ <Service id="johnzon" class-name="org.apache.johnzon.jaxrs.ConfigurableJohnzonProvider">
+   # 1M
+   maxSize = 1048576
+   bufferSize = 1048576
+
+   # ordered attributes
+   attributeOrder = $order
+
+   # Additional types to ignore
+   ignores = org.apache.cxf.jaxrs.ext.multipart.MultipartBody
+ </Service>
+
+ <Service id="order" class-name="com.company.MyAttributeSorter" />
+
+</resources>
+
+
+
+

Note: as you can see you mainly just need to define a service with the id johnzon (same as in openejb-jar.xml) +and you can reference other instances using $id for services and @id for resources.

+
+
+
+
+ +
+
+ + +
+ + +
+ + + + + + + + + + + + + + Propchange: tomee/site/trunk/content/tomee-8.0/docs/developer/json/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: tomee/site/trunk/content/tomee-8.0/docs/developer/migration/tomee-1-to-7.html URL: http://svn.apache.org/viewvc/tomee/site/trunk/content/tomee-8.0/docs/developer/migration/tomee-1-to-7.html?rev=1847931&view=auto ============================================================================== --- tomee/site/trunk/content/tomee-8.0/docs/developer/migration/tomee-1-to-7.html (added) +++ tomee/site/trunk/content/tomee-8.0/docs/developer/migration/tomee-1-to-7.html Sun Dec 2 00:12:50 2018 @@ -0,0 +1,238 @@ + + + + + + + + Apache TomEE + + + + + + + + + + + + + + + + + + + + + +
+ Preloader image +
+ + + +
+
+
+
+ +
+
+ Download as PDF +
+
+ +

Migrate from TomEE 1 to TomEE 7

+
+
+
+
+ +
+
+

Breaking changes

+
+
+
    +
  • +

    Artifact coordinates changes

    +
    • +
+
+
+

GroupId changed from org.apache.openejb to org.apache.tomee. +It includes maven plugins which use now org.apache.tomee.maven and the javaee-api.

+
+
+

Versions of openejb and tomee are now aligned on 7.x and you don’t need to use +4.x and 1.x (or any variant) for openejb and tomee.

+
+
+
    +
  • +

    JAX-RS 2 specification refined the sorting of providers. It can have side effects for message body +readers/writers which don’t define their target mediatype properly like Jackson which uses wildcard instead of +a json related mediatype. To solve it register a custom provider redefining the media type.

    +
    • +
+
+
+

Can be as easy as:

+
+
+
+
@Provider
+@Consumes("application/json")
+@Produces("application/json")
+public class MyAppJsonProvider extends JacksonJsonProvider {
+}
+
+
+
+
    +
  • +

    JPA and CDI are linked now, enabling JPA to use CDI for its components but CDI can use JPA too…​ +to solve issues with hibernate you need to add either as system property or persistence unit tomee.jpa.factory.lazy = true.

    +
    • +
+
+
+
+
+ +
+
+ + +
+ + +
+ + + + + + + + + + + + + + Propchange: tomee/site/trunk/content/tomee-8.0/docs/developer/migration/tomee-1-to-7.html ------------------------------------------------------------------------------ svn:eol-style = native