{"record":{"id":"c56154923160c1b0","repo":"apache/shardingsphere","slug":"getncharacterstream-c56154","errorCode":null,"errorMessage":"getNCharacterStream","messagePattern":"getNCharacterStream","errorType":"exception","errorClass":"SQLFeatureNotSupportedException","httpStatus":null,"severity":"error","filePath":"kernel/sql-federation/core/src/main/java/org/apache/shardingsphere/sqlfederation/resultset/AbstractUnsupportedOperationSQLFederationResultSet.java","lineNumber":165,"sourceCode":"    \n    @Override\n    public final int getHoldability() throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"getHoldability\");\n    }\n    \n    @Override\n    public final NClob getNClob(final int columnIndex) throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"getNClob\");\n    }\n    \n    @Override\n    public final NClob getNClob(final String columnLabel) throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"getNClob\");\n    }\n    \n    @Override\n    public final Reader getNCharacterStream(final int columnIndex) throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"getNCharacterStream\");\n    }\n    \n    @Override\n    public final Reader getNCharacterStream(final String columnLabel) throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"getNCharacterStream\");\n    }\n    \n    @Override\n    public final Ref getRef(final int columnIndex) throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"getRef\");\n    }\n    \n    @Override\n    public final Ref getRef(final String columnLabel) throws SQLException {\n        throw new SQLFeatureNotSupportedException(\"getRef\");\n    }\n    \n    @Override","sourceCodeStart":147,"sourceCodeEnd":183,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/kernel/sql-federation/core/src/main/java/org/apache/shardingsphere/sqlfederation/resultset/AbstractUnsupportedOperationSQLFederationResultSet.java#L147-L183","documentation":"ShardingSphere's SQL federation engine returns its own ResultSet implementation for cross-database federated queries. That implementation deliberately does not support the JDBC optional-method getNCharacterStream(int), so any call throws SQLFeatureNotSupportedException. The method is declared final in AbstractUnsupportedOperationSQLFederationResultSet and unconditionally rejects the call; it is a design limitation, not a transient fault.","triggerScenarios":"Calling ResultSet.getNCharacterStream(int columnIndex) on a ResultSet produced by a ShardingSphere SQL federation query (SQLFederationResultSet). This happens when application code or an ORM/framework reads NCHAR/NVARCHAR/NCLOB columns as a java.io.Reader by column index.","commonSituations":"Applications migrated to federation mode that previously read national-character columns via getNCharacterStream; ORM libraries (Hibernate, MyBatis type handlers) configured with NCharacterStreamTypeHandler; code reused from a plain MySQL/PostgreSQL driver path where the method worked.","solutions":["Read the column with a supported accessor instead: rs.getString(columnIndex) or rs.getCharacterStream(columnIndex), then convert to Reader if needed.","If an ORM type handler is involved, switch it from NCharacterStream to a string-based handler for federation queries.","If the query does not need federation (single shard, no cross-table join), route it outside sql-federation so the underlying driver's ResultSet is returned.","Request/track support for the method in the ShardingSphere issue tracker if it is essential."],"exampleFix":"// before\nReader reader = resultSet.getNCharacterStream(1);\n\n// after\nReader reader = new StringReader(resultSet.getString(1));","handlingStrategy":"fallback","validationCode":"if (resultSet instanceof SQLFederationResultSet || !resultSet.getClass().getName().startsWith(\"com.mysql\")) { /* use getString */ }","typeGuard":"boolean supportsNCharacterStream(ResultSet rs) { try { rs.getNCharacterStream(rs.getMetaData().getColumnCount() + 0); return true; } catch (SQLFeatureNotSupportedException e) { return false; } }","tryCatchPattern":"try { reader = rs.getNCharacterStream(1); } catch (SQLFeatureNotSupportedException e) { reader = new StringReader(rs.getString(1)); }","preventionTips":["Standardize on getString/getCharacterStream for national-character columns in code that may run under ShardingSphere federation.","Run read-path integration tests with sql-federation enabled before shipping.","Keep a list of unsupported JDBC optional methods from the federation ResultSet classes as a migration checklist."],"tags":["jdbc","sql-federation","resultset","unsupported-operation","national-character"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}