Commit 4462dfca authored by Greg Cage's avatar Greg Cage

Merge branch 'eclipse-next' into next

parents 871ffac6 931b5801
# The Eclipse Integrated Computational Environment (ICE) Main Repository
Please see [our wiki](https://wiki.eclipse.org/ICE) for detailed information about Eclipse ICE, including where to download binaries.
Please see [the website](https://www.eclipse.org/ice) for more information on the project.
Build instructions are available [on our wiki too](http://wiki.eclipse.org/ICE_Build_Instructions).
## Build Instructions
Contributions follow the standard Eclipse mechanisms and you should check out our [CONTRIBUTING.md](https://github.com/eclipse/ice/blob/master/CONTRIBUTING.md) file for more information. If you are looking at this, then you are most likely using Git and can start the process by issuing
a pull request on our GitHub repo.
Checkout the project and from the org.eclipse.ice.build directory execute
```bash
mvn clean install
```
## Using the project generators
Once the build is complete, use the project generators to get started with a new Eclipse ICE project. From the shell, execute the following for a basic project:
```bash
mvn archetype:generate -DarchetypeGroupId=org.eclipse.ice -DarchetypeArtifactId=data-element-archetype -DarchetypeVersion=1.0-SNAPSHOT -DgroupId=com.test -DartifactId=testApp
```
For a web form project, execute the following
```bash
mvn archetype:generate -DarchetypeGroupId=org.eclipse.ice -DarchetypeArtifactId=data-element-webform-archetype -DarchetypeVersion=1.0-SNAPSHOT -DgroupId=com.test -DartifactId=testApp
```
The group and artifact ids above are examples and should be replaced with the correct ids for your use case.
# Data Element Example
There are a number of examples in the test and org.eclipse.ice.renderer packages. There is also a [gist available](https://code.ornl.gov/snippets/109).
# Commands Examples
Examples for using the Commands tools are available [in the demo bundle](https://github.com/eclipse/ice/tree/next/org.eclipse.ice.demo/src/org/eclipse/ice/demo/commands).
# Getting started on development
If you're using Eclipse for development, you need to install Lombok into the Eclipse environment so that Eclipse knows about the bytecode changes that Lombok makes during the build process. Instructions are available here: https://projectlombok.org/setup/eclipse
Contributions follow the standard Eclipse mechanisms and you should check out our [CONTRIBUTING.md](https://github.com/eclipse/ice/blob/master/CONTRIBUTING.md) file for more information. If you are looking at this, then you are most likely using Git and can start the process by issuing
a pull request on our GitHub repo.
If you're using Eclipse for development, you need to install Lombok into the Eclipse environment so that Eclipse knows about the bytecode changes that Lombok makes during the build process. Instructions are available [at the Lombok site](https://projectlombok.org/setup/eclipse).
Using the project generators
-
# Contacting the development team
Instructions for generating a new project with the maven archeytpes.
pull the org.eclipse.ice.archetypes project
make sure that the data element renderer and annotations projects are built as well
build the package and it should build the archetypes as well.
then you can use mvn archetype:generate -DarchetypeGroupId=org.eclipse.ice -DarchetypeArtifactId=data-element-archetype -DarchetypeVersion=1.0-SNAPSHOT -DgroupId=com.test -DartifactId=testApp
Note* use -DarchetypeArtifactId=data-element-webform-archetype for the webform archetype
replace the group and artifact id's with whatever.
\ No newline at end of file
Please submit a ticket or pull request to contact the team. Alternatively, use the [ice-dev@eclipse.org mailing list](https://accounts.eclipse.org/mailing-list/ice-dev) to post questions.
......@@ -21,6 +21,5 @@
<module>../org.eclipse.ice.dev</module>
<module>../org.eclipse.ice.archetypes</module>
<module>../org.eclipse.ice.commands</module>
<module>../org.eclipse.ice.renderer</module>
</modules>
</project>
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
<name>org.eclipse.ice.data.neutrons</name>
<comment></comment>
<projects>
</projects>
<buildSpec>
<buildCommand>
<name>org.eclipse.jdt.core.javabuilder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.wst.common.project.facet.core.builder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.m2e.core.maven2Builder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.eclipse.wst.validation.validationbuilder</name>
<arguments>
</arguments>
</buildCommand>
</buildSpec>
<natures>
<nature>org.eclipse.jem.workbench.JavaEMFNature</nature>
<nature>org.eclipse.wst.common.modulecore.ModuleCoreNature</nature>
<nature>org.eclipse.jdt.core.javanature</nature>
<nature>org.eclipse.m2e.core.maven2Nature</nature>
<nature>org.eclipse.wst.common.project.facet.core.nature</nature>
<nature>org.eclipse.wst.jsdt.core.jsNature</nature>
</natures>
</projectDescription>
Manifest-Version: 1.0
Built-By: gzi
Build-Jdk: 14.0.1
Created-By: Maven Integration for Eclipse
#Generated by Maven Integration for Eclipse
#Tue Sep 22 09:34:30 EDT 2020
m2e.projectLocation=/home/gzi/Documents/forks/ice/org.eclipse.ice.data.neutrons
m2e.projectName=org.eclipse.ice.data.neutrons
groupId=org.eclipse.ice
artifactId=org.eclipse.ice.data.neutrons
version=1.0-SNAPSHOT
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.eclipse.ice</groupId>
<artifactId>org.eclipse.ice.data.neutrons</artifactId>
<version>1.0-SNAPSHOT</version>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<vaadin.version>14.1.17</vaadin.version>
<failOnMissingWebXml>false</failOnMissingWebXml>
</properties>
<packaging>war</packaging>
<repositories>
<!-- The order of definitions matters. Explicitly defining central here
to make sure it has the highest priority. -->
<!-- Main Maven repository -->
<repository>
<id>central</id>
<url>https://repo.maven.apache.org/maven2</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
<!-- Repository used by many Vaadin add-ons -->
<repository>
<id>Vaadin Directory</id>
<url>https://maven.vaadin.com/vaadin-addons</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
<pluginRepositories>
<!-- Main Maven repository -->
<pluginRepository>
<id>central</id>
<url>https://repo.maven.apache.org/maven2</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-bom</artifactId>
<version>${vaadin.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.eclipse.ice</groupId>
<artifactId>org.eclipse.ice.dev.annotations</artifactId>
<version>3.0.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>3.1.0</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.11</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.vaadin</groupId>
<!-- Replace artifactId with vaadin-core to use only free components -->
<artifactId>vaadin</artifactId>
<exclusions>
<!-- Webjars are only needed when running in Vaadin 13 compatibility
mode -->
<exclusion>
<groupId>com.vaadin.webjar</groupId>
<artifactId>*</artifactId>
</exclusion>
<exclusion>
<groupId>org.webjars.bowergithub.insites</groupId>
<artifactId>*</artifactId>
</exclusion>
<exclusion>
<groupId>org.webjars.bowergithub.polymer</groupId>
<artifactId>*</artifactId>
</exclusion>
<exclusion>
<groupId>org.webjars.bowergithub.polymerelements</groupId>
<artifactId>*</artifactId>
</exclusion>
<exclusion>
<groupId>org.webjars.bowergithub.vaadin</groupId>
<artifactId>*</artifactId>
</exclusion>
<exclusion>
<groupId>org.webjars.bowergithub.webcomponents</groupId>
<artifactId>*</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-spring-boot-starter</artifactId>
<exclusions>
<!-- Excluding so that webjars are not included. -->
<exclusion>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-core</artifactId>
</exclusion>
<exclusion>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
</exclusion>
<exclusion>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-core</artifactId>
</exclusion>
<!-- Remove these exclusions if using embedded Tomcat provided by Spring -->
<exclusion> <!-- declare the exclusion here -->
<groupId>org.apache.tomcat.embed</groupId>
<artifactId>tomcat-embed-core</artifactId>
</exclusion>
<exclusion> <!-- declare the exclusion here -->
<groupId>org.apache.tomcat.embed</groupId>
<artifactId>tomcat-embed-el</artifactId>
</exclusion>
<exclusion> <!-- declare the exclusion here -->
<groupId>org.apache.tomcat.embed</groupId>
<artifactId>tomcat-embed-websocket</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
<build>
<!-- Remove jetty:run if not using jetty -->
<defaultGoal>jetty:run</defaultGoal>
<pluginManagement><!-- lock down plugins versions to avoid using Maven
defaults (may be moved to parent pom) -->
<plugins>
<!-- Replace with whichever servlet container you are using -->
<plugin>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-maven-plugin</artifactId>
<version>9.4.15.v20190215</version>
<configuration>
<scanIntervalSeconds>1</scanIntervalSeconds>
</configuration>
</plugin>
<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>3.1.0</version>
</plugin>
<!-- see http://maven.apache.org/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_jar_packaging -->
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>3.0.2</version>
</plugin>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.0</version>
<configuration>
<release>11</release>
<annotationProcessorPaths>
<path>
<groupId>com.google.dagger</groupId>
<artifactId>dagger-compiler</artifactId>
<version>2.16</version>
</path>
<path>
<groupId>org.eclipse.ice</groupId>
<artifactId>org.eclipse.ice.dev.annotations</artifactId>
<version>3.0.0-SNAPSHOT</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.22.1</version>
</plugin>
<plugin>
<artifactId>maven-jar-plugin</artifactId>
<version>3.0.2</version>
</plugin>
<plugin>
<artifactId>maven-install-plugin</artifactId>
<version>2.5.2</version>
</plugin>
<plugin>
<artifactId>maven-deploy-plugin</artifactId>
<version>2.8.2</version>
</plugin>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-maven-plugin</artifactId>
<version>${vaadin.version}</version>
<executions>
<execution>
<goals>
<goal>prepare-frontend</goal>
<goal>build-frontend</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</pluginManagement>
</build>
</project>
......@@ -29,6 +29,15 @@
<artifactId>maven-failsafe-plugin</artifactId>
<version>2.22.2</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.0</version>
<configuration>
<source>11</source>
<target>11</target>
</configuration>
</plugin>
</plugins>
</build>
......
<?xml version="1.0" encoding="UTF-8"?>
<classpath>
<classpathentry kind="src" output="target/classes" path="src/main/java">
<classpathentry kind="src" output="target/classes"
path="src/main/java">
<attributes>
<attribute name="optional" value="true"/>
<attribute name="maven.pomderived" value="true"/>
<attribute name="optional" value="true" />
<attribute name="maven.pomderived" value="true" />
</attributes>
</classpathentry>
<classpathentry excluding="**" kind="src" output="target/classes" path="src/main/resources">
<classpathentry excluding="**" kind="src"
output="target/classes" path="src/main/resources">
<attributes>
<attribute name="maven.pomderived" value="true"/>
<attribute name="maven.pomderived" value="true" />
</attributes>
</classpathentry>
<classpathentry kind="src" output="target/test-classes" path="src/test/java">
<classpathentry kind="src" output="target/test-classes"
path="src/test/java">
<attributes>
<attribute name="optional" value="true"/>
<attribute name="maven.pomderived" value="true"/>
<attribute name="test" value="true"/>
<attribute name="optional" value="true" />
<attribute name="maven.pomderived" value="true" />
<attribute name="test" value="true" />
</attributes>
</classpathentry>
<classpathentry excluding="**" kind="src" output="target/test-classes" path="src/test/resources">
<classpathentry excluding="**" kind="src"
output="target/test-classes" path="src/test/resources">
<attributes>
<attribute name="maven.pomderived" value="true"/>
<attribute name="test" value="true"/>
<attribute name="maven.pomderived" value="true" />
<attribute name="test" value="true" />
</attributes>
</classpathentry>
<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-11">
<classpathentry kind="con"
path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-11">
<attributes>
<attribute name="maven.pomderived" value="true"/>
<attribute name="maven.pomderived" value="true" />
</attributes>
</classpathentry>
<classpathentry kind="con" path="org.eclipse.m2e.MAVEN2_CLASSPATH_CONTAINER">
<classpathentry kind="con"
path="org.eclipse.m2e.MAVEN2_CLASSPATH_CONTAINER">
<attributes>
<attribute name="maven.pomderived" value="true"/>
<attribute name="org.eclipse.jst.component.nondependency" value=""/>
<attribute name="maven.pomderived" value="true" />
</attributes>
</classpathentry>
<classpathentry kind="con" path="org.eclipse.jdt.junit.JUNIT_CONTAINER/5"/>
<classpathentry kind="src" path="target/generated-sources/annotations">
<classpathentry kind="con"
path="org.eclipse.jdt.junit.JUNIT_CONTAINER/5" />
<classpathentry kind="src"
path="target/generated-sources/annotations">
<attributes>
<attribute name="optional" value="true"/>
<attribute name="maven.pomderived" value="true"/>
<attribute name="ignore_optional_problems" value="true"/>
<attribute name="m2e-apt" value="true"/>
<attribute name="optional" value="true" />
<attribute name="maven.pomderived" value="true" />
<attribute name="ignore_optional_problems" value="true" />
<attribute name="m2e-apt" value="true" />
</attributes>
</classpathentry>
<classpathentry kind="src" output="target/test-classes" path="target/generated-test-sources/test-annotations">
<classpathentry kind="src" output="target/test-classes"
path="target/generated-test-sources/test-annotations">
<attributes>
<attribute name="optional" value="true"/>
<attribute name="maven.pomderived" value="true"/>
<attribute name="ignore_optional_problems" value="true"/>
<attribute name="m2e-apt" value="true"/>
<attribute name="test" value="true"/>
<attribute name="optional" value="true" />
<attribute name="maven.pomderived" value="true" />
<attribute name="ignore_optional_problems" value="true" />
<attribute name="m2e-apt" value="true" />
<attribute name="test" value="true" />
</attributes>
</classpathentry>
<classpathentry kind="output" path="target/classes"/>
<classpathentry kind="output" path="target/classes" />
</classpath>
Eclipse ICE Annotations
=======================
> TODO Intro to annotations included in this bundle
## Annotations
### Data Elements
> TODO Data Element Annotation walkthrough, what is generated, examples
### Persistence
> TODO Persistence Annotation walkthrough, what is generated, examples
## Creating New Annotations
Eclipse ICE Dev Annotations provides tools and interfaces to split Annotation
Processing into two phases: (1) metadata extraction from the element and
annotations in process and (2) file generation.
Currently, using these tools the two phases are occurring manually and the flow
through the "pipeline" is conceptual. This leaves the door open for implementing
an actual pipeline in future revisions.
As an example, suppose we would like to create an annotation that writes some
helpful information to a generated file. Let's call it `@Debug`. Such an
annotation's definition might look something like the following:
```java
/**
* Simple annotation for printing metadata about the annotated element.
*/
@Retention(SOURCE)
@Target({
TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE
})
public @interface Debug {
/**
* Value prepended to printed metadata.
* @return prefix.
*/
public String value() default "Debug:";
}
```
### Phase 1: Metadata Extraction
Metadata extraction occurs through the use of classes extending the
`AbstractAnnotationExtractor<T>` abstract class. Classes extending it must meet
the `AnnotationExtractor<T>` interface which defines the `extract` method:
```java
/**
* Extract information from element and annotations found on or within
* element. The subclass of element is dependent on the annotation and
* implementation of the extractor.
* @param element from which information will be extracted.
* @return extracted information
* @throws InvalidElementException if element is not annotated as expected
* for this annotation extractor.
*/
public T extract(Element element) throws InvalidElementException;
```
In this interface, the type parameter `T` is the type of the metadata returned
by the Extractor. The `AbstractAnnotationExtractor` abstract class contains
methods that might be helpful while extracting metadata but it is not strictly
required that Annotation Extractors extend this abstract base class as long as
it implements the `AnnotationExtractor` interface.
When creating a new annotation, you will likely need to define a new
`AnnotationExtractor` and POJO to hold the metadata. Continuing the `@Debug`
example, a `DebugExtractor` might look something like the following:
```java
/**
* Extract metadata from {@link Debug} annotated elements.
*/
public class DebugExtractor extends AbstractAnnotationExtractor<DebugMetadata> {
public DebugExtractor(Elements elementUtils) {
super(elementUtils);
}
@Override
public DebugMetadata extract(Element element) throws InvalidElementException {