Skip to content

Updated JavaDocs across driver - Part 1 #754

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lilgreenbird merged 10 commits into from
Jul 25, 2018
Merged

Updated JavaDocs across driver - Part 1 #754

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
49d94e7
updated javadocs
Jul 20, 2018
fb3a2c8
back to prev versions of Geography and Geometry
Jul 21, 2018
4b2a4b1
undo changes to Geography and Geometry as they will be updated in ano…
Jul 23, 2018
df890eb
review updates
Jul 23, 2018
426d377
Merge remote-tracking branch 'upstream/dev' into javadocs
lilgreenbird Jul 23, 2018
b948142
revert Geography and Geometry again
lilgreenbird Jul 23, 2018
20c3b91
fixed typo
lilgreenbird Jul 23, 2018
5dc54bd
review updates
lilgreenbird Jul 24, 2018
3512cb8
review updates
lilgreenbird Jul 24, 2018
beccd2b
fixed javadocs warnings
lilgreenbird Jul 25, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 49 additions & 47 deletions src/main/java/com/microsoft/sqlserver/jdbc/DataTypes.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -531,11 +531,11 @@ static JavaType of(Object obj) {
return JavaType.OBJECT;
}

// Retrieve JDBC to use with this Java type. By default we use the static JDBC type
// associated with the Java type, ignoring the JDBC type specified by the application.
// But this behavior is overridden for certain Java types, like InputStream, which
// require the JDBC type to be specified externally to be able to distinguish between
// ASCII and binary streams.
/**
* Returns the JDBC type to use with this Java type. We use the static JDBC type associated with the Java type by
* default, ignoring the JDBC type specified by the application. This behavior is overridden for certain Java types,
* such as InputStream, which requires the JDBC type to be specified externally in order to distinguish between.
*/
JDBCType getJDBCType(SSType ssType, JDBCType jdbcTypeFromApp) {
return jdbcTypeFromJavaType;
}
Expand Down Expand Up @@ -677,7 +677,7 @@ private JDBCType(Category category, int intValue, String className) {
}

/**
* Gets the integer value of JDBCType
* Returns the integer value of JDBCType.
*
* @return integer representation of JDBCType
*/
Expand Down Expand Up @@ -916,7 +916,7 @@ static JDBCType of(int intValue) throws SQLServerException {
}

/**
* Identify numerically signed data types.
* Identifies numerically signed data types.
*
* @return true if the type can be signed
*/
Expand All @@ -928,7 +928,7 @@ boolean isSigned() {
}

/**
* Identify binary JDBC data types.
* Identifies binary JDBC data types.
*
* @return true if the JDBC type is binary
*/
Expand All @@ -939,7 +939,7 @@ boolean isBinary() {
}

/**
* Identify textual JDBC data types -- those types for which conversion from another type is simply a matter of
* Identifies textual JDBC data types -- those types for which conversion from another type is simply a matter of
* representing that type as a string.
*
* Note: SQLXML does not qualify as a "textual" type in this context. That is, calling, for example,
Expand All @@ -955,7 +955,7 @@ boolean isTextual() {
}

/**
* Identify unsupported JDBC data types.
* Returns if datat types are supported by JDBC.
*
* @param jdbcType
* the JDBC type to check
Expand Down Expand Up @@ -993,7 +993,7 @@ int asJavaSqlType() {
}

/*
* Used for verifying if a data type can be normalized for AE
* Used for verifying if a data type can be normalized for AE.
*/
enum NormalizationAE {
CHARACTER_NORMALIZED_TO(JDBCType.CHAR, EnumSet.of(SSType.CHAR, SSType.VARCHAR, SSType.VARCHARMAX)),
Expand Down Expand Up @@ -1093,51 +1093,53 @@ static final void throwConversionError(String fromType, String toType) throws SQ
SQLServerException.makeFromDriverError(null, null, form.format(msgArgs), null, true);
}

// Max length in Unicode characters allowed by the "short" NVARCHAR type.
// Values longer than this must use NVARCHAR(max) (Yukon or later) or NTEXT (Shiloh)
/**
* Max length in Unicode characters allowed by the "short" NVARCHAR type. Values longer than this must use
* NVARCHAR(max) (Yukon or later) or NTEXT (Shiloh)
*/
final static int SHORT_VARTYPE_MAX_CHARS = 4000;

// Max length in bytes allowed by the "short" VARBINARY/VARCHAR types.
// Values longer than this must use VARBINARY(max)/VARCHAR(max) (Yukon or later) or IMAGE/TEXT (Shiloh)
/**
* Max length in bytes allowed by the "short" VARBINARY/VARCHAR types. Values longer than this must use
* VARBINARY(max)/VARCHAR(max) (Yukon or later) or IMAGE/TEXT (Shiloh)
*/
final static int SHORT_VARTYPE_MAX_BYTES = 8000;

// A type with unlimited max size, known as varchar(max), varbinary(max) and nvarchar(max),
// which has a max size of 0xFFFF, defined by PARTLENTYPE.
/**
* A type with unlimited max size, known as varchar(max), varbinary(max) and nvarchar(max), which has a max size of
* 0xFFFF, defined by PARTLENTYPE.
*/
final static int SQL_USHORTVARMAXLEN = 65535; // 0xFFFF

// From SQL Server 2005 Books Online : ntext, text, and image (Transact-SQL)
// http://msdn.microsoft.com/en-us/library/ms187993.aspx
//
// image
// "... through 2^31 - 1 (2,147,483,687) bytes."
//
// text
// "... maximum length of 2^31 - 1 (2,147,483,687) characters."
//
// ntext
// "... maximum length of 2^30 - 1 (1,073,741,823) characters."
/**
* From SQL Server 2005 Books Online : ntext, text, and image (Transact-SQL)
* http://msdn.microsoft.com/en-us/library/ms187993.aspx
*
* image "... through 2^31 - 1 (2,147,483,687) bytes."
*
* text "... maximum length of 2^31 - 1 (2,147,483,687) characters."
*
* ntext "... maximum length of 2^30 - 1 (1,073,741,823) characters."
*/
final static int NTEXT_MAX_CHARS = 0x3FFFFFFF;
final static int IMAGE_TEXT_MAX_BYTES = 0x7FFFFFFF;

// From SQL Server 2005 Books Online : Transact-SQL Data Types
// http://msdn.microsoft.com/en-us/library/ms179910.aspx
//
// varbinary(max)
// "max indicates that the maximum storage size is 2^31 - 1 bytes. The storage size is the actual
// length of the data entered + 2 bytes."
//
// varchar(max)
// "max indicates that the maximum storage size is 2^31 - 1 bytes. The storage size is the actual
// length of the data entered + 2 bytes."
//
// nvarchar(max)
// "max indicates that the maximum storage size is 2^31 - 1 bytes. The storage size, in bytes,
// is two times the number of characters entered + 2 bytes."
//
// Normally, that would mean that the maximum length of nvarchar(max) data is 0x3FFFFFFE characters
// and that the maximum length of varchar(max) or varbinary(max) data is 0x3FFFFFFD bytes. However...
// Despite the documentation, SQL Server returns 2^30 - 1 and 2^31 - 1 respectively as the PRECISION
// of these types, so use that instead.
/**
* Transact-SQL Data Types: http://msdn.microsoft.com/en-us/library/ms179910.aspx
*
* varbinary(max) "max indicates that the maximum storage size is 2^31 - 1 bytes. The storage size is the actual
* length of the data entered + 2 bytes."
*
* varchar(max) "max indicates that the maximum storage size is 2^31 - 1 bytes. The storage size is the actual
* length of the data entered + 2 bytes."
*
* nvarchar(max) "max indicates that the maximum storage size is 2^31 - 1 bytes. The storage size, in bytes, is two
* times the number of characters entered + 2 bytes."
*
* Normally, that would mean that the maximum length of nvarchar(max) data is 0x3FFFFFFE characters and that the
* maximum length of varchar(max) or varbinary(max) data is 0x3FFFFFFD bytes. However... Despite the documentation,
* SQL Server returns 2^30 - 1 and 2^31 - 1 respectively as the PRECISION of these types, so use that instead.
*/
final static int MAX_VARTYPE_MAX_CHARS = 0x3FFFFFFF;
final static int MAX_VARTYPE_MAX_BYTES = 0x7FFFFFFF;

Expand Down
28 changes: 14 additions & 14 deletions src/main/java/com/microsoft/sqlserver/jdbc/ISQLServerBulkRecord.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,22 +9,22 @@


/**
* The ISQLServerBulkRecord interface can be used to create classes that read in data from any source (such as a file)
* and allow a SQLServerBulkCopy class to write the data to SQL Server tables.
* Provides an interface used to create classes that read in data from any source (such as a file) and allows a
* SQLServerBulkCopy class to write the data to SQL Server tables.
*
* This interface is implemented by {@link SQLServerBulkCommon} Class
*/
public interface ISQLServerBulkRecord {

/**
* Get the ordinals for each of the columns represented in this data record.
* Returns the ordinals for each of the columns represented in this data record.
*
* @return Set of ordinals for the columns.
*/
public java.util.Set<Integer> getColumnOrdinals();

/**
* Get the name of the given column.
* Returns the name of the given column.
*
* @param column
* Column ordinal
Expand All @@ -33,7 +33,7 @@ public interface ISQLServerBulkRecord {
public String getColumnName(int column);

/**
* Get the JDBC data type of the given column.
* Returns the JDBC data type of the given column.
*
* @param column
* Column ordinal
Expand All @@ -42,7 +42,7 @@ public interface ISQLServerBulkRecord {
public int getColumnType(int column);

/**
* Get the precision for the given column.
* Returns the precision for the given column.
*
* @param column
* Column ordinal
Expand All @@ -51,7 +51,7 @@ public interface ISQLServerBulkRecord {
public int getPrecision(int column);

/**
* Get the scale for the given column.
* Returns the scale for the given column.
*
* @param column
* Column ordinal
Expand All @@ -60,7 +60,7 @@ public interface ISQLServerBulkRecord {
public int getScale(int column);

/**
* Indicates whether the column represents an identity column.
* Returns whether the column represents an identity column.
*
* @param column
* Column ordinal
Expand All @@ -69,7 +69,7 @@ public interface ISQLServerBulkRecord {
public boolean isAutoIncrement(int column);

/**
* Gets the data for the current row as an array of Objects.
* Returns the data for the current row as an array of Objects.
*
* Each Object must match the Java language Type that is used to represent the indicated JDBC data type for the
* given column. For more information, see 'Understanding the JDBC Driver Data Types' for the appropriate mappings.
Expand Down Expand Up @@ -130,39 +130,39 @@ public void addColumnMetadata(int positionInFile, String name, int jdbcType, int
int scale) throws SQLServerException;

/**
* Set the format for reading in dates from the file.
* Sets the format for reading in dates from the file.
*
* @param dateTimeFormat
* format to parse data sent as java.sql.Types.TIMESTAMP_WITH_TIMEZONE
*/
public void setTimestampWithTimezoneFormat(String dateTimeFormat);

/**
* Set the format for reading in dates from the file.
* Sets the format for reading in dates from the file.
*
* @param dateTimeFormatter
* format to parse data sent as java.sql.Types.TIMESTAMP_WITH_TIMEZONE
*/
public void setTimestampWithTimezoneFormat(DateTimeFormatter dateTimeFormatter);

/**
* Set the format for reading in dates from the file.
* Sets the format for reading in dates from the file.
*
* @param timeFormat
* format to parse data sent as java.sql.Types.TIME_WITH_TIMEZONE
*/
public void setTimeWithTimezoneFormat(String timeFormat);

/**
* Set the format for reading in dates from the file.
* Sets the format for reading in dates from the file.
*
* @param dateTimeFormatter
* format to parse data sent as java.sql.Types.TIME_WITH_TIMEZONE
*/
public void setTimeWithTimezoneFormat(DateTimeFormatter dateTimeFormatter);

/**
* Retreives <code>dateTimeFormatter</code> for the given column
* Returns the <code>dateTimeFormatter</code> for the given column.
*
* @param column
* Column ordinal
Expand Down
Loading