Install Eclipse & Plugins
Eclipse Indigo (3.7)
If you can access Magnolia's internal network, a preinstalled eclipse for Mac OS X(Cocoa 64) called eclipse-indigo-macosx-cocoa-64.zip can be found at our file server under Product Development/Eclipse
The eclipse-indigo-macosx-cocoa-64.zip bundle was created on 3 August 2011 and consists of the latest core platform + integrated maven support + subclipse + AnyEdit Tools + Freemarker IDE + checkstyle plugin. For more information concerning the preinstalled software/plugins, please look at the Eclipse Installation Details.
m2e 1.0 known issue
Indigo introduces m2e (Maven 2 Eclipse) 1.0, which seems to cause some problems with plugins that are not "known" by m2e. This hits Magnolia with the setproperty Maven plugin. If you have m2e 1.0 installed you will likely get the following error upon importing a Maven project (i.e. a Magnolia module) into Eclipse:
No marketplace entries found to handle Execution currentDate, in /pom.xml in Eclipse. Please see Help for more information.
No worries. Choose to resolve the issue later and import the project.
Now, in the Eclipse Markers view you should get the following Maven error preventing the project from building (you should also receive some negligible warnings about m2e ignoring some plugin's goals):
Plugin execution not covered by lifecycle configuration: info.magnolia:maven-setproperty-plugin:1.1.1:set-property (execution: currentDate, phase: generate-resources)
Again, no worries. To get rid of the error and proceed with project build you'll need to add the following snippet to the pluginManagement/plugins section of your project's pom.xml
<plugin> <!--This plugin's configuration is used to store Eclipse m2e settings only. It has no influence on the Maven build itself. --> <groupId>org.eclipse.m2e</groupId> <artifactId>lifecycle-mapping</artifactId> <version>1.0.0</version> <configuration> <lifecycleMappingMetadata> <pluginExecutions> <pluginExecution> <pluginExecutionFilter> <groupId>info.magnolia</groupId> <artifactId>maven-setproperty-plugin</artifactId> <versionRange>[1.1.1,)</versionRange> <goals> <goal>set-property</goal> </goals> </pluginExecutionFilter> <action> <execute></execute> </action> </pluginExecution> </pluginExecutions> </lifecycleMappingMetadata> </configuration> </plugin>
If your module inherits from magnolia-parent-pom version 20, then m2e should not complain at all as the above fix was applied globally to our parent pom (see http://jira.magnolia-cms.com/browse/BUILD-72). This pom fix might not be needed in the future, as soon as this m2e issue will be accepted and solved.
For some background info and the ratio behind this new behaviour in m2e, please read:
http://wiki.eclipse.org/M2E_plugin_execution_not_covered
http://dev.eclipse.org/mhonarc/lists/m2e-users/thrd7.html starting at http://dev.eclipse.org/mhonarc/lists/m2e-users/msg00448.html
magnolia-empty-webapp configuration
The new version of Maven integration For WTP plugin, will create a /target/m2e-wtp folder and serve project resources from there. This may cause issues when choosing to serve modules without publishing them in the Servers configuration. To solve this,
- go to project Properties -> Deployment Assembly
- remove the m2e-wtp folder
- add src/main/webapp folder and src/main/resources folders
Your configuration should now look similar to that of the screenshot below.
Notice that when importing new modules which magnolia-empty-webapp depends on, the Deployment Assembly configuration will be automatically updated. In the example above, the magnolia-ui-admincentral module was imported after the magnolia-empty-webapp and is now directly served from the eclipse workspace instead of the local Maven repository jar.
Eclipse Helios (3.6)
If you can access Magnolia's internal network, a preinstalled eclipse for Mac OS X(Cocoa 64) called eclipse-helios-macosx-cocoa-64.zip can be found at our file server under Product Development/Eclipse
The eclipse-helios-macosx-cocoa-64.zip bundle was created on 12 January 2011 and consists of the following platform, plugins and related versions (where available):
Name |
Version |
Notes |
---|---|---|
Eclipse Platform |
3.6.1.r361_v20100909-9gF78GrkFqw7GrsZnvz0JWNTeb6fue6896L |
Helios |
AnyEditTools |
2.3.4.201012191830 |
|
CollabNet Merge |
Client 2.2.1 |
|
Eclipse Checkstyle Plug-in |
5.3.0.201012121300 |
|
Eclipse IDE for Java EE Developers |
1.3.1.20100916-1202 |
|
FreeMarker IDE |
1.1.0.v20101206-2100-H28-Beta2 |
no stable release for Helios here |
Google Plugin for Eclipse 3.6 |
1.4.2.v201012211742 |
needed by Freemarker IDE |
Google Web Toolkit SDK 2.0.4 |
2.0.4.v201006301309 |
|
JNA Library |
3.2.7 |
|
Maven Integration for Eclipse (Required) |
0.12.0.20101115-1102 |
|
Maven Integration for WTP (Optional) |
0.11.1.20101108-1810 |
|
Maven SCM handler for Subclipse |
0.12.0.20101207-1600 |
Allows to checkout a maven project into the workspace by right-clicking on a jar dependency |
Memory Analyzer |
1.0.1.201008091353 |
|
Memory Analyzer (Charts) (optional) |
|
|
Subclipse (Required) |
1.6.16 |
|
Subclipse Integration for Mylyn 3.x (Optional) |
3.0.0 |
|
Subversion Client Adapter (Required) |
|
|
Subversion JavaHL Native Library Adapter (Required) |
|
|
Subversion Revision Graph |
1.0.9 |
|
SVNKit Client Adapter (Not required) |
1.6.12 |
|
SVNKit Library |
1.3.4.6888 |
|
Vaadin Eclipse Integration |
1.3.1.201012171040 |
|
Vaadin Visual Editor (EXPERIMENTAL) |
0.6.0.201012080843 |
|
Install Eclipse (3.5)
Download the Java EE edition which includes WTP (web tool project).
Subversive (Subversion Plugin)
Install the plugin
- Help / Install New Software ..
- select: Galileo - http://download.eclipse.org/releases/galileo
- select: Collaboration/Subversive SVN Team Provider
Note: to get the latest stable version you will better use the project's url. I had to do that because eclipse started to block on startups otherwise.
Note: There seems to be a version conflict with Subversive. If you look at the table showing the content of the eclipse-helios-macosx-cocoa-64.zip bundle (in a preceding section, above) you will notice that it includes Subclipse, not Subversive. If you have problems with Subversive you might try Subclipse instead. http://subclipse.tigris.org/update_1.6.x
Connectors
You also have to install a connector. Subversive will prompt you on the first usage.
- open "SVN Repository" perspective (Window -> Open perspective)
- select SVNKit 1.3
- proceed installation
Maven integration (M2Eclipse)
Plugin
- Help -> Install New Software ..
- Add... (to add a new site)
- http://m2eclipse.sonatype.org/sites/m2e
WTP Integration
- Help -> Install New Software ..
- Add... (to add a new site)
- http://m2eclipse.sonatype.org/sites/m2e-extras
- select: Maven Integration for WTP
Subversive Integration
- Help -> Install New Software ..
- Add... (to add a new site)
- http://www.polarion.org/projects/subversive/download/integrations/update-site/
- select: Subversive Integration for M2Eclipse
FreeMarker IDE (optional)
Register the following URLs in Help / Software Updates
- http://download.jboss.org/jbosstools/updates/JBossTools-3.0.3.GA
- select: FreeMarker IDE
Any Edit (optional)
Used for tab to space transformations and other cleanup on save
- http://andrei.gmxhome.de/eclipse
- select: AnyEditTools
JIRA integration (optional)
- Check Mylyn Extras and select JIRA integration
Maven Repository
See Maven setup. Be sure to follow these steps first as else you'll not be able to checkout magnolia properly!
Add SVN Repository
You will have to register our SVN repository in case you want to checkout magnolia modules/projects
- open SVN Repository Exploring Perspective
- add repository location
- http://svn.magnolia-cms.com/svn
Create/Checkout a Project
New Checkout
- open "SVN Repository" perspective (Window -> Open perspective)
- select module/project to check out
- click "Check out as Maven project..." in the context menu
Importing an already checked out project from file system
Sometimes it is more convenient to checkout a project manually and then use the eclipse import function. This is especially helpful if the module to be imported has submodules.
- File -> Import
- in the import dialog select 'Maven Projects'
Setup the Server (Tomcat)
Create a Server
If not yet done create a server.
Deploy the Webapp project
Open Server Edit Pane
Doubleclick on the server item
Server settings: Disable publishing
Make sure that the option Serve modules without publishing is selected. This ensures that the classes are taken from the target directories.
Server settings: Increase timeouts
In these same settings, increase both timeout values by a factor of 10.
Freemarker specific settings
Taglib definitions (tld)
FreeMarker does not search the classpath to find taglib definition. It uses only WEB-INF/lib
and the entries defined in web.xml
directly. There are two workarounds:
A) Register taglib definitions in web.xml
- Edit
web.xml
and add the taglib definitions as follows. It is important to add them beforejsp-property-group
.<jsp-config> <taglib> <taglib-uri>cms-taglib</taglib-uri> <taglib-location>cms-taglib.tld</taglib-location> </taglib> <taglib> <taglib-uri>cms-util-taglib</taglib-uri> <taglib-location>cms-util-taglib.tld</taglib-location> </taglib> <taglib> <taglib-uri>cmsfn-taglib</taglib-uri> <taglib-location>cmsfn-taglib.tld</taglib-location> </taglib> <jsp-property-group> <url-pattern>*.jsp</url-pattern> <page-encoding>UTF-8</page-encoding> </jsp-property-group> </jsp-config>
- Copy the files to
webapp/WEB-INF
.
B) Put minimal JARs into WEB-INF/lib
- In the
webapp
folder, execute:This generates a complete webapp in yourmvn war:inplace
src/webapp
directory as opposed totarget/webapp-name-1.0-SNAPSHOT
. This is an Eclipse specific workaround. - Delete all JARs except the taglib JARs in
src/main/webapp/WEB-INF/lib
- Minimize the taglib JAR
zip -d magnolia-taglib-cms-4.1.1-SNAPSHOT.jar /info/* zip -d magnolia-taglib-utility-4.1.1-SNAPSHOT.jar /info/*
Auto completion
Freemarker templates do not provide automatically auto completion of the provided objects.
The provided objects like ctx, stk or mgnl must be declared to the IDE, that they can be auto completed.
There for a configuration file must be provided in each project in your workspace. The file is named '.freemarker-ide.xml'. I have attached it to this page without the dot at the beginning, or I can't upload it on the Mac otherwise (hidden).
The important part of this configuration file is the declaration of the objects the auto completion should know. I think these four declarations I use make sense:
<value key="mgnl" object-class="info.magnolia.module.templating.MagnoliaTemplatingUtilities"/> <value key="ctx" object-class="info.magnolia.context.MgnlContext"/> <value key="stk" object-class="info.magnolia.module.templatingkit.util.STKUtil"/> <value key="state" object-class="info.magnolia.cms.core.AggregationState"/>
Configure Code Style
If you are an internal developer or a contributor please follow the instructions found here: Coding Conventions.
Tips and Tricks
Get the sources or a linked jar / module
- select the jar (in the Maven Dependencies library)
- right click -> Maven -> Download Sources
Dependencies
The dependencies are resolved inside the workspace. This is quite helpful. But this will only work if the version you reference in the project and the version of the module you checked out has the same version. In some cases you will have to adapt the pom files locally (to point to the current snapshot for instance).
Known Problems
Wrong maven version is used for dependency checks
If the project can't build because of the following message (printed in Maven Console)
[WARN] Rule 0: org.apache.maven.plugin.enforcer.RequireMavenVersion failed with message: Detected Maven Version: 2.1-SNAPSHOT is not in the allowed range [2.0.9,2.0.9].
The expected stacktrace on startup is:
SEVERE: Exception sending context initialized event to listener instance of class info.magnolia.cms.servlets.MgnlServletContextListener java.lang.NullPointerException at info.magnolia.cms.beans.config.PropertiesInitializer.loadAllModuleProperties(PropertiesInitializer.java:92) at info.magnolia.cms.beans.config.PropertiesInitializer.loadAllProperties(PropertiesInitializer.java:79) at info.magnolia.cms.servlets.MgnlServletContextListener.contextInitialized(MgnlServletContextListener.java:176) at org.apache.catalina.core.StandardContext.listenerStart(StandardContext.java:3843) at org.apache.catalina.core.StandardContext.start(StandardContext.java:4350)
You can either add the following to the pluginManagement section in your main project pom to disable the enforcer plugin or select the eclipse profile:
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-enforcer-plugin</artifactId> <configuration> <skip>true</skip> </configuration> </plugin>
Then clean all projects
To ensure that everything is fine you have to check that magnolia-core/target/classes/mgnl-bean.properties exists.
Freemarker can't find tags (tlds)
See #Freemarkerspecificsettings
Project contains duplicate entry
Sometimes the same jar is references twice (by maven and EAR dependencies). This sometimes happens if you open eclipse freshly. To make the project compile again you must remove the ear dependency:
- right click project -> Java EE -> Update EAR libraries
Class Cast Exception: info.magnolia.cms.filters.MgnlMainFilter
Symptom:
SEVERE: Exception starting filter magnoliaFilterChain java.lang.ClassCastException: info.magnolia.cms.filters.MgnlMainFilter at org.apache.catalina.core.ApplicationFilterConfig.getFilter(ApplicationFilterConfig.java:255) at org.apache.catalina.core.ApplicationFilterConfig.setFilterDef(ApplicationFilterConfig.java:397) at org.apache.catalina.core.ApplicationFilterConfig.<init>(ApplicationFilterConfig.java:108) at org.apache.catalina.core.StandardContext.filterStart(StandardContext.java:3709) at org.apache.catalina.core.StandardContext.start(StandardContext.java:4356) at org.apache.catalina.core.ContainerBase.start(ContainerBase.java:1045)
Solution: exclude the servlet api jar. Verify that you don't have the servlet api jar in your maven dependencies.
Example:
<dependency> <groupId>info.magnolia</groupId> <artifactId>magnolia-empty-webapp</artifactId> <version>4.0.1</version> <type>pom</type> <exclusions> <exclusion> <groupId>javax.servlet</groupId> <artifactId>servlet-api</artifactId> </exclusion> </exclusions> </dependency>
Webapp project doesn't work
- make sure that you have only one webapp project open
- add the pom dependency (not only the war dependency) otherwise the dependencies defined in the referenced war file won't be seen
- use mvn war:inplace to overlay the webapp project (make sure that the WEB-INF/web.xml exists
- ensure that you delete WEB-INF/lib after a war:inplace
- check settings
project/project facets/dynamic web module
==> 2.4 works (helios, wtp 2.4), 3.0 doesn't (helios, wtp 3.0)
NPE when configuring tomcat with "don't publish" option
- delete Servers, delete .project and .settings from the webapp and reimport the webapp
webapp is not recognized as webapp and doesn't show in tomcat when trying to add it
- go to
project/project facets
and make suredynamic web module
andjava
andjavascript
facets are checked. - rebuild the project
modules are not installed when installing the webapp
- cause: modules are not visible if the faceted build version of java doesn't match the current version or that used by the webapp project
- solution: update project config and change java version
Trouble shooting step by step
- check if there are any build issues denoted in the problem view
- check if there are any problems denoted in the pom.xml (missing parents, ..)
- check if the project builds in the terminal (by using mvn only)
- are the parent poms available?
- check the maven log in eclipse (select the maven console in the console view)
- are the logs fine?
- verify that there is no version conflict thrown by the enforcer plugin
- if so configure the project to use the eclipse profile in the project settings (maven tab)
- clean the project
- this ensures that maven is used to build the resources
- verify that the resources have been built (module descriptor in
target/classes/META-INF/magnolia
- update project configuration
- right click project -> maven -> update project configuration
- check the maven console (some errors are not reported to the GUI)