Skip to content

Commit 7ab6f6a

Browse files
marevolCopilot
marevol
and
Copilot
authored
Enhance documentation and testing for ExampleEngine in Fess script plugin (#1)
* Add comprehensive documentation and test coverage for ExampleEngine * Update src/test/java/org/codelibs/fess/script/example/ExampleEngineTest.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 1a025ee commit 7ab6f6a

3 files changed

Lines changed: 296 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 148 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,157 @@
1-
Example Script Plugin for Fess [![Build Status](https://travis-ci.org/codelibs/fess-script-example.svg?branch=master)](https://travis-ci.org/codelibs/fess-script-example)
2-
==========================
1+
# Fess Script Example Plugin
2+
3+
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.codelibs.fess/fess-script-example/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.codelibs.fess/fess-script-example)
4+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
5+
6+
A simple example plugin demonstrating how to create custom script engines for [Fess](https://fess.codelibs.org/), the open-source enterprise search server.
37

48
## Overview
59

6-
This is a example plugin for Fess Script.
10+
This plugin provides a minimal implementation of a custom script engine for Fess. The `ExampleEngine` serves as a template and starting point for developers who want to create their own script engines with custom template processing logic.
11+
12+
### Key Features
713

8-
## Download
14+
- **Simple Implementation**: Demonstrates the basic structure of a Fess script engine
15+
- **Template Pass-through**: Returns template strings unchanged (useful for testing and learning)
16+
- **Full Integration**: Properly integrated with Fess's dependency injection container
17+
- **Comprehensive Tests**: Includes extensive test cases covering edge cases and various scenarios
918

10-
See [Maven Repository](https://repo1.maven.org/maven2/org/codelibs/fess/fess-script-example/).
19+
## Architecture
20+
21+
The plugin extends Fess's `AbstractScriptEngine` class and implements:
22+
23+
- **Template Evaluation**: Process template strings with parameter maps
24+
- **Engine Identification**: Provides a unique name ("example") for the script engine
25+
- **DI Integration**: Configured via LastaDi container for seamless Fess integration
1126

1227
## Installation
1328

14-
See [Plugin](https://fess.codelibs.org/13.12/admin/plugin-guide.html) of Administration guide.
29+
### Prerequisites
30+
31+
- Fess 15.0.0 or later
32+
- Java 21 or later
33+
34+
### Download
35+
36+
You can download the plugin JAR from [Maven Central](https://repo1.maven.org/maven2/org/codelibs/fess/fess-script-example/).
37+
38+
### Plugin Installation
39+
40+
1. Download the latest `fess-script-example-{version}.jar` from the releases
41+
2. Copy the JAR file to your Fess plugin directory (`$FESS_HOME/app/WEB-INF/plugin/`)
42+
3. Restart Fess server
43+
4. The "example" script engine will be available for use
44+
45+
For detailed installation instructions, see the [Fess Plugin Guide](https://fess.codelibs.org/15.0/admin/plugin-guide.html).
46+
47+
## Usage
48+
49+
Once installed, you can use the "example" script engine in your Fess configuration:
50+
51+
```xml
52+
<component name="exampleScriptEngine" class="org.codelibs.fess.script.example.ExampleEngine"/>
53+
```
54+
55+
The engine will process templates by returning them unchanged, making it useful for:
56+
- Testing script engine integration
57+
- Learning how to implement custom script engines
58+
- As a starting point for more complex implementations
59+
60+
## Development
61+
62+
### Building from Source
63+
64+
```bash
65+
git clone https://github.com/codelibs/fess-script-example.git
66+
cd fess-script-example
67+
mvn clean package
68+
```
69+
70+
### Running Tests
71+
72+
```bash
73+
mvn test
74+
```
75+
76+
The test suite includes 19 comprehensive test cases covering:
77+
- Basic functionality
78+
- Edge cases (null/empty inputs)
79+
- Various data types and special characters
80+
- Multi-line templates and large content
81+
- Instance independence and data integrity
82+
83+
### Code Quality
84+
85+
```bash
86+
# Format code
87+
mvn formatter:format
88+
89+
# Check license headers
90+
mvn license:check
91+
92+
# Generate Javadoc
93+
mvn javadoc:javadoc
94+
```
95+
96+
## Project Structure
97+
98+
```
99+
src/
100+
├── main/java/
101+
│ └── org/codelibs/fess/script/example/
102+
│ └── ExampleEngine.java # Main script engine implementation
103+
├── main/resources/
104+
│ └── fess_se++.xml # DI container configuration
105+
└── test/java/
106+
└── org/codelibs/fess/script/example/
107+
└── ExampleEngineTest.java # Comprehensive test suite
108+
```
109+
110+
## Creating Your Own Script Engine
111+
112+
This project serves as a template for creating custom script engines. To create your own:
113+
114+
1. Fork this repository
115+
2. Rename the `ExampleEngine` class
116+
3. Implement your custom template processing logic in the `evaluate` method
117+
4. Update the `getName` method to return your engine's unique identifier
118+
5. Update the DI configuration in `fess_se++.xml`
119+
6. Add appropriate tests
120+
121+
## Dependencies
122+
123+
- **Fess Framework**: Core search server functionality (provided scope)
124+
- **LastaFlute**: Web application framework with DI container
125+
- **DBFlute**: Database access framework
126+
- **OpenSearch**: Search engine integration (provided scope)
127+
- **UTFlute**: Testing framework for LastaFlute applications
128+
129+
## Contributing
130+
131+
We welcome contributions! Please feel free to submit issues, feature requests, or pull requests.
132+
133+
### Development Guidelines
134+
135+
- Follow the existing code style and formatting
136+
- Add comprehensive tests for new functionality
137+
- Update documentation as needed
138+
- Ensure all tests pass before submitting PRs
139+
140+
## License
141+
142+
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
143+
144+
## Support
145+
146+
- **Documentation**: [Fess Official Documentation](https://fess.codelibs.org/)
147+
- **Issues**: [GitHub Issues](https://github.com/codelibs/fess-script-example/issues)
148+
- **Community**: [Fess Community Forum](https://discuss.codelibs.org/)
149+
150+
## Related Projects
151+
152+
- [Fess](https://github.com/codelibs/fess) - The main Fess search server
153+
- [Fess Plugins](https://github.com/codelibs?q=fess-) - Other Fess plugins
154+
155+
---
15156

157+
Developed by [CodeLibs Project](https://github.com/codelibs)

‎src/main/java/org/codelibs/fess/script/example/ExampleEngine.java‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,37 @@
1919

2020
import org.codelibs.fess.script.AbstractScriptEngine;
2121

22+
/**
23+
* Example script engine implementation that demonstrates how to create custom script engines for Fess.
24+
* This implementation simply returns the template string unchanged without any processing.
25+
*/
2226
public class ExampleEngine extends AbstractScriptEngine {
2327

28+
/**
29+
* Creates a new instance of ExampleEngine.
30+
*/
31+
public ExampleEngine() {
32+
super();
33+
}
34+
35+
/**
36+
* Evaluates the given template with the provided parameter map.
37+
* In this example implementation, the template is returned unchanged without any processing.
38+
*
39+
* @param template the template string to evaluate
40+
* @param paramMap the parameter map containing variables for template evaluation
41+
* @return the template string unchanged
42+
*/
2443
@Override
2544
public Object evaluate(final String template, final Map<String, Object> paramMap) {
2645
return template;
2746
}
2847

48+
/**
49+
* Returns the name of this script engine.
50+
*
51+
* @return the name "example" that identifies this script engine
52+
*/
2953
@Override
3054
protected String getName() {
3155
return "example";

‎src/test/java/org/codelibs/fess/script/example/ExampleEngineTest.java‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,4 +54,128 @@ public void test_evaluate() {
5454
public void test_getName() {
5555
assertEquals("example", exampleEngine.getName());
5656
}
57+
58+
// Comprehensive test cases for evaluating various input scenarios
59+
60+
public void test_evaluate_withNullTemplate() {
61+
final Map<String, Object> params = new HashMap<>();
62+
assertNull(exampleEngine.evaluate(null, params));
63+
}
64+
65+
public void test_evaluate_withEmptyTemplate() {
66+
final Map<String, Object> params = new HashMap<>();
67+
assertEquals("", exampleEngine.evaluate("", params));
68+
}
69+
70+
public void test_evaluate_withNullParameterMap() {
71+
assertEquals("test", exampleEngine.evaluate("test", null));
72+
}
73+
74+
public void test_evaluate_withEmptyParameterMap() {
75+
final Map<String, Object> params = new HashMap<>();
76+
assertEquals("test", exampleEngine.evaluate("test", params));
77+
}
78+
79+
public void test_evaluate_withPopulatedParameterMap() {
80+
final Map<String, Object> params = new HashMap<>();
81+
params.put("key1", "value1");
82+
params.put("key2", 123);
83+
params.put("key3", true);
84+
assertEquals("template content", exampleEngine.evaluate("template content", params));
85+
}
86+
87+
public void test_evaluate_withSpecialCharacters() {
88+
final Map<String, Object> params = new HashMap<>();
89+
final String template = "Special chars: !@#$%^&*(){}[]|\\:;\"'<>,.?/~`";
90+
assertEquals(template, exampleEngine.evaluate(template, params));
91+
}
92+
93+
public void test_evaluate_withMultilineTemplate() {
94+
final Map<String, Object> params = new HashMap<>();
95+
final String template = "Line 1\nLine 2\nLine 3";
96+
assertEquals(template, exampleEngine.evaluate(template, params));
97+
}
98+
99+
public void test_evaluate_withJapaneseCharacters() {
100+
final Map<String, Object> params = new HashMap<>();
101+
final String template = "こんにちは世界";
102+
assertEquals(template, exampleEngine.evaluate(template, params));
103+
}
104+
105+
public void test_evaluate_withLongTemplate() {
106+
final Map<String, Object> params = new HashMap<>();
107+
final StringBuilder sb = new StringBuilder();
108+
for (int i = 0; i < 1000; i++) {
109+
sb.append("This is a long template content. ");
110+
}
111+
final String template = sb.toString();
112+
assertEquals(template, exampleEngine.evaluate(template, params));
113+
}
114+
115+
public void test_evaluate_withComplexParameterMap() {
116+
final Map<String, Object> params = new HashMap<>();
117+
params.put("string", "value");
118+
params.put("number", 42);
119+
params.put("boolean", true);
120+
params.put("null", null);
121+
params.put("map", new HashMap<String, String>());
122+
assertEquals("complex template", exampleEngine.evaluate("complex template", params));
123+
}
124+
125+
public void test_getName_consistency() {
126+
assertEquals("example", exampleEngine.getName());
127+
assertEquals("example", exampleEngine.getName());
128+
assertEquals("example", exampleEngine.getName());
129+
}
130+
131+
public void test_getName_returnsConstant() {
132+
final String name1 = exampleEngine.getName();
133+
final String name2 = exampleEngine.getName();
134+
assertSame(name1, name2);
135+
}
136+
137+
public void test_constructor_initialization() {
138+
final ExampleEngine engine = new ExampleEngine();
139+
assertNotNull(engine);
140+
assertEquals("example", engine.getName());
141+
}
142+
143+
public void test_multipleInstances_independence() {
144+
final ExampleEngine engine1 = new ExampleEngine();
145+
final ExampleEngine engine2 = new ExampleEngine();
146+
147+
assertNotSame(engine1, engine2);
148+
assertEquals(engine1.getName(), engine2.getName());
149+
150+
final Map<String, Object> params = new HashMap<>();
151+
assertEquals("test", engine1.evaluate("test", params));
152+
assertEquals("test", engine2.evaluate("test", params));
153+
}
154+
155+
public void test_evaluate_preservesTemplateIntegrity() {
156+
final Map<String, Object> params = new HashMap<>();
157+
params.put("modify", "attempt");
158+
159+
final String originalTemplate = "original template";
160+
final Object result = exampleEngine.evaluate(originalTemplate, params);
161+
162+
assertEquals(originalTemplate, result);
163+
assertTrue(result instanceof String);
164+
assertEquals(String.class, result.getClass());
165+
}
166+
167+
public void test_evaluate_withWhitespaceOnly() {
168+
final Map<String, Object> params = new HashMap<>();
169+
assertEquals(" ", exampleEngine.evaluate(" ", params));
170+
assertEquals(" ", exampleEngine.evaluate(" ", params));
171+
assertEquals("\t", exampleEngine.evaluate("\t", params));
172+
assertEquals("\n", exampleEngine.evaluate("\n", params));
173+
}
174+
175+
public void test_evaluate_returnTypeConsistency() {
176+
final Map<String, Object> params = new HashMap<>();
177+
final Object result = exampleEngine.evaluate("test", params);
178+
assertTrue(result instanceof String);
179+
assertEquals("test", result);
180+
}
57181
}

0 commit comments

Comments
 (0)