Changes for page Quick Start

Summary

• Page properties (3 modified, 0 added, 0 removed)

Details

Page properties

Parent

...	...	@@ -1,0 +1,1 @@
	1	+WOL.Home.WOProject-Maven.WebHome

Author

...	...	@@ -1,1 +1,1 @@
1		-XWiki.ramsey
	1	+XWiki.paulh

Content

...	...	@@ -1,114 +1,154 @@
1		-== Outline ==
	1	+(% class="auto-cursor-target" %)
	2	+You should be able to get a "Hello, World!" Wonder application running using [[Maven>>https://maven.apache.org]] in about 10 minutes.
2	2
3		-== Step 1: Installing Maven ==
	4	+(% id="HAssumptions" class="auto-cursor-target" %)
	5	+= Assumptions =
4	4
5		-Downloading and installing the latest version of [[Maven>>url:http://maven.apache.org/download||shape="rect"]] is the first step to start using this tool.
	7	+We're going to make a few assumptions to keep this page brief:
6	6
7		-{{tip title="Mac Tip"}}
8		-install macports [[http:~~/~~/www.macports.org/install.php>>url:http://www.macports.org/install.php||shape="rect"]], then on the terminal:
	9	+1. You are running macOS X. You can probably get a WebObjects development environment up on a different OS, but we won't cover that here.
	10	+1. You have Java installed. Any version will do. People are running WebObjects on Java 21 in production.
	11	+1. You have Eclipse and WOLips installed. Install the [[latest version of Eclipse>>https://www.eclipse.org/downloads/packages/]], along with the [[latest WOLips>>https://github.com/wocommunity/wolips]] if you haven't already.
9	9
10		-{{noformat}}
11		-sudo port install maven3
	13	+(% id="HSetup" class="auto-cursor-target" %)
	14	+= Setup =
12	12
13		-{{/noformat}}
	16	+(% class="auto-cursor-target" %)
	17	+You need to install Maven:
14	14
15		-In future, to keep this up to date:
	19	+(% class="auto-cursor-target" %)
	20	+{{{$ cd ~/Applications
	21	+$ curl -O https://dlcdn.apache.org/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.zip
	22	+$ unzip apache-maven-3.9.9-bin.zip
	23	+$ ln -s apache-maven-3.9.9 apache-maven
	24	+}}}
16	16
17		-{{noformat}}
18		-sudo port upgrade maven3
	26	+Add ##bin## to your path in your shell's startup file, say ##~~/.zshrc##:
19	19
20		-{{/noformat}}
	28	+{{{PATH=$PATH:/Users/paulh/Applications/apache-maven-3.9.9/bin
	29	+}}}
21	21
22		-Don't forget to install maven_select:
	31	+(% class="auto-cursor-target" %)
	32	+Confirm you have it installed:
23	23
24		-{{noformat}}
25		-sudo port install maven_select
	34	+(% class="auto-cursor-target" %)
	35	+{{{$ mvn --version
	36	+Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3cd08dcc295161ae)
	37	+}}}
26	26
27		-{{/noformat}}
28		-{{/tip}}
	39	+(% class="auto-cursor-target" %)
	40	+Finally, add ##~~/.m2/settings.xml##:
29	29
30		-**NOTE**: It is very helpful if you understand some Maven concepts before continuing with this tutorial. See [[doc:General Maven Documentation]] for more information.
	42	+(% class="auto-cursor-target" %)
	43	+{{{<settings xmlns="http://maven.apache.org/POM/4.0.0"
	44	+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	45	+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
	46	+ http://maven.apache.org/xsd/settings-1.0.0.xsd">
	47	+ <profiles>
	48	+ <profile>
	49	+ <id>wocommunity</id>
	50	+ <activation>
	51	+ <activeByDefault>true</activeByDefault>
	52	+ </activation>
	53	+ <repositories>
	54	+ <repository>
	55	+ <id>wocommunity</id>
	56	+ <url>https://maven.wocommunity.org/content/groups/public/</url>
	57	+ <releases>
	58	+ <enabled>true</enabled>
	59	+ </releases>
	60	+ <snapshots>
	61	+ <enabled>true</enabled>
	62	+ </snapshots>
	63	+ </repository>
	64	+ </repositories>
	65	+ <pluginRepositories>
	66	+ <pluginRepository>
	67	+ <id>wocommunity</id>
	68	+ <url>https://maven.wocommunity.org/content/groups/public/</url>
	69	+ <releases>
	70	+ <enabled>true</enabled>
	71	+ </releases>
	72	+ <snapshots>
	73	+ <enabled>false</enabled>
	74	+ </snapshots>
	75	+ </pluginRepository>
	76	+ </pluginRepositories>
	77	+ </profile>
	78	+ </profiles>
	79	+</settings>
	80	+}}}
31	31
32		-== Step 2: Configuring your Maven Settings ==
	82	+(% id="HCreateanewapplicationproject" class="auto-cursor-target" %)
	83	+= Create a new application project =
33	33
34		-Advanced users can skip this step, but it's highly recommended.
	85	+(% class="auto-cursor-target" %)
	86	+Make a new directory somewhere, and run:
35	35
36		-[[doc:Quick Start Maven Settings Configuration Guide]]
	88	+{{{$ mvn archetype:generate -DarchetypeArtifactId=erxapplication-archetype \
	89	+ -DarchetypeGroupId=org.wocommunity \
	90	+ -DarchetypeVersion=3.0 -DaskForDefaultPropertyValues=true}}}
37	37
38		-**NOTE for those who know what to do**: You can download the complete and most recent settings.xml [[here>>attach:settings.xml]] and install it to ~~/.m2/settings.xml.
	92	+(% class="auto-cursor-target" %)
	93	+After some downloading, Maven will prompt you:
39	39
40		-See [[Maven Settings Reference>>url:http://maven.apache.org/settings.html||shape="rect"]] if you want more information about additional options for the settings.xml file.
	95	+(% class="auto-cursor-target" %)
	96	+{{{Define value for property 'JavaVersion' 1.8: : 1.8
	97	+Define value for property 'WonderVersion' 7.2: : 7.4
	98	+Define value for property 'groupId': example.app
	99	+Define value for property 'artifactId': Foo
	100	+Define value for property 'version' 1.0-SNAPSHOT: : 0.1-SNAPSHOT
	101	+Define value for property 'package' example.app: : example.app.foo}}}
41	41
42		-== Step 3: Installing WebObjects Libraries ==
43	43
44		-Maven takes control of all your project's dependencies. To develop WebObjects applications, Maven has to reference the WebObjects jars. You have to [[install the WebObjects libraries into your local repository>>url:http://wocreator.sourceforge.net/repository-howto.html||shape="rect"]] to accomplish this:
	104	+You can enter any version of Java. You should definitely change ##WonderVersion## from 7.2 → 7.4. Hit 'Y' to confirm when requested.
45	45
46		-{{noformat}}
47		-mvn wobootstrap:install
	106	+(% class="box infomessage" %)
	107	+(((
	108	+If you enter a ##JavaVersion## greater than 1.8 (there are people using Java 21 in production, for example: enter ##21##), you need to add the following line to build.properties:
	109	+\\##jvmOptions=~-~-add-exports java.base/sun.security.action=ALL-UNNAMED ~-~-add-exports java.base/sun.util.calendar=ALL-UNNAMED##
	110	+)))
48	48
49		-{{/noformat}}
50	50
51		-**NOTE**: WebObjects must be installed.
	113	+(% id="HBuildandlaunchtheapplication" class="auto-cursor-target" %)
	114	+= Build and launch the application =
52	52
53		-**See** the [[doc:maven-wobootstrap-plugin]] documentation for more information and options for specifying a specific version.
	116	+(% class="auto-cursor-target" %)
	117	+From the same directory, run:
54	54
55		-**See** [[Maven Introduction to Repositories>>url:http://maven.apache.org/guides/introduction/introduction-to-repositories.html||shape="rect"]] if you want more information about Maven repositories.
	119	+(% class="auto-cursor-target" %)
	120	+{{{$ cd Foo
	121	+$ mvn package}}}
56	56
57		-{{warning title="Installing the right jars!"}}
58		-Do **not** link to or install the WebObjects jars located inside {{code language="none"}}/System/Library/Frameworks{{/code}} or {{code language="none"}}/Library/Frameworks{{/code}}. If you're installing an older version of WebObjects you must obtain the jars that the WebObjects installer had previously installed into {{code language="none"}}/Library/WebObjects/lib{{/code}}. For example, the jar {{code language="none"}}/Library/WebObjects/lib/JavaWebObjects.jar{{/code}} has the complete set of resources and files included for the dependency JavaWebObjects whereas {{code language="none"}}/System/Library/Frameworks/JavaWebObjects.framework/Resources/Java/javawebobjects.jar{{/code}} does not.
59		-{{/warning}}
	123	+(% class="auto-cursor-target" %)
	124	+Once Maven has finished building, you can launch:
60	60
61		-== Step 4: Creating a WebObjects or Wonder Project ==
	126	+(% class="auto-cursor-target" %)
	127	+{{{$ ./target/Foo.woa/Foo}}}
62	62
63		-Archetypes are the fast way to create a new project using Maven and WOProject provides various archetypes of its own to get you started with WebObjects, or better, Wonder-based applications. Execute the following command to generate a basic Wonder application project:
	129	+(% class="auto-cursor-target" %)
	130	+A browser should open and show:
64	64
65		-{{noformat}}
66		-mvn archetype:generate -DarchetypeArtifactId=erxapplication-archetype \
67		- -DarchetypeGroupId=org.objectstyle.woproject.maven2 \
68		- -DarchetypeVersion=2.1
	132	+>Hello WOnder world!
69	69
70		-{{/noformat}}
	134	+(% id="HImportyourprojectintoEclipse" class="auto-cursor-target" %)
	135	+= Import your project into Eclipse =
71	71
72		-The maven-archetype-plugin will ask the required information to create the new project.
	137	+(% class="auto-cursor-target" %)
	138	+A final, optional step is to bring the project into Eclipse.
73	73
74		-**NOTE**: You can use archetype catalogs to reduce the number of properties to set while creating a project. See the documentation of [[doc:woapplication-archetype]].
	140	+1. File > Import... > Maven > Existing Maven Projects
	141	+1. Using the file browser, find the top-level "Foo" folder containing the project you created above, click Open.
	142	+1. Ensure ##pom.xml## is checked and click Finish.
75	75
76		-**NOTE**: You can use archetypes within Eclipse as described [[here>>doc:documentation.Maven Create WO Application Project||anchor="m2eclipse"]].
	144	+(% class="box infomessage" %)
	145	+(((
	146	+As above, if you're using Java beyond Java 8, you need to add the following to the launch configuration under Arguments > VM arguments:
	147	+\\##~-~-add-exports java.base/sun.security.action=ALL-UNNAMED ~-~-add-exports java.base/sun.util.calendar=ALL-UNNAMED##
	148	+)))
77	77
78		-**NOTE:** You can see the list of available archetypes in the following location: [[http:~~/~~/wo-repository.moleque.com.br/nexus/content/groups/public/org/objectstyle/woproject/maven2/>>url:http://wo-repository.moleque.com.br/nexus/content/groups/public/org/objectstyle/woproject/maven2/||shape="rect"]].
79	79
80		-== Step 5: Importing the Project into Eclipse ==
81	81
82		-The new project is ready to be imported into Eclipse workspace. Use the Eclipse's import wizard (File > Import...) and choose the option "Existing Projects into Workspace". Select the root directory of your new project and finish the import wizard.
83	83
84		-{{note title="Warning"}}
85		-As Maven takes care of the dependency management, you must use a mechanism to add the jars to your Eclipse build path. There are 3 options:
86		-
87		-1. Use the [[mvn eclipse:eclipse>>url:http://maven.apache.org/plugins/maven-eclipse-plugin/||shape="rect"]] goal to update your .classpath file.
88		-1. Use the [[m2eclipse>>url:http://m2eclipse.codehaus.org/||shape="rect"]] plug-in for Eclipse.
89		-1. Use the [[q4e>>url:http://code.google.com/p/q4e/||shape="rect"]] plug-in for Eclipse.
90		-{{/note}}
91		-
92		-After adding the project dependencies to your Eclipse build path, WOLips can build the project and you will be able to start developing and running the application.
93		-
94		-**NOTE**: This tutorial assumes you have chosen the option 2. You can find more information about IDE integration [[here>>doc:General Maven Documentation||anchor="IDE Integration"]].
95		-
96		-== Step 6: Building WebObjects Applications with Maven ==
97		-
98		-Now, building your project with Maven is easy. Go to the project folder on Terminal and execute:
99		-
100		-{{noformat}}
101		-mvn clean package
102		-
103		-{{/noformat}}
104		-
105		-This goal will generate a WOA package inside the target folder of your project. It also generates two compressed packages: one for woapplication and other for the webserver resources.
106		-
107		-To install your project into your local repository:
108		-
109		-{{noformat}}
110		-mvn clean install
111		-
112		-{{/noformat}}
113		-
114		-This will install your project into {{code language="none"}}~/.m2/repository/your/project/groupId/artifactId/version/...{{/code}}
	153	+(% class="auto-cursor-target" %)
	154	+You're done.