Skip to content

docs: updates the readme: LENS-979 #96

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jul 11, 2023
Merged

docs: updates the readme: LENS-979 #96

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2b86152
updates the README
npushkarskii Jul 6, 2023
8843ad4
Merge branch 'main' into docs-review
npushkarskii Jul 7, 2023
07ad16c
Apply suggestions from code review
npushkarskii Jul 7, 2023
7c5ea8e
updates formatting
npushkarskii Jul 7, 2023
3446939
Update README.md
npushkarskii Jul 11, 2023
911df74
Update README.md
npushkarskii Jul 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 82 additions & 63 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,58 +1,66 @@
# Push API Client

A Coveo Push API Client in Java
A [Coveo Push API ](https://docs.coveo.com/en/12/api-reference/push-api) client library for Java.

## Prerequisites

The Coveo `push-api-client.java` package is stored on GitHub packages.
You will need a personal access token (classic) with at least `read:packages` scope to install this dependency.

For details, see [Authenticating to GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry#authenticating-to-github-packages)

## Installation

### Step 1: Prerequisites
The Coveo `push-api-client.java` package is stored on Github packages. You will need a personal access token (classic) with at least `read:packages` scope to install this dependency.
### Step 1: Update `settings.xml`
You can install this GitHub Package with [Apache Maven by](https://maven.apache.org/) editing the `~/.m2/settings.xml` file:

More info, visit [Authenticating to GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry#authenticating-to-github-packages)
1. Add a repository definition to the GitHub Package.

### Step 2: Update `settings.xml`
You can install this GitHub Package with Apache Maven by editing your `~/.m2/settings.xml`:
```xml
<repository>
<id>github</id>
<url>https://maven.pkg.github.com/coveo/push-api-client.java</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
```

#### The repository to the package
Add a definition to the Github Package
1. Add your GitHub personal access token to install packages from GitHub Packages.

```xml
<repository>
<id>github</id>
<url>https://maven.pkg.github.com/coveo/push-api-client.java</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
```
```xml
<servers>
<server>
<id>github</id>
<username>USERNAME</username>
<password>TOKEN</password>
</server>
</servers>
```

#### Your GitHub personal access token
Your personal access token required to install packages from Github Packages
### Step 2: Add a Coveo dependency to project

Add a Coveo dependency to your Maven project by editing the `pom.xml` file.

```xml
<servers>
<server>
<id>github</id>
<username>USERNAME</username>
<password>TOKEN</password>
</server>
</servers>
<dependency>
<groupId>com.coveo</groupId>
<artifactId>push-api-client.java</artifactId>
<version>2.3.0</version>
</dependency>
```

### Step 3: Add Coveo dependency to project
Using Maven:

### Step 3: Install the project files

Add Coveo dependency to your maven project. Instructions on how to do that available in this [URL](https://github.com/coveo/push-api-client.java/packages/1884180).
To install the updated project files, build the Maven project.

### Step 4: Install
Run via command line
```bash
mvn install
```

## Usage

See more examples in the `./samples` folder.
> See more examples in the `./samples` folder.

```java
import com.coveo.pushapiclient.DocumentBuilder;
Expand Down Expand Up @@ -82,45 +90,56 @@ public class PushOneDocument {
```

## Logging
When pushing multiple documents into your source using a service (e.g. `PushService`, `StreamService`), make sure to configure a **logger** to be able to see what happens.
to do so .. in your `resources` folder.

### Log4j2 XML Configuration Example
To log execution output into the console, use the below `log4j2.xml` configuration:
```xml
<!-- log4j2.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
<Appenders>
<Console name="ConsoleAppender" target="SYSTEM_OUT">
<PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n" />
</Console>
</Appenders>
<Loggers>
<Root level="debug">
<AppenderRef ref="ConsoleAppender" />
</Root>
</Loggers>
</Configuration>
```
If you want to push multiple documents to your Coveo organization and use a service for that (e.g. `PushService`, `StreamService`), you need to configure a **logger** to be able to see what happens.

See [Log4j2 configuration](https://logging.apache.org/log4j/2.x/manual/configuration.html) for more details.
1. Go to your project's root folder.

## Local Setup to Contribute
1. Update the Apache Log4j2 configuration by editing the `log4j2.xml` file.
The following example will print the log execution to the console.

### Formatting
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
<Appenders>
<Console name="ConsoleAppender" target="SYSTEM_OUT">
<PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n" />
</Console>
</Appenders>
<Loggers>
<Root level="debug">
<AppenderRef ref="ConsoleAppender" />
</Root>
</Loggers>
</Configuration>
```

For more details, see [Log4j2 configuration](https://logging.apache.org/log4j/2.x/manual/configuration.html).

## Formatting the code before contributing

This project uses [Google Java Format](https://github.com/google/google-java-format), so make sure your code is properly formatted before opening a pull request.

To enforce code style and formatting rules, run the Maven Spotless plugin:

```bash
mvn spotless:apply
```

## Release

* Tag the commit following semver.
* Bump version in pom.xml
* mvn -P release clean deploy
* cd into ./target
* jar -cvf bundle.jar push-api-client.java-1.0.0-javadoc.jar push-api-client.java-1.0.0-javadoc.jar.asc push-api-client.java-1.0.0-sources.jar push-api-client.java-1.0.0-sources.jar.asc push-api-client.java-1.0.0.jar push-api-client.java-1.0.0.jar.asc push-api-client.java-1.0.0.pom push-api-client.java-1.0.0.pom.asc
* Log into https://oss.sonatype.org/
* Upload newly created bundle.jar
1. Tag the commit according to the [semantic versioning](https://semver.org/).

1. Bump version in `pom.xml`.

1. Run the following commands:

1. `mvn -P release clean deploy`.

1. `cd ./target`.

1. `jar -cvf bundle.jar push-api-client.java-1.0.0-javadoc.jar push-api-client.java-1.0.0-javadoc.jar.asc push-api-client.java-1.0.0-sources.jar push-api-client.java-1.0.0-sources.jar.asc push-api-client.java-1.0.0.jar push-api-client.java-1.0.0.jar.asc push-api-client.java-1.0.0.pom push-api-client.java-1.0.0.pom.asc`

1. Log in to https://oss.sonatype.org/.

1. Upload the newly created `bundle.jar` file.