# embedded-lucene

**Repository Path**: tangzhongli/embedded-lucene

## Basic Information

- **Project Name**: embedded-lucene
- **Description**: 封装lucene，应用内嵌型，提供便捷api
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 7
- **Created**: 2023-11-10
- **Last Updated**: 2023-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Embedded-Lucene

封装了原生Lucene，提供更便捷的Api，开箱即用。

仓库地址:https://gitee.com/alone_coding/embedded-lucene

## 功能简介

### 1.核心功能

- 配置化创建索引数据目录
- 定制字段类型自动配置组合解析器(Analyzer)
- Lucene的Document对象与JavaBean自动双向映射

### 2.仓库操作

- 增删改查，分页查询，高亮查询，排序查询
- 基础的事务支持，异常超时回滚
- 提供仓库类运行时执行切面，支持定制化插件

### 3.支持SpringBoot自动装配

通过 `@EnableEmbeddedLucene` 开启即可

## 快速开始

### 1.原生方式

##### 1.1 定义一个 文档 <=> JavaBean 的映射类

```java

@Data
public class Article {

    // 文档的id
    @DocId
    private Long id;

    @DocField(type = FieldType.TEXT)
    private String title;

    @DocField(type = FieldType.TEXT)
    private String content;

    @DocField(type = FieldType.TEXT)
    private String abContent;

    @DocField(type = FieldType.TEXT)
    private String author;

    // 标记自动填充
    @AutoFill
    @DocField(type = FieldType.DATE)
    private LocalDateTime time;

    @DocField(type = FieldType.BOOL)
    private boolean deleted;

    // 经纬度类型
    @DocField(type = FieldType.LATLON)
    private LatLon latLon;

}
```

##### 1.2 配置EmbeddedLucene

```java
EmbeddedLucene lucene=EmbeddedLucene.create(
        EmbeddedLuceneConfig.builder()
        // 数据落盘的位置,相对路径,绝对路径都可以
        .indexPath("./embedded-lucene-data")
        // 注册映射文档的JAVA类
        .registerSource(Article.class)
        // 为FieldType设置对应解析器
        .fieldTypeAnalyzer(FieldType.TEXT,new IKAnalyzer(true))
        // 仓库类扩展插件
        // 日志输出
        .repositoryHandler(new LogHandler())
        // 字段填充
        .repositoryHandler(new AutoFillHandler(new DefaultAutoFillValProvider()))
        .build());

        // 配置完毕后需手动启动
        lucene.start();
```

##### 1.3 crud操作

```java
// 通过EmbeddedLucene创建仓库类
ElRepository<Article> repository=ElRepository.get(lucene.getSource(Article.class));

        // 新增
        repository.insert(Article.DATA);

        // 修改
        Article article=repository.select(2L);
        article.setContent("updated content");
        repository.update(article);

        // 删除
        repository.delete(Article.DATA);
        repository.delete(1L);

        // 查询
        repository.select(1L);
        repository.selectList();
        repository.selectPage(PageQuery.of(1,10));
```

### 2.SpringBoot工程方式

##### 2.1 配置

yml配置文件

```yaml
embedded-lucene:
  // 映射类所在的包，支持配置多个，没有配置的话会全量扫描影响启动速度
  entity-packages:
    - com.alone.embedded.lucene.a
    - com.alone.embedded.lucene.b
    - com.alone.embedded.lucene.c

  // 数据落盘的位置,相对路径,绝对路径都可以
  index-path: ./embedded-lucene-data
```

配置类

```java
// 开启EmbeddedLucene自动配置
@EnableEmbeddedLucene
@Configuration(proxyBeanMethods = false)
public class EmbeddedLuceneConfigure {

    /**
     * 仓库增强 日志输出
     */
    @Bean
    public RepositoryHandler logHandler() {
        return new LogHandler();
    }

    /**
     * 仓库增强 自动填充
     */
    @Bean
    public RepositoryHandler autoFillHandler() {
        return new AutoFillHandler(new DefaultAutoFillValProvider());
    }

    /**
     * 客制字段解析器
     */
    @Bean
    public FieldTypeAnalyzerMapper fieldTypeAnalyzerMapper() {
        return new DefaultFieldTypeAnalyzerMapper();
    }

    /**
     * 客制JAVA类解析器
     */
    @Bean
    public Analyzer articleAnalyzer() {
        IKAnalyzer ikAnalyzer = new IKAnalyzer(true);
        Map<String, Analyzer> fieldAnalyzers = new HashMap<>(8);
        fieldAnalyzers.put("title", ikAnalyzer);
        fieldAnalyzers.put("content", ikAnalyzer);
        fieldAnalyzers.put("abContent", ikAnalyzer);
        fieldAnalyzers.put("author", ikAnalyzer);
        return new PerFieldAnalyzerWrapper(new StandardAnalyzer(), fieldAnalyzers);
    }
}
```

##### 2.2 标记映射类

```java
// 在原生方式里定义的映射类上添加注解即可，类所在包需在上面配置的包扫描内
@ElEntity(value = "article", analyzerBeanName = "articleAnalyzer")
```

##### 2.3 crud操作

```java

@Service
public class XXXService {

    // 直接从Spring容器中获取仓库操作类
    @Autowired
    private ElRepository<Article> repository;

    public void crud() {
        // 新增
        repository.insert(Article.DATA);

        // 修改
        Article article = repository.select(2L);
        article.setContent("updated content");
        repository.update(article);

        // 删除
        repository.delete(Article.DATA);
        repository.delete(1L);

        // 查询
        repository.select(1L);
        repository.selectList();
        repository.selectPage(PageQuery.of(1, 10));
    }

}
```

## 详细功能

### 1.查询

##### 1.1 基础概念

1. ElRepository提供了三种类型的查询

    - select: 查询单个文档
    - selectList: 查询多个文档
    - selectPage: 分页查询文档


2. 条件查询包装器(ConditionQueryWrapper)
    - 提供链式调用，通过`Wrappers.lambdaQuery()`快速构建作为上述查询的入参使用
    - 所有方法都拥有前置一个`boolean`类型的参数`conditon`， 代表当前方法是否被纳入最终查询中

##### 1.2 模糊查询(like)

like查询通过SimpleQueryParser实现，语法如下

```text
AND '+' 示例: token1+token2
OR '|' 示例: token1|token2
NOT '-' 示例: -token0
PHRASE '"' 示例: "term1 term2 ..."
PREFIX '*' 示例: term*
FUZZY '~N' 示例: term~1
NEAR '~N' 示例: "term1 term2"~5
PRECEDENCE '()' 示例: token1 + (token2 | token3)
```

##### 1.3 分页查询

通过PageQuery传入分页信息：

```java
public class PageQuery {
    // 当前页码
    protected int current;
    // 分页大小
    protected int size;
}
```

> ⚠️注意: 分页查询通过全量扫描然后截取实现，深度分页时可能会出现性能瓶颈甚至异常。

##### 1.4 排序查询

1. 通过Sorts

```java
Sorts.<Article>builder()
        // 方法：升/降序 , 参数一：排序字段 , 参数二：排序纬度
        .asc(Article::getAuthor,SortField.Type.SCORE)
        .desc(Article::getId,SortField.Type.LONG)
        .build();
```

2. 通过ConditionQueryWrapper

```java
Wrappers.<Article>lambdaQuery()
        .sortAsc(Article::getAuthor,SortField.Type.SCORE)
        .sortDesc(Article::getId,SortField.Type.LONG);
```

##### 1.5 一键高亮

高亮查询开启后会自动应用在`1.2 模糊查询(like)`的所有Field上

```java
Wrappers.<Article>lambdaQuery().highlight()
```

也可以通过Formatter自定义高亮样式

```java
Formatter custStyle=new SimpleHTMLFormatter(String.format("<B style=\"color: %s\">","red"),"</B>")
Wrappers.<Article>lambdaQuery().highlight(custStyle);
```

> 不需要高亮的like查询使用`likeNoHighlight(C column, Object value)`方法即可

##### 1.6 经纬度查询

```java
// 以某个坐标为圆心固定半径搜索，半径单位为m
Querys.latLonRadio(
        Article::getLatLon,
        LatLon.of(29.0,120.0),
        100000.0));

// 一个矩形框内搜索，通过这个矩形的左上坐标和右下坐标框定范围
Querys.latLonBox(
        Article::getLatLon,
        LatLon.of(29.0,120.0),
        LatLon.of(30.0,121.0)));
```

##### 1.7 其他查询

```java
// 等于
eq(C column, Object value)

// 小于等于
le(C column, Object value)

// 大于等于
ge(C column, Object value)

// 小于
lt(C column, Object value)

// 大于
gt(C column, Object value)

// 不等于
ne(C column, Object value)

// 等价于sql中的in
in(C column, Collection<?> value)
notIn(C column, Collection<?> value)

// 原生查询
query(Query query)
query(Query query, BooleanClause.Occur occur)

// 只在selectList时生效
limit(int limit)
```

### 2.事务
以一个Source(可以理解成一个文档<=>JavaBean的映射类)为最小粒度资源,
特性如下：
* 传播机制: 支持当前事务，如果不存在，则创建一个新事务,类似Spring中的Propagation.REQUIRED
* 隔离级别: Serialize串行
##### 2.1 编程式事务
```java
UserTransaction transaction = new ElUserTransaction(lucene.getTxManager());
transaction.begin();

repository.insert(Article.DATA);
System.out.println("未提交读。。。。。。。。");
System.out.println(repository.selectPage(PageQuery.of(2, 1)));
System.out.println(repository.select(2L));

transaction.commit();
System.out.println("已提交读。。。。。。。。");
System.out.println(repository.selectPage(PageQuery.of(2, 1)));
System.out.println(repository.select(2L));
```
##### 2.2 声明式事务
使用`@ElTransactional`注解，用法与spring的一致
### 3.扩展点
TODO