Skip to content

Commit 2f80a2b

Browse files
chkalchkal
committed
Updated installation guides
1 parent 6e292b0 commit 2f80a2b

File tree

3 files changed

+161
-122
lines changed

3 files changed

+161
-122
lines changed

‎src/ozark/docs/install-javaee.md

Lines changed: 50 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -5,138 +5,123 @@ template: page.html
55

66
## Install Guide for Java EE
77

8-
MVC is an extension to JAX-RS, Ozark can be run on most application servers without
9-
any configuration. You will need to include the MVC-Spec as well as the Ozark module
8+
MVC is built on top of JAX-RS. This means that Ozark can be run on most application servers without
9+
any additional configuration. You will just need to include the MVC API JAR as well as the Ozark module
1010
for the JAX-RS implementation shipped with your application server.
1111

12-
Ozark requires at least the Java-EE 7 Web-Profile or the Eclipse MicroProfile.
12+
Ozark requires at least the Java EE 8 Web-Profile or the Eclipse MicroProfile.
1313

14-
### Glassfish/Payara
14+
Note: The MVC specification and Ozark are under active development. Therefore, you will have to add
15+
the Sonatype OSS snapshot repository to your POM to get the latest and greatest version.
16+
Please refer to [Setting up the snapshot repository](install-snapshots.html) for details.
1517

16-
Glassfishes comes with Jersey as its JAX-RS implementation. Please add the following
17-
dependencies to your application:
18+
### Required dependencies
19+
20+
The dependencies you need to add to your `pom.xml` file depend on which application server
21+
your are using.
22+
23+
#### Glassfish/Payara
24+
25+
Glassfish comes with Jersey as its JAX-RS implementation. Please add the following dependencies
26+
to your application:
1827

1928
```xml
2029
<dependency>
2130
<groupId>javax.mvc</groupId>
2231
<artifactId>javax.mvc-api</artifactId>
23-
<version>1.0-SNAPSHOT</version>
32+
<version>{{versions.spec.develop}}</version>
2433
</dependency>
2534
<dependency>
2635
<groupId>org.mvc-spec.ozark</groupId>
2736
<artifactId>ozark-jersey</artifactId>
28-
<version>1.0.0-m03-SNAPSHOT</version>
37+
<version>{{versions.ozark.develop}}</version>
2938
</dependency>
3039
```
3140

3241
### Wildfly and JBoss EAP
3342

34-
Wildfly uses RestEasy for JAX-RS. You need to include the following dependencies:
43+
Wildfly is using RESTEasy for JAX-RS. So you need to Ozark RESTEasy integration module:
3544

3645
```xml
3746
<dependency>
3847
<groupId>javax.mvc</groupId>
3948
<artifactId>javax.mvc-api</artifactId>
40-
<version>1.0-SNAPSHOT</version>
49+
<version>{{versions.spec.develop}}</version>
4150
</dependency>
4251
<dependency>
4352
<groupId>org.mvc-spec.ozark</groupId>
4453
<artifactId>ozark-resteasy</artifactId>
45-
<version>1.0.0-m03-SNAPSHOT</version>
54+
<version>{{versions.ozark.develop}}</version>
4655
</dependency>
4756
```
4857

4958
### Wildfly Swarm
5059

51-
We currently don't have a dedicated fraction for wildfly swarm, but you can use the
52-
JAX-RS fraction with the dependencies from wildfly section above:
60+
We currently don't have a dedicated fraction for wildfly Swarm, but you can use the
61+
JAX-RS fraction and add the same dependencies as required for Wildfly:
5362

5463
```xml
55-
<!-- WildFly Swarm Fractions -->
5664
<dependency>
5765
<groupId>org.wildfly.swarm</groupId>
5866
<artifactId>jaxrs</artifactId>
5967
</dependency>
6068
<dependency>
6169
<groupId>javax.mvc</groupId>
6270
<artifactId>javax.mvc-api</artifactId>
63-
<version>1.0-SNAPSHOT</version>
71+
<version>{{versions.spec.develop}}</version>
6472
</dependency>
6573
<dependency>
6674
<groupId>org.mvc-spec.ozark</groupId>
6775
<artifactId>ozark-resteasy</artifactId>
68-
<version>1.0.0-m03-SNAPSHOT</version>
76+
<version>{{versions.ozark.develop}}</version>
6977
</dependency>
7078
```
7179

7280
### Apache TomEE
7381

74-
TomEE uses CXF as JAX-RS implementation. Right now there is no Ozark module for that.
82+
Apache TomEE uses CXF as the JAX-RS implementation. Unfortunately there are some known bugs in CXF
83+
which are causing trouble for Ozark. The latest CXF release should fix these issues, but Apache TomEE
84+
currently ships with an older CXF release.
7585

76-
To get around this, we'll demonstrate how to use it with the RestEasy module.
77-
78-
The following pom.xml example that shows the dependency configuration:
86+
If you want to give Ozark on Apache TomEE a try, add the following dependencies to your `pom.xml`:
7987

8088
```xml
8189
<dependency>
8290
<groupId>javax.mvc</groupId>
8391
<artifactId>javax.mvc-api</artifactId>
84-
<version>1.0-SNAPSHOT</version>
92+
<version>{{versions.spec.develop}}</version>
8593
</dependency>
8694
<dependency>
8795
<groupId>org.mvc-spec.ozark</groupId>
88-
<artifactId>ozark-resteasy</artifactId>
89-
<version>1.0.0-m03-SNAPSHOT</version>
96+
<artifactId>ozark-core</artifactId>
97+
<version>{{versions.ozark.develop}}</version>
9098
</dependency>
99+
```
100+
101+
If using CXF with Ozark is causing trouble, you can also manually add RESTEasy to your application
102+
and use this instead of CXF. To do so, use the following depndencies instead.
103+
104+
```xml
91105
<dependency>
92-
<groupId>javax</groupId>
93-
<artifactId>javaee-web-api</artifactId>
94-
<version>7.0</version>
95-
<scope>provided</scope>
106+
<groupId>javax.mvc</groupId>
107+
<artifactId>javax.mvc-api</artifactId>
108+
<version>{{versions.spec.develop}}</version>
96109
</dependency>
97110
<dependency>
98-
<groupId>org.jboss.resteasy</groupId>
99-
<artifactId>resteasy-cdi</artifactId>
100-
<version>3.1.4.Final</version>
111+
<groupId>org.mvc-spec.ozark</groupId>
112+
<artifactId>ozark-resteasy</artifactId>
113+
<version>{{versions.ozark.develop}}</version>
101114
</dependency>
102115
<dependency>
103-
<groupId>org.jboss.resteasy</groupId>
104-
<artifactId>resteasy-servlet-initializer</artifactId>
105-
<version> 3.1.4.Final</version>
116+
<groupId>org.jboss.resteasy</groupId>
117+
<artifactId>resteasy-cdi</artifactId>
118+
<version>3.1.4.Final</version>
106119
</dependency>
107120
<dependency>
108-
<groupId>org.hibernate</groupId>
109-
<artifactId>hibernate-validator</artifactId>
110-
<version>5.4.1.Final</version>
121+
<groupId>org.jboss.resteasy</groupId>
122+
<artifactId>resteasy-servlet-initializer</artifactId>
123+
<version>3.1.4.Final</version>
111124
</dependency>
112125
```
113-
### 3. Add the bean.xml,context.xml and web.xml file
114-
make sure to add an empty beans.xml file in your /resources/META-INF/ folder to your Web project:
115-
116-
```xml
117-
<?xml version="1.0"?>
118-
<beans xmlns="http://xmlns.jcp.org/xml/ns/javaee"
119-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
120-
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
121-
http://xmlns.jcp.org/xml/ns/javaee/beans_1_1.xsd"
122-
version="1.1" bean-discovery-mode="all">
123-
</beans>
124-
```
125-
to finish create within /webapp/WEB-INF/ the web.xml file with the following content:
126-
127-
```xml
128-
<?xml version="1.0" encoding="UTF-8"?>
129-
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
130-
xmlns="http://java.sun.com/xml/ns/javaee"
131-
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
132-
http://java.sun.com/xml/ns/javaee/web-app_3_1.xsd"
133-
version="3.1">
134-
135-
<context-param>
136-
<!--http://docs.jboss.org/resteasy/docs/3.1.4.Final/userguide/html_single/index.html#d4e143 -->
137-
<param-name>resteasy.injector.factory</param-name>
138-
<param-value>org.jboss.resteasy.cdi.CdiInjectorFactory</param-value>
139-
</context-param>
140-
</web-app>
141-
```
142126

127+
That's all. Now you can start developing your first MVC 1.0 application.

‎src/ozark/docs/install-servlet.md

Lines changed: 85 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -5,100 +5,128 @@ template: page.html
55

66
## Install Guide for Servlet Containers
77

8-
The Ozark MVC implementation is based on Jersey and recently a RestEasy module has been added to work with Widlfly.
8+
The simplest way to get started with MVC is to deploy your app to a JavaEE 7 application server.
9+
In this setup the application server will provider JAX-RS, CDI and Beań Validation implemnetations
10+
for you. Please refer to [Install Guide for Java EE](install-javaee.html) for details about this setup.
911

10-
In this guide we will run Ozark on Apache Tomcat using the RestEasy module
12+
However, there is a large number of users who prefer to run their applications on plain Servlet
13+
containers like Apache Tomcat and Jetty. In this setup you will have to provider JAX-RS,
14+
CDI and Bean Validations yourself.
1115

12-
The following pom.xml example that shows the dependency configuration:
16+
In this guide we will show you how to run Ozark on Apache Tomcat using Weld, RESTEasy and
17+
Hibernate Validator.
1318

14-
### Apache Tomcat
19+
Note: The MVC specification and Ozark are under active development. Therefore, you will have to add
20+
the Sonatype OSS snapshot repository to your POM to get the latest and greatest version.
21+
Please refer to [Setting up the snapshot repository](install-snapshots.html) for details.
22+
23+
### Required dependencies
24+
25+
The following `pom.xml` example shows the dependency configuration for your application:
1526

1627
```xml
28+
<!-- Get the API JARs for Java EE 7 -->
1729
<dependency>
18-
<groupId>javax.mvc</groupId>
19-
<artifactId>javax.mvc-api</artifactId>
20-
<version>1.0-SNAPSHOT</version>
30+
<groupId>javax</groupId>
31+
<artifactId>javaee-web-api</artifactId>
32+
<version>7.0</version>
2133
</dependency>
34+
35+
<!-- Weld -->
2236
<dependency>
23-
<groupId>org.mvc-spec.ozark</groupId>
24-
<artifactId>ozark-resteasy</artifactId>
25-
<version>1.0.0-m03-SNAPSHOT</version>
37+
<groupId>org.jboss.weld.servlet</groupId>
38+
<artifactId>weld-servlet-core</artifactId>
39+
<version>2.4.3.Final</version>
2640
</dependency>
41+
42+
<!-- RESTEasy -->
2743
<dependency>
28-
<groupId>javax</groupId>
29-
<artifactId>javaee-web-api</artifactId>
30-
<version>7.0</version>
44+
<groupId>org.jboss.resteasy</groupId>
45+
<artifactId>resteasy-cdi</artifactId>
46+
<version>3.1.4.Final</version>
3147
</dependency>
3248
<dependency>
33-
<groupId>org.jboss.weld.servlet</groupId>
34-
<artifactId>weld-servlet-core</artifactId>
35-
<version>2.4.3.Final</version>
49+
<groupId>org.jboss.resteasy</groupId>
50+
<artifactId>resteasy-servlet-initializer</artifactId>
51+
<version> 3.1.4.Final</version>
3652
</dependency>
53+
54+
<!-- Bean Validation -->
3755
<dependency>
38-
<groupId>org.jboss.resteasy</groupId>
39-
<artifactId>resteasy-cdi</artifactId>
40-
<version>3.1.4.Final</version>
56+
<groupId>org.hibernate</groupId>
57+
<artifactId>hibernate-validator</artifactId>
58+
<version>5.4.1.Final</version>
4159
</dependency>
60+
61+
<!-- MVC + Ozark for RESTEasy-->
4262
<dependency>
43-
<groupId>org.jboss.resteasy</groupId>
44-
<artifactId>resteasy-servlet-initializer</artifactId>
45-
<version> 3.1.4.Final</version>
63+
<groupId>javax.mvc</groupId>
64+
<artifactId>javax.mvc-api</artifactId>
65+
<version>{{versions.spec.develop}}</version>
4666
</dependency>
4767
<dependency>
48-
<groupId>org.hibernate</groupId>
49-
<artifactId>hibernate-validator</artifactId>
50-
<version>5.4.1.Final</version>
68+
<groupId>org.mvc-spec.ozark</groupId>
69+
<artifactId>ozark-resteasy</artifactId>
70+
<version>{{versions.ozark.develop}}</version>
5171
</dependency>
5272
```
53-
### 3. Add the bean.xml,context.xml and web.xml file
54-
make sure to add an empty beans.xml file in your /resources/META-INF folder to your Web project:
73+
74+
### Configuration files
75+
76+
Make sure to add an empty `beans.xml` file in your `/src/main/webapp/WEB-INF` folder:
5577

5678
```xml
5779
<?xml version="1.0"?>
5880
<beans xmlns="http://xmlns.jcp.org/xml/ns/javaee"
5981
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
60-
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
61-
http://xmlns.jcp.org/xml/ns/javaee/beans_1_1.xsd"
62-
version="1.1" bean-discovery-mode="all">
82+
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/beans_1_1.xsd"
83+
version="1.1" bean-discovery-mode="all">
84+
6385
</beans>
6486
```
65-
still in the same folder add the context.xml with the following content:
87+
88+
Please also add a file called `context.xml` to `src/main/resources/META-INF`:
6689

6790
```xml
6891
<?xml version="1.0" encoding="UTF-8"?>
6992
<Context>
70-
<Manager pathname=""/>
71-
<Resource name="BeanManager"
72-
auth="Container"
73-
type="javax.enterprise.inject.spi.BeanManager"
74-
factory="org.jboss.weld.resources.ManagerObjectFactory"/>
93+
94+
<Resource name="BeanManager" auth="Container"
95+
type="javax.enterprise.inject.spi.BeanManager"
96+
factory="org.jboss.weld.resources.ManagerObjectFactory"/>
97+
7598
</Context>
7699
```
77-
this file is essential for the operation of the CDI in TomCat as described here:[Weld-Doc](http://docs.jboss.org/weld/reference/latest/en-US/html_single/#_tomcat)
78100

79-
to finish create within /webapp/WEB-INF/ the web.xml file with the following content:
101+
This file `context.xml` is essential for the operation of the CDI in Tomcat as described in
102+
the [Weld documentation](http://docs.jboss.org/weld/reference/latest/en-US/html_single/#tomcat).
103+
104+
The file to create is called `web.xml` and should be placed in the `src/main/webapp/WEB-INF`
105+
directory:
80106

81107
```xml
82108
<?xml version="1.0" encoding="UTF-8"?>
83109
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
84-
xmlns="http://java.sun.com/xml/ns/javaee"
85-
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
86-
http://java.sun.com/xml/ns/javaee/web-app_3_1.xsd"
87-
version="3.1">
88-
89-
<listener>
90-
<listener-class>org.jboss.weld.environment.servlet.Listener</listener-class>
91-
</listener>
92-
93-
<resource-env-ref>
94-
<resource-env-ref-name>BeanManager</resource-env-ref-name>
95-
<resource-env-ref-type>javax.enterprise.inject.spi.BeanManager</resource-env-ref-type>
96-
</resource-env-ref>
97-
98-
<context-param>
99-
<!--http://docs.jboss.org/resteasy/docs/3.1.4.Final/userguide/html_single/index.html#d4e143 -->
100-
<param-name>resteasy.injector.factory</param-name>
101-
<param-value>org.jboss.resteasy.cdi.CdiInjectorFactory</param-value>
102-
</context-param>
110+
xmlns="http://java.sun.com/xml/ns/javaee"
111+
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_1.xsd"
112+
version="3.1">
113+
114+
<listener>
115+
<listener-class>org.jboss.weld.environment.servlet.Listener</listener-class>
116+
</listener>
117+
118+
<resource-env-ref>
119+
<resource-env-ref-name>BeanManager</resource-env-ref-name>
120+
<resource-env-ref-type>javax.enterprise.inject.spi.BeanManager</resource-env-ref-type>
121+
</resource-env-ref>
122+
123+
<!--http://docs.jboss.org/resteasy/docs/3.1.4.Final/userguide/html_single/index.html#d4e143 -->
124+
<context-param>
125+
<param-name>resteasy.injector.factory</param-name>
126+
<param-value>org.jboss.resteasy.cdi.CdiInjectorFactory</param-value>
127+
</context-param>
128+
103129
</web-app>
104130
```
131+
132+
That's all. Now you can start developing your first MVC 1.0 application.

0 commit comments

Comments
 (0)