# MetaOxide Java API Reference
Complete API documentation for the Java library.
## Table of Contents
- [Installation](#installation)
- [Package Structure](#package-structure)
- [Classes](#classes)
- [Methods](#methods)
- [Data Types](#data-types)
- [Exceptions](#exceptions)
- [Examples](#examples)
## Installation
### Maven
```xml
<dependency>
<groupId>com.metaoxide</groupId>
<artifactId>meta-oxide</artifactId>
<version>0.1.0</version>
</dependency>
```
### Gradle
```gradle
dependencies {
implementation 'com.metaoxide:meta-oxide:0.1.0'
}
```
## Package Structure
```java
package com.metaoxide;
import com.metaoxide.MetaOxide;
import com.metaoxide.Metadata;
import com.metaoxide.OpenGraphData;
import com.metaoxide.TwitterCardData;
import com.metaoxide.MetaOxideException;
```
## Classes
### `MetaOxide`
Main class for extracting metadata from HTML. Implements `AutoCloseable`.
#### Constructor
```java
public MetaOxide(String html, String baseUrl) throws MetaOxideException
```
**Parameters:**
- `html` (String) - HTML content to parse
- `baseUrl` (String) - Base URL for resolving relative URLs
**Throws:**
- `MetaOxideException` - If HTML parsing fails
**Example:**
```java
try (MetaOxide extractor = new MetaOxide(html, "https://example.com")) {
// Use extractor
}
```
**Important:** Use try-with-resources to ensure proper resource cleanup.
## Methods
### `extractAll()`
Extract all metadata formats.
```java
public Metadata extractAll() throws MetaOxideException
```
**Returns:** `Metadata` - All extracted metadata
**Throws:** `MetaOxideException` - If extraction fails
**Example:**
```java
try (MetaOxide extractor = new MetaOxide(html, url)) {
Metadata metadata = extractor.extractAll();
System.out.println("Title: " + metadata.get("title"));
}
```
### `extractBasicMeta()`
Extract basic HTML metadata.
```java
public Metadata extractBasicMeta() throws MetaOxideException
```
**Returns:** `Metadata` - Basic HTML metadata
**Example:**
```java
Metadata basic = extractor.extractBasicMeta();
System.out.println("Title: " + basic.get("title"));
System.out.println("Description: " + basic.get("description"));
```
### `extractOpenGraph()`
Extract Open Graph metadata.
```java
public OpenGraphData extractOpenGraph() throws MetaOxideException
```
**Returns:** `OpenGraphData` or `null` if not present
**Example:**
```java
OpenGraphData og = extractor.extractOpenGraph();
if (og != null) {
System.out.println("OG Title: " + og.getTitle());
System.out.println("OG Image: " + og.getImage());
}
```
### `extractTwitterCard()`
Extract Twitter Card metadata.
```java
public TwitterCardData extractTwitterCard() throws MetaOxideException
```
**Returns:** `TwitterCardData` or `null` if not present
**Example:**
```java
TwitterCardData twitter = extractor.extractTwitterCard();
if (twitter != null) {
System.out.println("Card Type: " + twitter.getCard());
}
```
### `extractJSONLD()`
Extract JSON-LD structured data.
```java
public List<JSONLDData> extractJSONLD() throws MetaOxideException
```
**Returns:** `List<JSONLDData>` - List of JSON-LD objects
**Example:**
```java
List<JSONLDData> jsonld = extractor.extractJSONLD();
for (JSONLDData item : jsonld) {
System.out.println("Type: " + item.getType());
}
```
### `extractMicrodata()`
Extract Microdata items.
```java
public List<MicrodataItem> extractMicrodata() throws MetaOxideException
```
**Returns:** `List<MicrodataItem>` - List of Microdata items
**Example:**
```java
List<MicrodataItem> microdata = extractor.extractMicrodata();
for (MicrodataItem item : microdata) {
System.out.println("Type: " + item.getType());
}
```
### `extractMicroformats()`
Extract Microformats data.
```java
public Map<String, List<Metadata>> extractMicroformats() throws MetaOxideException
```
**Returns:** `Map<String, List<Metadata>>` - Microformats grouped by type
**Example:**
```java
Map<String, List<Metadata>> mf = extractor.extractMicroformats();
if (mf.containsKey("h-card")) {
for (Metadata card : mf.get("h-card")) {
System.out.println("Name: " + card.get("name"));
}
}
```
### `extractDublinCore()`
Extract Dublin Core metadata.
```java
public DublinCoreData extractDublinCore() throws MetaOxideException
```
**Returns:** `DublinCoreData` or `null` if not present
### `extractRelLinks()`
Extract link relations.
```java
public Map<String, List<Link>> extractRelLinks() throws MetaOxideException
```
**Returns:** `Map<String, List<Link>>` - Links grouped by rel type
**Example:**
```java
Map<String, List<Link>> links = extractor.extractRelLinks();
if (links.containsKey("canonical")) {
System.out.println("Canonical: " + links.get("canonical").get(0).getHref());
}
```
### `close()`
Close and release native resources. Automatically called by try-with-resources.
```java
public void close()
```
## Data Types
### `Metadata`
Generic metadata container extending `HashMap<String, Object>`.
```java
public class Metadata extends HashMap<String, Object> {
// Convenience methods
public String getString(String key);
public Integer getInt(String key);
public List<String> getStringList(String key);
}
```
### `OpenGraphData`
Open Graph metadata.
```java
public class OpenGraphData {
private String title;
private String type;
private String image;
private String url;
private String description;
private String siteName;
private String locale;
// Getters
public String getTitle() { return title; }
public String getType() { return type; }
public String getImage() { return image; }
public String getUrl() { return url; }
public String getDescription() { return description; }
public String getSiteName() { return siteName; }
public String getLocale() { return locale; }
}
```
### `TwitterCardData`
Twitter Card metadata.
```java
public class TwitterCardData {
private String card;
private String site;
private String creator;
private String title;
private String description;
private String image;
private String imageAlt;
// Getters
public String getCard() { return card; }
public String getSite() { return site; }
public String getCreator() { return creator; }
public String getTitle() { return title; }
public String getDescription() { return description; }
public String getImage() { return image; }
public String getImageAlt() { return imageAlt; }
}
```
### `MicrodataItem`
Microdata item.
```java
public class MicrodataItem {
private List<String> type;
private Map<String, List<Object>> properties;
private String id;
// Getters
public List<String> getType() { return type; }
public Map<String, List<Object>> getProperties() { return properties; }
public String getId() { return id; }
}
```
### `Link`
Link element.
```java
public class Link {
private String href;
private String rel;
private String media;
private String title;
private String type;
private String hreflang;
// Getters
public String getHref() { return href; }
public String getRel() { return rel; }
// ... other getters
}
```
## Exceptions
### `MetaOxideException`
Base exception for MetaOxide errors.
```java
public class MetaOxideException extends Exception {
public MetaOxideException(String message) {
super(message);
}
public MetaOxideException(String message, Throwable cause) {
super(message, cause);
}
}
```
### Exception Handling
```java
try (MetaOxide extractor = new MetaOxide(html, url)) {
Metadata metadata = extractor.extractAll();
// Use metadata
} catch (MetaOxideException e) {
System.err.println("Extraction failed: " + e.getMessage());
} catch (Exception e) {
System.err.println("Unexpected error: " + e.getMessage());
}
```
## Examples
### Basic Usage
```java
import com.metaoxide.MetaOxide;
import com.metaoxide.Metadata;
public class Example {
public static void main(String[] args) {
String html = "<!DOCTYPE html>...";
try (MetaOxide extractor = new MetaOxide(html, "https://example.com")) {
Metadata metadata = extractor.extractAll();
System.out.println("Title: " + metadata.get("title"));
} catch (Exception e) {
e.printStackTrace();
}
}
}
```
### Extract from URL
```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class URLExtractor {
public static Metadata extractFromURL(String url) throws Exception {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
try (MetaOxide extractor = new MetaOxide(response.body(), url)) {
return extractor.extractAll();
}
}
}
```
### Parallel Processing
```java
import java.util.List;
import java.util.stream.Collectors;
public class ParallelExtractor {
public static List<Metadata> extractMultiple(List<String> urls) {
return urls.parallelStream()
.map(url -> {
try {
return extractFromURL(url);
} catch (Exception e) {
System.err.println("Failed: " + url);
return null;
}
})
.filter(m -> m != null)
.collect(Collectors.toList());
}
}
```
### Spring Boot Service
```java
import org.springframework.stereotype.Service;
import com.metaoxide.MetaOxide;
import com.metaoxide.Metadata;
@Service
public class MetadataService {
public Metadata extract(String html, String url) throws MetaOxideException {
try (MetaOxide extractor = new MetaOxide(html, url)) {
return extractor.extractAll();
}
}
}
```
### Android Usage
```java
import android.os.AsyncTask;
import com.metaoxide.MetaOxide;
import com.metaoxide.Metadata;
public class MetadataTask extends AsyncTask<String, Void, Metadata> {
@Override
protected Metadata doInBackground(String... params) {
String url = params[0];
try {
String html = fetchHTML(url);
try (MetaOxide extractor = new MetaOxide(html, url)) {
return extractor.extractAll();
}
} catch (Exception e) {
e.printStackTrace();
return null;
}
}
@Override
protected void onPostExecute(Metadata metadata) {
if (metadata != null) {
// Update UI
}
}
}
```
### Kotlin Usage
```kotlin
import com.metaoxide.MetaOxide
fun extractMetadata(html: String, url: String): Metadata? {
return try {
MetaOxide(html, url).use { extractor ->
extractor.extractAll()
}
} catch (e: Exception) {
null
}
}
// Usage
val metadata = extractMetadata(html, "https://example.com")
metadata?.let {
println("Title: ${it["title"]}")
}
```
## Thread Safety
MetaOxide is thread-safe. Each thread should create its own instance.
```java
// Safe: Each thread has its own extractor
ExecutorService executor = Executors.newFixedThreadPool(4);
urls.forEach(url -> {
executor.submit(() -> {
try (MetaOxide extractor = new MetaOxide(html, url)) {
// Safe
}
});
});
```
## Performance Tips
1. **Use try-with-resources**: Ensures proper cleanup
2. **Parallel Streams**: Process multiple URLs concurrently
3. **Selective Extraction**: Extract only needed formats
4. **Connection Pooling**: Reuse HTTP client instances
## See Also
- [Getting Started Guide](/docs/getting-started/getting-started-java.md)
- [Spring Boot Integration](/docs/integrations/spring-boot-integration.md)
- [Examples](/examples/real-world/java-spring-service/)