0
# Plugin Services
1

2
Core plugin framework providing the main entry point for Apache Ranger plugins. This module handles plugin lifecycle management, policy evaluation, audit logging, and integration with the broader Ranger ecosystem.
3

4
## Capabilities
5

6
### RangerBasePlugin
7

8
The primary class that all Ranger plugins extend. Provides comprehensive plugin functionality including policy evaluation, audit logging, and lifecycle management.
9

10
```java { .api }
11
/**
12
 * Core plugin implementation that handles policy evaluation, auditing, and plugin lifecycle
13
 */
14
public class RangerBasePlugin {
15
    /**
16
     * Constructor for plugins with default service name
17
     * @param serviceType - Type of service (e.g., "hdfs", "hive", "hbase")
18
     * @param appId - Application identifier for this plugin instance
19
     */
20
    public RangerBasePlugin(String serviceType, String appId);
21
    
22
    /**
23
     * Constructor for plugins with explicit service name
24
     * @param serviceType - Type of service (e.g., "hdfs", "hive", "hbase")
25
     * @param serviceName - Name of the service instance
26
     * @param appId - Application identifier for this plugin instance
27
     */
28
    public RangerBasePlugin(String serviceType, String serviceName, String appId);
29
    
30
    /**
31
     * Constructor with full plugin configuration
32
     * @param pluginConfig - Complete plugin configuration
33
     */
34
    public RangerBasePlugin(RangerPluginConfig pluginConfig);
35
    
36
    /**
37
     * Initialize the plugin - must be called before use
38
     */
39
    public void init();
40
    
41
    /**
42
     * Cleanup plugin resources - called during shutdown
43
     */
44
    public void cleanup();
45
    
46
    /**
47
     * Evaluate access request against policies
48
     * @param request - Access request to evaluate
49
     * @return Access result with allow/deny decision and audit info
50
     */
51
    public RangerAccessResult isAccessAllowed(RangerAccessRequest request);
52
    
53
    /**
54
     * Evaluate multiple access requests
55
     * @param requests - Collection of access requests
56
     * @return Collection of access results
57
     */
58
    public Collection<RangerAccessResult> isAccessAllowed(Collection<RangerAccessRequest> requests);
59
    
60
    /**
61
     * Evaluate data masking policies
62
     * @param request - Access request to evaluate
63
     * @param resultProcessor - Optional result processor for custom handling
64
     * @return Access result with masking information
65
     */
66
    public RangerAccessResult evalDataMaskPolicies(RangerAccessRequest request, RangerAccessResultProcessor resultProcessor);
67
    
68
    /**
69
     * Evaluate row filtering policies
70
     * @param request - Access request to evaluate
71
     * @param resultProcessor - Optional result processor for custom handling
72
     * @return Access result with row filter information
73
     */
74
    public RangerAccessResult evalRowFilterPolicies(RangerAccessRequest request, RangerAccessResultProcessor resultProcessor);
75
    
76
    /**
77
     * Evaluate audit policies for access result
78
     * @param result - Access result to evaluate for auditing
79
     * @return Audit policy evaluation result
80
     */
81
    public RangerAccessResult evalAuditPolicies(RangerAccessResult result);
82
    
83
    /**
84
     * Get resource ACLs for a request
85
     * @param request - Access request
86
     * @return Resource ACLs
87
     */
88
    public RangerResourceACLs getResourceACLs(RangerAccessRequest request);
89
    
90
    /**
91
     * Get the service name for this plugin
92
     * @return Service name
93
     */
94
    public String getServiceName();
95
    
96
    /**
97
     * Get the service definition
98
     * @return Service definition
99
     */
100
    public RangerServiceDef getServiceDef();
101
    
102
    /**
103
     * Get current policy version
104
     * @return Policy version number (nullable)
105
     */
106
    public Long getPolicyVersion();
107
    
108
    /**
109
     * Get current roles version
110
     * @return Roles version number
111
     */
112
    public Long getRolesVersion();
113
    
114
    /**
115
     * Set policies for this plugin
116
     * @param policies - Service policies to set
117
     */
118
    public void setPolicies(ServicePolicies policies);
119
    
120
    /**
121
     * Refresh policies and tags from admin server
122
     */
123
    public void refreshPoliciesAndTags();
124
}
125
```
126

127
**Usage Examples:**
128

129
```java
130
import org.apache.ranger.plugin.service.RangerBasePlugin;
131
import org.apache.ranger.plugin.policyengine.RangerAccessRequestImpl;
132
import org.apache.ranger.plugin.policyengine.RangerAccessResourceImpl;
133
import java.util.*;
134
import java.util.Arrays;
135

136
// Basic plugin setup
137
public class MyHDFSRangerPlugin extends RangerBasePlugin {
138
    public MyHDFSRangerPlugin() {
139
        super("hdfs", "MyHDFSApp");
140
    }
141
    
142
    @Override
143
    public void init() {
144
        super.init();
145
        // Plugin-specific initialization
146
        System.out.println("HDFS Ranger Plugin initialized");
147
    }
148
}
149

150
// Initialize and use plugin
151
MyHDFSRangerPlugin plugin = new MyHDFSRangerPlugin();
152
plugin.init();
153
// Plugin is ready to use after init() - no separate start() method needed
154

155
// Create access request
156
RangerAccessResourceImpl resource = new RangerAccessResourceImpl();
157
resource.setValue("path", "/user/alice/data.txt");
158

159
RangerAccessRequestImpl request = new RangerAccessRequestImpl();
160
request.setResource(resource);
161
request.setAccessType("read");
162
request.setUser("alice");
163
request.setUserGroups(new HashSet<>(Arrays.asList("users", "data-analysts")));
164

165
// Evaluate access
166
RangerAccessResult result = plugin.isAccessAllowed(request);
167
if (result.getIsAllowed()) {
168
    System.out.println("Access granted to " + request.getUser());
169
} else {
170
    System.out.println("Access denied: " + result.getReason());
171
}
172

173
// Auditing is handled automatically during access evaluation
174
// Audit policies can be evaluated separately if needed:
175
// RangerAccessResult auditResult = plugin.evalAuditPolicies(result);
176
```
177

178
### RangerBaseService
179

180
Base service implementation providing common service functionality.
181

182
```java { .api }
183
/**
184
 * Base service implementation with common functionality
185
 */
186
public class RangerBaseService {
187
    // Common service implementation methods
188
}
189
```
190

191
### RangerChainedPlugin
192

193
Plugin implementation that supports chaining multiple policy engines.
194

195
```java { .api }
196
/**
197
 * Plugin implementation supporting policy engine chaining
198
 */
199
public class RangerChainedPlugin {
200
    // Chained plugin functionality
201
}
202
```
203

204
### RangerDefaultRequestProcessor
205

206
Default implementation for processing access requests.
207

208
```java { .api }
209
/**
210
 * Default request processor implementation
211
 */
212
public class RangerDefaultRequestProcessor {
213
    // Default request processing logic
214
}
215
```
216

217
### RangerAuthContext
218

219
Authentication context for plugin operations.
220

221
```java { .api }
222
/**
223
 * Authentication context for plugin operations
224
 */
225
public class RangerAuthContext {
226
    // Authentication context methods
227
}
228
```
229

230
### RangerAuthContextListener
231

232
Listener interface for authentication context changes.
233

234
```java { .api }
235
/**
236
 * Listener for authentication context changes
237
 */
238
public interface RangerAuthContextListener {
239
    // Authentication context change notifications
240
}
241
```
242

243
### ResourceLookupContext
244

245
Context for resource lookup operations.
246

247
```java { .api }
248
/**
249
 * Context for resource lookup operations
250
 */
251
public class ResourceLookupContext {
252
    // Resource lookup context methods
253
}
254
```
255

256
## Plugin Lifecycle
257

258
The typical lifecycle of a Ranger plugin:
259

260
1. **Construction**: Create plugin instance with service type and app ID
261
2. **Initialization**: Call `init()` to initialize configuration and connections
262
3. **Starting**: Call `start()` to begin plugin services
263
4. **Operation**: Process access requests using `isAccessAllowed()`
264
5. **Auditing**: Log all access decisions using `logAudit()`
265
6. **Shutdown**: Call `stop()` to cleanup resources
266

267
## Thread Safety
268

269
- `RangerBasePlugin` is thread-safe for concurrent access evaluation
270
- Multiple threads can safely call `isAccessAllowed()` simultaneously
271
- Audit logging is thread-safe and can be called from multiple threads
272
- Plugin lifecycle methods (`init()`, `start()`, `stop()`) should be called from a single thread
273

274
## Performance Considerations
275

276
- Cache `RangerBasePlugin` instances - initialization is expensive
277
- Use batch evaluation methods when processing multiple requests
278
- Plugin instances are designed to be long-lived and reused
279
- Policy refresh operations are optimized to minimize performance impact