Skip to content

Commit 8232cd4

Browse files
shroffkshroffk
authored
Merge pull request #165 from ChannelFinder/mvn-wrapper
add a maven wrapper
2 parents 1e3c29f + 194fcb7 commit 8232cd4

File tree

4 files changed

+548
-130
lines changed

4 files changed

+548
-130
lines changed

‎.mvn/wrapper/maven-wrapper.properties‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one
2+
# or more contributor license agreements. See the NOTICE file
3+
# distributed with this work for additional information
4+
# regarding copyright ownership. The ASF licenses this file
5+
# to you under the Apache License, Version 2.0 (the
6+
# "License"); you may not use this file except in compliance
7+
# with the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing,
12+
# software distributed under the License is distributed on an
13+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
# KIND, either express or implied. See the License for the
15+
# specific language governing permissions and limitations
16+
# under the License.
17+
wrapperVersion=3.3.2
18+
distributionType=only-script
19+
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip

‎README.md‎

Lines changed: 121 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -1,155 +1,138 @@
1-
### Channel Finder
1+
# Channel Finder
22

3-
#### A simple directory service
3+
ChannelFinder is a directory server, implemented as a REST style web service.
4+
Its intended use is for control systems, namely the EPICS Control system.
45

5-
ChannelFinder is a directory server, implemented as a REST style web service.
6-
Its intended use is within control systems, namely the EPICS Control system, for which it has been written.
6+
- [Documentation](https://channelfinder.readthedocs.io/en/latest/)
7+
- [Releases](https://github.com/ChannelFinder/ChannelFinderService/releases)
8+
- [Docker Containers](https://github.com/ChannelFinder/ChannelFinderService/pkgs/container/channelfinderservice)
79

8-
* Motivation and Objectives
10+
## Description
911

10-
High level applications tend to prefer an hierarchical view of the control system name space. They group channel names by location or physical function. The name space of the EPICS Channel Access protocol, on the other hand, is flat. A good and thoroughly enforced naming convention may solve the problem of creating unique predictable names. It does not free every application from being configured explicitly, so that it knows all channel names it might be interested in beforehand.
12+
* **Motivation and Objectives**
1113

12-
ChannelFinder tries to overcome this limitation by implementing a generic directory service, which applications can query for a list of channels that match certain conditions, such as physical functionality or location. It also provides mechanisms to create channel name aliases, allowing for different perspectives of the same set of channel names.
14+
High level applications tend to prefer a hierarchical view of the control system name space. They group channel names
15+
by location or physical function. The name space of the EPICS Channel Access protocol, on the other hand, is flat. A
16+
good and thoroughly enforced naming convention may solve the problem of creating unique predictable names. It does not
17+
free every application from being configured explicitly, so that it knows all channel names it might be interested in
18+
beforehand.
1319

14-
* Directory Data Structure
20+
ChannelFinder tries to overcome this limitation by implementing a generic directory service, which applications can
21+
query for a list of channels that match certain conditions, such as physical functionality or location. It also
22+
provides mechanisms to create channel name aliases, allowing for different perspectives of the same set of channel
23+
names.
1524

16-
Each directory entry consists of a channel `<name>`, an arbitrary set of `<properties>` (name-value pairs), and an arbitrary set of `<tags>` (names).
25+
* **Directory Data Structure**
1726

18-
* Basic Operation
27+
Each directory entry consists of a channel `<name>`, an arbitrary set of `<properties>` (name-value pairs), and an
28+
arbitrary set of `<tags>` (names).
1929

20-
An application sends an HTTP query to the service, specifying an expression that references tags, properties and their values, or channel names. The service returns a list of matching channels with their properties and tags, as JSON documents.
30+
* **Basic Operation**
2131

32+
An application sends an HTTP query to the service, specifying an expression that references tags, properties and their
33+
values, or channel names. The service returns a list of matching channels with their properties and tags, as JSON
34+
documents.
2235

23-
#### API reference guide
36+
## Installation
2437

25-
https://channelfinder.readthedocs.io/en/latest/
38+
ChannelFinder is a Java EE5 REST-style web service. The directory data is held in a ElasticSearch index.
2639

27-
#### Installation
40+
### Docker Compose
2841

29-
ChannelFinder is a Java EE5 REST-style web service. The directory data is held in a ElasticSearch index.
42+
For using docker containers there is a barebones [docker compose file](./docker-compose.yml).
3043

31-
Collected installation recipes and notes may be found on [wiki pages](https://github.com/ChannelFinder/ChannelFinder-SpringBoot/wiki).
44+
### Manual Installation
3245

3346
* Prerequisites
3447

35-
* JDK 17
36-
* Elastic version 8.2.x
37-
* <For authN/authZ using LDAP:> LDAP server, e.g. OpenLDAP
38-
39-
* setup elastic search
40-
**Install**
41-
Download and install elasticsearch (verision 8.2.0) from [elastic.com](https://www.elastic.co/downloads/past-releases/elasticsearch-8-2-0)
42-
following the instructions for your platform.\
43-
<Alternatively:> Install the elastic server from your distribution using a package manager.
44-
45-
* Build
46-
```
47-
# Debian 10
48-
sudo apt-get install openjdk-17-jdk maven git curl wget
49-
wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-8.2.0-amd64.deb
50-
sudo dpkg -i elasticsearch-8.2.0-amd64.deb
51-
sudo systemctl start elasticsearch
52-
53-
#### Checkout and build ChannelFinder service source
54-
git clone https://github.com/ChannelFinder/ChannelFinderService.git
55-
cd ChannelFinderService
56-
mvn clean install
48+
* JDK 17
49+
* Elastic version 8.11.x
50+
* **For authN/authZ using LDAP:** LDAP server, e.g. OpenLDAP
5751

58-
```
52+
#### Setup Elasticsearch
5953

60-
#### Start the service
54+
Options:
6155

62-
* Using spring boot via Maven
56+
- Download and install elasticsearch (version 8.11.0)
57+
from [elastic.com](https://www.elastic.co) following the instructions for
58+
your platform.
59+
- Install the elastic server from your distribution using a package manager.
60+
- Run Elasticsearch in a [docker container](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html)
6361

64-
```
65-
mvn spring-boot:run
66-
```
62+
#### Running
6763

68-
* or using the jar
64+
```bash
65+
sudo apt-get install openjdk-17-jre git curl wget
66+
sudo systemctl start elasticsearch # Or other command to run elastic search
6967

70-
```
71-
java -jar target/ChannelFinder-4.7.0.jar
68+
# Replace verison with the release you want
69+
wget https://github.com/ChannelFinder/ChannelFinderService/releases/download/ChannelFinder-{version}/ChannelFinder-{version}.jar
70+
java -jar target/ChannelFinder-*.jar
71+
```
72+
73+
Other installation recipes can be found
74+
on [the wiki pages](https://github.com/ChannelFinder/ChannelFinder-SpringBoot/wiki).
75+
76+
### Configuration
77+
78+
By default, the channelfinder service will start on port 8080 with the default settings. To start with a
79+
different `application.properties` file:
80+
81+
```bash
82+
java -Dspring.config.location=file:./application.properties -jar ChannelFinder-*.jar
7283
```
7384

74-
The above command will start the channelfinder service on port 8080 with the default settings,
75-
which use embedded ldap server with users and roles defined in the [`cf.ldif`](src/main/resources/cf.ldif) file.
85+
The default authentication includes an embedded ldap server with users and roles defined in
86+
the [`cf.ldif`](src/main/resources/cf.ldif) file.
7687
Note that `cf.ldif` contains **default credentials** and should only be used during testing and evaluation.
7788

78-
#### Verification
89+
### Verification
7990

80-
To check that the server is running correctly.
91+
To check that the server is running correctly, visit [the default homepage](http://localhost:8080/). For more
92+
information on the api see the [swagger docs endpoint](http://localhost:8080/swagger-ui/index.html).
8193

82-
```
83-
$ curl --fail-with-body http://localhost:8080/ChannelFinder
84-
{
85-
"name" : "ChannelFinder Service",
86-
"version" : "4.7.0",
87-
"elastic" : {
88-
"status" : "Connected",
89-
"clusterName" : "elasticsearch",
90-
"clusterUuid" : "sA2L_cpoRD-H46c_Mya3mA",
91-
"version" : "8.2.0"
92-
}
93-
}
94-
95-
96-
# Verify by creating a simple Channel using the demo auth
97-
$ curl --location -u admin:adminPass --request PUT 'http://localhost:7070/ChannelFinder/resources/channels/test_channel' \
98-
--header 'Content-Type: application/json' \
99-
--data '{
100-
"name": "test_channel",
101-
"owner": "admin"
102-
}'
103-
104-
$ curl --fail-with-body http://localhost:8080/ChannelFinder/resources/channels
105-
106-
...
107-
$ curl --basic -u admin:adminPass --fail-with-body -H 'Content-Type: application/json' \
108-
-X PUT -d '{"name":"foo", "owner":"admin"}' \
109-
http://localhost:8080/ChannelFinder/resources/tags/foo
110-
111-
$ curl --fail-with-body http://localhost:8080/ChannelFinder/resources/tags
112-
113-
...
114-
$ curl --fail-with-body http://localhost:8080/ChannelFinder/resources/tags
115-
[{"name":"foo","owner":"admin","channels":[]}]
116-
117-
$ curl --basic -u admin:1234 --fail-with-body -X DELETE \
118-
http://localhost:8080/ChannelFinder/resources/tags/foo
119-
```
94+
## Development
12095

121-
#### Start up options
96+
It's strongly encouraged to use a modern IDE such as [Intelij](https://www.jetbrains.com/idea/)
97+
and [Eclipse](https://eclipseide.org/).
12298

123-
You can start the channelfinder service with your own applications.properties file as follows:
99+
* Prerequisites
124100

125-
```
126-
mvn spring-boot:run -Dspring.config.location=file:./application.properties
127-
```
128-
or
129-
```
130-
java -Dspring.config.location=file:./application.properties -jar ChannelFinder-4.7.0.jar
131-
```
101+
* JDK 17
102+
* Maven (via package manager or via the wrapper `./mvnw`) (version specified
103+
in [the wrapper properties](./.mvn/wrapper/maven-wrapper.properties))
132104

133-
You can also start up channelfinder with demo data using the command line argument `demo-data` followed by an integer number `n`. For example, `--demo-data=n`. With this argument, `n*1500` channels will be created to simulate some of the most common types of devices found in accelerators like magnets, power supplies, etc...
105+
For the following commands `mvn` can be interchangeably used instead via `./mvnw`
134106

107+
To build:
108+
109+
```bash
110+
mvn clean install
135111
```
136-
java -jar target/ChannelFinder-4.7.*.jar --demo-data=1
137-
java -jar target/ChannelFinder-4.7.*.jar --cleanup=1
138-
```
139-
112+
113+
To test:
114+
115+
```bash
116+
mvn test
140117
```
141-
mvn spring-boot:run -Dspring-boot.run.arguments="--demo-data=1"
142-
mvn spring-boot:run -Dspring-boot.run.arguments="--cleanup=1"
118+
119+
To run the server in development (you need a running version of Elasticsearch)
120+
121+
```bash
122+
mvn spring-boot:run
143123
```
144124

145-
#### Integration tests with Docker containers
125+
### Integration tests with Docker containers
146126

147127
Purpose is to have integration tests for ChannelFinder API with Docker.
148128

149129
See `src/test/java` and package
130+
150131
* `org.phoebus.channelfinder.docker`
151132

152-
Integration tests start docker containers for ChannelFinder and Elasticsearch and run http requests (GET) and curl commands (POST, PUT, DELETE) towards the application to test behavior (read, list, query, create, update, remove) and replies are received and checked if content is as expected.
133+
Integration tests start docker containers for ChannelFinder and Elasticsearch and run http requests (GET, POST, PUT,
134+
DELETE) towards the application to test behavior (read, list, query, create, update, remove) and
135+
replies are received and checked if content is as expected.
153136

154137
There are tests for properties, tags and channels separately and in combination.
155138

@@ -159,42 +142,50 @@ Integration tests can be run in IDE and via Maven.
159142
mvn failsafe:integration-test -DskipITs=false
160143
```
161144

162-
See
145+
See also
146+
163147
* [How to run Integration test with Docker](src/test/resources/INTEGRATIONTEST_DOCKER_RUN.md)
164148
* [Tutorial for Integration test with Docker](src/test/resources/INTEGRATIONTEST_DOCKER_TUTORIAL.md)
165149

166-
#### ChannelFinder data managment
167-
168-
The [cf-manager](https://github.com/ChannelFinder/cf-manager) project provides tools to perform operations on large queries ( potentially the entire directory ).
169-
Some examples of these operations include running checks to validate the pv names or producing reports about the number of active PVs, a list of IOC names, etc..
170-
171150
### Release ChannelFinder Server binaries to maven central
172151

173-
The Phoebus ChannelFinder service uses the maven release plugin to prepare the publish the ChannelFinder server binaries to maven central
152+
The Phoebus ChannelFinder service uses the maven release plugin to prepare the publish the ChannelFinder server binaries
153+
to maven central
174154
using the sonatype repositories.
175155

176-
**Setup**
156+
#### Setup
177157

178158
Create a sonatype account and update the maven settings.xml file with your sonatype credentials
179159

160+
```xml
161+
<servers>
162+
<server>
163+
<id>phoebus-releases</id>
164+
<username>username</username>
165+
<password>*******</password>
166+
</server>
167+
</servers>
180168
```
181-
<servers>
182-
<server>
183-
<id>phoebus-releases</id>
184-
<username>shroffk</username>
185-
<password>*******</password>
186-
</server>
187-
</servers>
188-
```
189169

190-
**Prepare the release**
191-
`mvn release:prepare`
170+
#### Prepare the release
171+
172+
```bash
173+
mvn release:prepare
174+
```
175+
192176
In this step will ensure there are no uncommitted changes, ensure the versions number are correct, tag the scm, etc..
193-
A full list of checks is documented [here](https://maven.apache.org/maven-release/maven-release-plugin/examples/prepare-release.html):
177+
A full list of checks is
178+
documented [here](https://maven.apache.org/maven-release/maven-release-plugin/examples/prepare-release.html):
179+
180+
#### Perform the release
181+
182+
```bash
183+
mvn release:perform
184+
```
194185

195-
**Perform the release**
196-
`mvn release:perform`
197186
Checkout the release tag, build, sign and push the build binaries to sonatype.
198187

199-
**Publish**
200-
Open the staging repository in [sonatype](https://s01.oss.sonatype.org/#stagingRepositories) and hit the *publish* button
188+
#### Publish
189+
190+
Open the staging repository in [sonatype](https://s01.oss.sonatype.org/#stagingRepositories) and hit the *publish*
191+
button

0 commit comments

Comments
 (0)