370 lines
8.2 KiB
Markdown
370 lines
8.2 KiB
Markdown
# Connection & Session Management
|
|
|
|
This reference covers establishing and managing connections to OMERO servers using BlitzGateway.
|
|
|
|
## Basic Connection
|
|
|
|
### Standard Connection Pattern
|
|
|
|
```python
|
|
from omero.gateway import BlitzGateway
|
|
|
|
# Create connection
|
|
conn = BlitzGateway(username, password, host=host, port=4064)
|
|
|
|
# Connect to server
|
|
if conn.connect():
|
|
print("Connected successfully")
|
|
# Perform operations
|
|
conn.close()
|
|
else:
|
|
print("Failed to connect")
|
|
```
|
|
|
|
### Connection Parameters
|
|
|
|
- **username** (str): OMERO user account name
|
|
- **password** (str): User password
|
|
- **host** (str): OMERO server hostname or IP address
|
|
- **port** (int): Server port (default: 4064)
|
|
- **secure** (bool): Force encrypted connection (default: False)
|
|
|
|
### Secure Connection
|
|
|
|
To ensure all data transfers are encrypted:
|
|
|
|
```python
|
|
conn = BlitzGateway(username, password, host=host, port=4064, secure=True)
|
|
conn.connect()
|
|
```
|
|
|
|
## Context Manager Pattern (Recommended)
|
|
|
|
Use context managers for automatic connection management and cleanup:
|
|
|
|
```python
|
|
from omero.gateway import BlitzGateway
|
|
|
|
with BlitzGateway(username, password, host=host, port=4064) as conn:
|
|
# Connection automatically established
|
|
for project in conn.getObjects('Project'):
|
|
print(project.getName())
|
|
# Connection automatically closed on exit
|
|
```
|
|
|
|
**Benefits:**
|
|
- Automatic `connect()` call
|
|
- Automatic `close()` call on exit
|
|
- Exception-safe resource cleanup
|
|
- Cleaner code
|
|
|
|
## Session Management
|
|
|
|
### Connection from Existing Client
|
|
|
|
Create BlitzGateway from an existing `omero.client` session:
|
|
|
|
```python
|
|
import omero.clients
|
|
from omero.gateway import BlitzGateway
|
|
|
|
# Create client and session
|
|
client = omero.client(host, port)
|
|
session = client.createSession(username, password)
|
|
|
|
# Create BlitzGateway from existing client
|
|
conn = BlitzGateway(client_obj=client)
|
|
|
|
# Use connection
|
|
# ...
|
|
|
|
# Close when done
|
|
conn.close()
|
|
```
|
|
|
|
### Retrieve Session Information
|
|
|
|
```python
|
|
# Get current user information
|
|
user = conn.getUser()
|
|
print(f"User ID: {user.getId()}")
|
|
print(f"Username: {user.getName()}")
|
|
print(f"Full Name: {user.getFullName()}")
|
|
print(f"Is Admin: {conn.isAdmin()}")
|
|
|
|
# Get current group
|
|
group = conn.getGroupFromContext()
|
|
print(f"Current Group: {group.getName()}")
|
|
print(f"Group ID: {group.getId()}")
|
|
```
|
|
|
|
### Check Admin Privileges
|
|
|
|
```python
|
|
if conn.isAdmin():
|
|
print("User has admin privileges")
|
|
|
|
if conn.isFullAdmin():
|
|
print("User is full administrator")
|
|
else:
|
|
# Check specific admin privileges
|
|
privileges = conn.getCurrentAdminPrivileges()
|
|
print(f"Admin privileges: {privileges}")
|
|
```
|
|
|
|
## Group Context Management
|
|
|
|
OMERO uses groups to manage data access permissions. Users can belong to multiple groups.
|
|
|
|
### Get Current Group Context
|
|
|
|
```python
|
|
# Get the current group context
|
|
group = conn.getGroupFromContext()
|
|
print(f"Current group: {group.getName()}")
|
|
print(f"Group ID: {group.getId()}")
|
|
```
|
|
|
|
### Query Across All Groups
|
|
|
|
Use group ID `-1` to query across all accessible groups:
|
|
|
|
```python
|
|
# Set context to query all groups
|
|
conn.SERVICE_OPTS.setOmeroGroup('-1')
|
|
|
|
# Now queries span all accessible groups
|
|
image = conn.getObject("Image", image_id)
|
|
projects = conn.listProjects()
|
|
```
|
|
|
|
### Switch to Specific Group
|
|
|
|
Switch context to work within a specific group:
|
|
|
|
```python
|
|
# Get group ID from an object
|
|
image = conn.getObject("Image", image_id)
|
|
group_id = image.getDetails().getGroup().getId()
|
|
|
|
# Switch to that group's context
|
|
conn.SERVICE_OPTS.setOmeroGroup(group_id)
|
|
|
|
# Subsequent operations use this group context
|
|
projects = conn.listProjects()
|
|
```
|
|
|
|
### List Available Groups
|
|
|
|
```python
|
|
# Get all groups for current user
|
|
for group in conn.getGroupsMemberOf():
|
|
print(f"Group: {group.getName()} (ID: {group.getId()})")
|
|
```
|
|
|
|
## Advanced Connection Features
|
|
|
|
### Substitute User Connection (Admin Only)
|
|
|
|
Administrators can create connections acting as other users:
|
|
|
|
```python
|
|
# Connect as admin
|
|
admin_conn = BlitzGateway(admin_user, admin_pass, host=host, port=4064)
|
|
admin_conn.connect()
|
|
|
|
# Get target user
|
|
target_user = admin_conn.getObject("Experimenter", user_id).getName()
|
|
|
|
# Create connection as that user
|
|
user_conn = admin_conn.suConn(target_user)
|
|
|
|
# Operations performed as target user
|
|
for project in user_conn.listProjects():
|
|
print(project.getName())
|
|
|
|
# Close substitute connection
|
|
user_conn.close()
|
|
admin_conn.close()
|
|
```
|
|
|
|
### List Administrators
|
|
|
|
```python
|
|
# Get all administrators
|
|
for admin in conn.getAdministrators():
|
|
print(f"ID: {admin.getId()}, Name: {admin.getFullName()}, "
|
|
f"Username: {admin.getOmeName()}")
|
|
```
|
|
|
|
## Connection Lifecycle
|
|
|
|
### Closing Connections
|
|
|
|
Always close connections to free server resources:
|
|
|
|
```python
|
|
try:
|
|
conn = BlitzGateway(username, password, host=host, port=4064)
|
|
conn.connect()
|
|
|
|
# Perform operations
|
|
|
|
except Exception as e:
|
|
print(f"Error: {e}")
|
|
finally:
|
|
if conn:
|
|
conn.close()
|
|
```
|
|
|
|
### Check Connection Status
|
|
|
|
```python
|
|
if conn.isConnected():
|
|
print("Connection is active")
|
|
else:
|
|
print("Connection is closed")
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
### Robust Connection Pattern
|
|
|
|
```python
|
|
from omero.gateway import BlitzGateway
|
|
import traceback
|
|
|
|
def connect_to_omero(username, password, host, port=4064):
|
|
"""
|
|
Establish connection to OMERO server with error handling.
|
|
|
|
Returns:
|
|
BlitzGateway connection object or None if failed
|
|
"""
|
|
try:
|
|
conn = BlitzGateway(username, password, host=host, port=port, secure=True)
|
|
if conn.connect():
|
|
print(f"Connected to {host}:{port} as {username}")
|
|
return conn
|
|
else:
|
|
print("Failed to establish connection")
|
|
return None
|
|
except Exception as e:
|
|
print(f"Connection error: {e}")
|
|
traceback.print_exc()
|
|
return None
|
|
|
|
# Usage
|
|
conn = connect_to_omero(username, password, host)
|
|
if conn:
|
|
try:
|
|
# Perform operations
|
|
pass
|
|
finally:
|
|
conn.close()
|
|
```
|
|
|
|
## Common Connection Patterns
|
|
|
|
### Pattern 1: Simple Script
|
|
|
|
```python
|
|
from omero.gateway import BlitzGateway
|
|
|
|
# Connection parameters
|
|
HOST = 'omero.example.com'
|
|
PORT = 4064
|
|
USERNAME = 'user'
|
|
PASSWORD = 'pass'
|
|
|
|
# Connect
|
|
with BlitzGateway(USERNAME, PASSWORD, host=HOST, port=PORT) as conn:
|
|
print(f"Connected as {conn.getUser().getName()}")
|
|
# Perform operations
|
|
```
|
|
|
|
### Pattern 2: Configuration-Based Connection
|
|
|
|
```python
|
|
import yaml
|
|
from omero.gateway import BlitzGateway
|
|
|
|
# Load configuration
|
|
with open('omero_config.yaml', 'r') as f:
|
|
config = yaml.safe_load(f)
|
|
|
|
# Connect using config
|
|
with BlitzGateway(
|
|
config['username'],
|
|
config['password'],
|
|
host=config['host'],
|
|
port=config.get('port', 4064),
|
|
secure=config.get('secure', True)
|
|
) as conn:
|
|
# Perform operations
|
|
pass
|
|
```
|
|
|
|
### Pattern 3: Environment Variables
|
|
|
|
```python
|
|
import os
|
|
from omero.gateway import BlitzGateway
|
|
|
|
# Get credentials from environment
|
|
USERNAME = os.environ.get('OMERO_USER')
|
|
PASSWORD = os.environ.get('OMERO_PASSWORD')
|
|
HOST = os.environ.get('OMERO_HOST', 'localhost')
|
|
PORT = int(os.environ.get('OMERO_PORT', 4064))
|
|
|
|
# Connect
|
|
with BlitzGateway(USERNAME, PASSWORD, host=HOST, port=PORT) as conn:
|
|
# Perform operations
|
|
pass
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Use Context Managers**: Always prefer context managers for automatic cleanup
|
|
2. **Secure Connections**: Use `secure=True` for production environments
|
|
3. **Error Handling**: Wrap connection code in try-except blocks
|
|
4. **Close Connections**: Always close connections when done
|
|
5. **Group Context**: Set appropriate group context before queries
|
|
6. **Credential Security**: Never hardcode credentials; use environment variables or config files
|
|
7. **Connection Pooling**: For web applications, implement connection pooling
|
|
8. **Timeouts**: Consider implementing connection timeouts for long-running operations
|
|
|
|
## Troubleshooting
|
|
|
|
### Connection Refused
|
|
|
|
```
|
|
Unable to contact ORB
|
|
```
|
|
|
|
**Solutions:**
|
|
- Verify host and port are correct
|
|
- Check firewall settings
|
|
- Ensure OMERO server is running
|
|
- Verify network connectivity
|
|
|
|
### Authentication Failed
|
|
|
|
```
|
|
Cannot connect to server
|
|
```
|
|
|
|
**Solutions:**
|
|
- Verify username and password
|
|
- Check user account is active
|
|
- Verify group membership
|
|
- Check server logs for details
|
|
|
|
### Session Timeout
|
|
|
|
**Solutions:**
|
|
- Increase session timeout on server
|
|
- Implement session keepalive
|
|
- Reconnect on timeout
|
|
- Use connection pools for long-running applications
|