Skip to content

Commit 1d109ec

Browse files
JaroslavTulachJaroslavTulach
authored
How to get a Java library from Maven central (#8912)
Tutorial describing how to get a Java library from Maven central including all its **transitive dependencies**.
1 parent 34e1bac commit 1d109ec

File tree

2 files changed

+136
-0
lines changed

2 files changed

+136
-0
lines changed

‎docs/distribution/packaging.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,12 @@ used by the supported polyglot languages. The contents of each subdirectory is
8585
specified on a per-language basis, in the
8686
[polyglot documentation](../polyglot/README.md).
8787

88+
The way to populate the `polyglot` directory is _language dependent_. It is
89+
different for JavaScript or Python, etc. A tutorial describing how to
90+
incorporate a
91+
[Java library](../polyglot/java.md#download-a-java-library-from-maven-central)
92+
is available.
93+
8894
### The `data` Directory
8995

9096
The `data` directory contains any data files and resources that the user needs

‎docs/polyglot/java.md

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,136 @@ main =
6565
>
6666
> - Expand on the detail when there is time.
6767
68+
## Download a Java Library from Maven Central
69+
70+
A typical use-case when bringing in some popular Java library into Enso
71+
ecosystem is to download it (including is **transitive dependencies**) from
72+
[Maven Central](http://maven.org) - a popular place hosting thousands of Java
73+
libraries. Let's **start from scratch** by creating an _empty Enso project_:
74+
75+
```bash
76+
$ bin/enso --new polydemo
77+
$ cd polydemo
78+
polydemo$ find .
79+
.
80+
./src
81+
./src/Main.enso
82+
./package.yaml
83+
```
84+
85+
To populate the appropriate `polyglot/java` subdirectory, let's create following
86+
two files - `pom.xml` and `assembly.xml` and put them into root of the project,
87+
next to `package.yaml` file. The content of `assembly.xml` is:
88+
89+
```xml
90+
<?xml version="1.0"?>
91+
<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
92+
xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
93+
94+
<id>polyglot</id>
95+
<formats>
96+
<format>dir</format>
97+
</formats>
98+
<baseDirectory>/</baseDirectory>
99+
<dependencySets>
100+
<dependencySet>
101+
<useProjectArtifact>false</useProjectArtifact>
102+
<scope>runtime</scope>
103+
<outputDirectory>/</outputDirectory>
104+
<outputFileNameMapping>${artifact.artifactId}-${artifact.baseVersion}.${artifact.extension}</outputFileNameMapping>
105+
</dependencySet>
106+
</dependencySets>
107+
</assembly>
108+
```
109+
110+
and let the content of the `pom.xml` be:
111+
112+
```xml
113+
<?xml version="1.0"?>
114+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
115+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
116+
<modelVersion>4.0.0</modelVersion>
117+
118+
<groupId>com.yourorg.yourproject</groupId>
119+
<artifactId>download</artifactId>
120+
<version>1.0-SNAPSHOT</version>
121+
<packaging>jar</packaging>
122+
123+
<name>Download JARs for Your Project</name>
124+
<build>
125+
<plugins>
126+
<plugin>
127+
<artifactId>maven-assembly-plugin</artifactId>
128+
<version>2.4</version>
129+
<executions>
130+
<execution>
131+
<id>download</id>
132+
<phase>package</phase>
133+
<goals>
134+
<goal>single</goal>
135+
</goals>
136+
<configuration>
137+
<outputDirectory>polyglot</outputDirectory>
138+
<appendAssemblyId>false</appendAssemblyId>
139+
<finalName>java</finalName>
140+
<descriptors>
141+
<descriptor>assembly.xml</descriptor>
142+
</descriptors>
143+
</configuration>
144+
</execution>
145+
</executions>
146+
</plugin>
147+
</plugins>
148+
</build>
149+
<dependencies>
150+
<dependency>
151+
<!-- find your favorite Java library at maven.org
152+
and put the co-ordinates here
153+
-->
154+
<groupId>com.google.analytics</groupId>
155+
<artifactId>google-analytics-data</artifactId>
156+
<version>0.44.0</version>
157+
</dependency>
158+
</dependencies>
159+
</project>
160+
```
161+
162+
The files are instructing [Maven](http://maven.apache.org) - _standard Java
163+
build tool_ - to download
164+
[google-analytics-data library](https://central.sonatype.com/artifact/com.google.analytics/google-analytics-data/0.44.0)
165+
library version `0.44.0` and all _its dependencies_ into your `polyglot/java`
166+
directory. Of course, _feel free to find different library_ on
167+
[Maven central](http://maven.apache.org) to download - edit `pom.xml`
168+
appropriately. Once your files are ready execute:
169+
170+
```bash
171+
polydemo$ ls *ml
172+
assembly.xml package.yaml pom.xml
173+
174+
polyglot$ mvn -q package
175+
176+
polydemo$ ls polyglot/java/*.jar
177+
...
178+
```
179+
180+
the [mvn command](http://maven.apache.org) invokes
181+
[Maven](http://maven.apache.org) which in turns downloads all the requested
182+
library JAR files (52 of them in the case of `google-analytics-data`) into
183+
`polyglot/java` directory. Now you are ready to use them.
184+
185+
There is a class `com.google.analytics.data.v1alpha.AlphaAnalyticsDataClient`
186+
among the downloaded libraries, as such let's modify `src/Main.enso` to:
187+
188+
```ruby
189+
polyglot java import com.google.analytics.data.v1alpha.AlphaAnalyticsDataClient
190+
191+
main =
192+
client = AlphaAnalyticsDataClient.create
193+
client.close
194+
```
195+
196+
run the project and voilá, the Java classes are available to your Enso sources.
197+
68198
## Polyglot Syntax System
69199

70200
The static system, however, lets us do much better in terms of user experience.

0 commit comments

Comments
 (0)