sql/types/DataTypes.java

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *    http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 package org.apache.spark.sql.types;
0019
0020 import java.util.*;
0021
0022 import org.apache.spark.annotation.Stable;
0023
0024 /**
0025  * To get/create specific data type, users should use singleton objects and factory methods
0026  * provided by this class.
0027  *
0028  * @since 1.3.0
0029  */
0030 @Stable
0031 public class DataTypes {
0032   /**
0033    * Gets the StringType object.
0034    */
0035   public static final DataType StringType = StringType$.MODULE$;
0036
0037   /**
0038    * Gets the BinaryType object.
0039    */
0040   public static final DataType BinaryType = BinaryType$.MODULE$;
0041
0042   /**
0043    * Gets the BooleanType object.
0044    */
0045   public static final DataType BooleanType = BooleanType$.MODULE$;
0046
0047   /**
0048    * Gets the DateType object.
0049    */
0050   public static final DataType DateType = DateType$.MODULE$;
0051
0052   /**
0053    * Gets the TimestampType object.
0054    */
0055   public static final DataType TimestampType = TimestampType$.MODULE$;
0056
0057   /**
0058    * Gets the CalendarIntervalType object.
0059    */
0060   public static final DataType CalendarIntervalType = CalendarIntervalType$.MODULE$;
0061
0062   /**
0063    * Gets the DoubleType object.
0064    */
0065   public static final DataType DoubleType = DoubleType$.MODULE$;
0066
0067   /**
0068    * Gets the FloatType object.
0069    */
0070   public static final DataType FloatType = FloatType$.MODULE$;
0071
0072   /**
0073    * Gets the ByteType object.
0074    */
0075   public static final DataType ByteType = ByteType$.MODULE$;
0076
0077   /**
0078    * Gets the IntegerType object.
0079    */
0080   public static final DataType IntegerType = IntegerType$.MODULE$;
0081
0082   /**
0083    * Gets the LongType object.
0084    */
0085   public static final DataType LongType = LongType$.MODULE$;
0086
0087   /**
0088    * Gets the ShortType object.
0089    */
0090   public static final DataType ShortType = ShortType$.MODULE$;
0091
0092   /**
0093    * Gets the NullType object.
0094    */
0095   public static final DataType NullType = NullType$.MODULE$;
0096
0097   /**
0098    * Creates an ArrayType by specifying the data type of elements ({@code elementType}).
0099    * The field of {@code containsNull} is set to {@code true}.
0100    */
0101   public static ArrayType createArrayType(DataType elementType) {
0102     if (elementType == null) {
0103       throw new IllegalArgumentException("elementType should not be null.");
0104     }
0105     return new ArrayType(elementType, true);
0106   }
0107
0108   /**
0109    * Creates an ArrayType by specifying the data type of elements ({@code elementType}) and
0110    * whether the array contains null values ({@code containsNull}).
0111    */
0112   public static ArrayType createArrayType(DataType elementType, boolean containsNull) {
0113     if (elementType == null) {
0114       throw new IllegalArgumentException("elementType should not be null.");
0115     }
0116     return new ArrayType(elementType, containsNull);
0117   }
0118
0119   /**
0120    * Creates a DecimalType by specifying the precision and scale.
0121    */
0122   public static DecimalType createDecimalType(int precision, int scale) {
0123     return DecimalType$.MODULE$.apply(precision, scale);
0124   }
0125
0126   /**
0127    * Creates a DecimalType with default precision and scale, which are 10 and 0.
0128    */
0129   public static DecimalType createDecimalType() {
0130     return DecimalType$.MODULE$.USER_DEFAULT();
0131   }
0132
0133   /**
0134    * Creates a MapType by specifying the data type of keys ({@code keyType}) and values
0135    * ({@code keyType}). The field of {@code valueContainsNull} is set to {@code true}.
0136    */
0137   public static MapType createMapType(DataType keyType, DataType valueType) {
0138     if (keyType == null) {
0139       throw new IllegalArgumentException("keyType should not be null.");
0140     }
0141     if (valueType == null) {
0142       throw new IllegalArgumentException("valueType should not be null.");
0143     }
0144     return new MapType(keyType, valueType, true);
0145   }
0146
0147   /**
0148    * Creates a MapType by specifying the data type of keys ({@code keyType}), the data type of
0149    * values ({@code keyType}), and whether values contain any null value
0150    * ({@code valueContainsNull}).
0151    */
0152   public static MapType createMapType(
0153       DataType keyType,
0154       DataType valueType,
0155       boolean valueContainsNull) {
0156     if (keyType == null) {
0157       throw new IllegalArgumentException("keyType should not be null.");
0158     }
0159     if (valueType == null) {
0160       throw new IllegalArgumentException("valueType should not be null.");
0161     }
0162     return new MapType(keyType, valueType, valueContainsNull);
0163   }
0164
0165   /**
0166    * Creates a StructField by specifying the name ({@code name}), data type ({@code dataType}) and
0167    * whether values of this field can be null values ({@code nullable}).
0168    */
0169   public static StructField createStructField(
0170       String name,
0171       DataType dataType,
0172       boolean nullable,
0173       Metadata metadata) {
0174     if (name == null) {
0175       throw new IllegalArgumentException("name should not be null.");
0176     }
0177     if (dataType == null) {
0178       throw new IllegalArgumentException("dataType should not be null.");
0179     }
0180     if (metadata == null) {
0181       throw new IllegalArgumentException("metadata should not be null.");
0182     }
0183     return new StructField(name, dataType, nullable, metadata);
0184   }
0185
0186   /**
0187    * Creates a StructField with empty metadata.
0188    *
0189    * @see #createStructField(String, DataType, boolean, Metadata)
0190    */
0191   public static StructField createStructField(String name, DataType dataType, boolean nullable) {
0192     return createStructField(name, dataType, nullable, (new MetadataBuilder()).build());
0193   }
0194
0195   /**
0196    * Creates a StructType with the given list of StructFields ({@code fields}).
0197    */
0198   public static StructType createStructType(List<StructField> fields) {
0199     return createStructType(fields.toArray(new StructField[fields.size()]));
0200   }
0201
0202   /**
0203    * Creates a StructType with the given StructField array ({@code fields}).
0204    */
0205   public static StructType createStructType(StructField[] fields) {
0206     if (fields == null) {
0207       throw new IllegalArgumentException("fields should not be null.");
0208     }
0209     Set<String> distinctNames = new HashSet<>();
0210     for (StructField field : fields) {
0211       if (field == null) {
0212         throw new IllegalArgumentException(
0213           "fields should not contain any null.");
0214       }
0215
0216       distinctNames.add(field.name());
0217     }
0218     if (distinctNames.size() != fields.length) {
0219       throw new IllegalArgumentException("fields should have distinct names.");
0220     }
0221
0222     return StructType$.MODULE$.apply(fields);
0223   }
0224 }