io microsphere net ExtendableProtocolURLStreamHandler

ExtendableProtocolURLStreamHandler

Type: Class | Module: microsphere-java-core | Package: io.microsphere.net | Since: 1.0.0

Source: microsphere-java-core/src/main/java/io/microsphere/net/ExtendableProtocolURLStreamHandler.java

Overview

Extendable Protocol URLStreamHandler class supports the sub-protocols, like : {protocol:{sub-protocols[0]}: ... :{sub-protocols[n]}://... },

- {protocol} : The protocol of `URLStreamHandler URLStreamHandler` is recognized by `URL` (required) 
- {sub-protocols} : the list of sub-protocols that is `#resolveSubProtocols(URL) resolved` from `URL` (optional) 

The method #initSubProtocolURLConnectionFactories(List) that is overridden allows the sub-protocols to be extended, the prerequisite is the method #init() being invoked later.

If no SubProtocolURLConnectionFactory initialized or URLConnection open, the #openFallbackConnection(URL, Proxy) fallback strategy will be applied.

If there is no requirement to support the sub-protocol, the subclass only needs to override #openConnection(URL, Proxy) method.

If an instance is instantiated by the default constructor, the implementation class must the obey conventions as follow:

- The class must be the top level
- The simple class name must be "Handler"
- The class must not be present in the "default" or builtin package({@linkURLUtils #DEFAULT_HANDLER_PACKAGE_PREFIX "sun.net.www.protocol"})

A new instance also can specify some protocol via #ExtendableProtocolURLStreamHandler(String) the constructor with the protocol argument.

Node: these methods are overridden making final:

- `#openConnection(URL)`
- `#parseURL(URL, String, int, int)`
- `#equals(URL, URL)`
- `#hostsEqual(URL, URL)`
- `#hashCode(URL)`
- `#toExternalForm(URL)`

Example Usage

Consider a custom protocol handler for "jdbc" supporting sub-protocols like "mysql", "postgresql", etc.:

`public class Handler extends ExtendableProtocolURLStreamHandler {
    public Handler() {
        super("jdbc");
    `

### Declaration

```java
public abstract class ExtendableProtocolURLStreamHandler extends URLStreamHandler
```

**Author:** Mercy

## Version Information

- **Introduced in:** `1.0.0`
- **Current Project Version:** `0.1.10-SNAPSHOT`

## Version Compatibility

This component is tested and compatible with the following Java versions:

| Java Version | Status |
|:---:|:---:|
| Java 8 | ✅ Compatible |
| Java 11 | ✅ Compatible |
| Java 17 | ✅ Compatible |
| Java 21 | ✅ Compatible |
| Java 25 | ✅ Compatible |

## Examples

```java
public class Handler extends ExtendableProtocolURLStreamHandler {
    public Handler() {
        super("jdbc");
    }

    @Override
    protected void initSubProtocolURLConnectionFactories(List factories) {
        factories.add(new JdbcSubProtocolConnectionFactory());
    }

    @Override
    protected URLConnection openFallbackConnection(URL url, Proxy proxy) throws IOException {
        throw new IOException("Unsupported JDBC sub-protocol: " + url.getProtocol());
    }
}
```

## Usage

### Maven Dependency

Add the following dependency to your `pom.xml`:

```xml

    io.github.microsphere-projects
    microsphere-java-core
    ${microsphere-java.version}

```

> **Tip:** Use the BOM (`microsphere-java-dependencies`) for consistent version management. See the [Getting Started](https://github.com/microsphere-projects/microsphere-java#getting-started) guide.

### Import

```java
import io.microsphere.net.ExtendableProtocolURLStreamHandler;
```

## API Reference

### Public Methods

| Method | Description |
|--------|-------------|
| `getHandlePackagesPropertyValue` | The default constructor must obey the following conventions: |
| `init` |  |
| `customizeSubProtocolURLConnectionFactories` | Initialize `SubProtocolURLConnectionFactory SubProtocolURLConnectionFactories` |
| `openConnection` |  |
| `getProtocol` |  |

### Method Details

#### `getHandlePackagesPropertyValue`

```java
public static String getHandlePackagesPropertyValue()
```

The default constructor must obey the following conventions:

    - The class must be the top level
    - The simple class name must be "Handler"
    - The class must not be present in the "default" or builtin package(`URLUtils#DEFAULT_HANDLER_PACKAGE_PREFIX "sun.net.www.protocol"`)

/
public ExtendableProtocolURLStreamHandler() {
Class currentClass = getClass();
assertConventions(currentClass);
String packageName = appendHandlerPackage(currentClass);
this.protocol = resolveConventionProtocol(packageName);
}

public ExtendableProtocolURLStreamHandler(String protocol) {
this.protocol = protocol;
}

#### `customizeSubProtocolURLConnectionFactories`

```java
public void customizeSubProtocolURLConnectionFactories(Consumer> factoriesCustomizer)
```

Initialize `SubProtocolURLConnectionFactory SubProtocolURLConnectionFactories`

## See Also

- `SubProtocolURLConnectionFactory`
- `URLStreamHandler`

---

*This documentation was auto-generated from the source code of [microsphere-java](https://github.com/microsphere-projects/microsphere-java).*