jdk8-mips64-public/jaxws: src/share/jaxws_classes/javax/xml/bind/DatatypeConverterInterface.java@9c07ef4934dd

     1 /*

     2  * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    26 package javax.xml.bind;

    28 /**

    29  * <p>

    30  * The DatatypeConverterInterface is for JAXB provider use only. A

    31  * JAXB provider must supply a class that implements this interface.

    32  * JAXB Providers are required to call the

    33  * {@link DatatypeConverter#setDatatypeConverter(DatatypeConverterInterface)

    34  * DatatypeConverter.setDatatypeConverter} api at

    35  * some point before the first marshal or unmarshal operation (perhaps during

    36  * the call to JAXBContext.newInstance).  This step is necessary to configure

    37  * the converter that should be used to perform the print and parse

    38  * functionality.  Calling this api repeatedly will have no effect - the

    39  * DatatypeConverter instance passed into the first invocation is the one that

    40  * will be used from then on.

    41  * </p>

    42  *

    43  * <p>

    44  * This interface defines the parse and print methods. There is one

    45  * parse and print method for each XML schema datatype specified in the

    46  * the default binding Table 5-1 in the JAXB specification.

    47  * </p>

    48  *

    49  * <p>

    50  * The parse and print methods defined here are invoked by the static parse

    51  * and print methods defined in the {@link DatatypeConverter DatatypeConverter}

    52  * class.

    53  * </p>

    54  *

    55  * <p>

    56  * A parse method for a XML schema datatype must be capable of converting any

    57  * lexical representation of the XML schema datatype ( specified by the

    58  * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes

    59  * specification</a> into a value in the value space of the XML schema datatype.

    60  * If an error is encountered during conversion, then an IllegalArgumentException

    61  * or a subclass of IllegalArgumentException must be thrown by the method.

    62  *

    63  * </p>

    64  *

    65  * <p>

    66  * A print method for a XML schema datatype can output any lexical

    67  * representation that is valid with respect to the XML schema datatype.

    68  * If an error is encountered during conversion, then an IllegalArgumentException,

    69  * or a subclass of IllegalArgumentException must be thrown by the method.

    70  * </p>

    71  *

    72  * The prefix xsd: is used to refer to XML schema datatypes

    73  * <a href="http://www.w3.org/TR/xmlschema-2/"> XML Schema Part2: Datatypes

    74  * specification.</a>

    75  *

    76  * <p>

    77  * @author <ul><li>Sekhar Vajjhala, Sun Microsystems, Inc.</li><li>Joe Fialli, Sun Microsystems Inc.</li><li>Kohsuke Kawaguchi, Sun Microsystems, Inc.</li><li>Ryan Shoemaker,Sun Microsystems Inc.</li></ul>

    78  * @see DatatypeConverter

    79  * @see ParseConversionEvent

    80  * @see PrintConversionEvent

    81  * @since JAXB1.0

    82  */

    84 public interface DatatypeConverterInterface {

    85     /**

    86      * <p>

    87      * Convert the string argument into a string.

    88      * @param lexicalXSDString

    89      *     A lexical representation of the XML Schema datatype xsd:string

    90      * @return

    91      *     A string that is the same as the input string.

    92      */

    93     public String parseString( String lexicalXSDString );

    95     /**

    96      * <p>

    97      * Convert the string argument into a BigInteger value.

    98      * @param lexicalXSDInteger

    99      *     A string containing a lexical representation of

   100      *     xsd:integer.

   101      * @return

   102      *     A BigInteger value represented by the string argument.

   103      * @throws NumberFormatException <code>lexicalXSDInteger</code> is not a valid string representation of a {@link java.math.BigInteger} value.

   104      */

   105     public java.math.BigInteger parseInteger( String lexicalXSDInteger );

   107     /**

   108      * <p>

   109      * Convert the string argument into an int value.

   110      * @param lexicalXSDInt

   111      *     A string containing a lexical representation of

   112      *     xsd:int.

   113      * @return

   114      *     An int value represented byte the string argument.

   115      * @throws NumberFormatException <code>lexicalXSDInt</code> is not a valid string representation of an <code>int</code> value.

   116      */

   117     public int parseInt( String lexicalXSDInt );

   119     /**

   120      * <p>

   121      * Converts the string argument into a long value.

   122      * @param lexicalXSDLong

   123      *     A string containing lexical representation of

   124      *     xsd:long.

   125      * @return

   126      *     A long value represented by the string argument.

   127      * @throws NumberFormatException <code>lexicalXSDLong</code> is not a valid string representation of a <code>long</code> value.

   128      */

   129     public long parseLong( String lexicalXSDLong );

   131     /**

   132      * <p>

   133      * Converts the string argument into a short value.

   134      * @param lexicalXSDShort

   135      *     A string containing lexical representation of

   136      *     xsd:short.

   137      * @return

   138      *     A short value represented by the string argument.

   139      * @throws NumberFormatException <code>lexicalXSDShort</code> is not a valid string representation of a <code>short</code> value.

   140      */

   141     public short parseShort( String lexicalXSDShort );

   143     /**

   144      * <p>

   145      * Converts the string argument into a BigDecimal value.

   146      * @param lexicalXSDDecimal

   147      *     A string containing lexical representation of

   148      *     xsd:decimal.

   149      * @return

   150      *     A BigDecimal value represented by the string argument.

   151      * @throws NumberFormatException <code>lexicalXSDDecimal</code> is not a valid string representation of {@link java.math.BigDecimal}.

   152      */

   153     public java.math.BigDecimal parseDecimal( String lexicalXSDDecimal );

   155     /**

   156      * <p>

   157      * Converts the string argument into a float value.

   158      * @param lexicalXSDFloat

   159      *     A string containing lexical representation of

   160      *     xsd:float.

   161      * @return

   162      *     A float value represented by the string argument.

   163      * @throws NumberFormatException <code>lexicalXSDFloat</code> is not a valid string representation of a <code>float</code> value.

   164      */

   165     public float parseFloat( String lexicalXSDFloat );

   167     /**

   168      * <p>

   169      * Converts the string argument into a double value.

   170      * @param lexicalXSDDouble

   171      *     A string containing lexical representation of

   172      *     xsd:double.

   173      * @return

   174      *     A double value represented by the string argument.

   175      * @throws NumberFormatException <code>lexicalXSDDouble</code> is not a valid string representation of a <code>double</code> value.

   176      */

   177     public double parseDouble( String lexicalXSDDouble );

   179     /**

   180      * <p>

   181      * Converts the string argument into a boolean value.

   182      * @param lexicalXSDBoolean

   183      *     A string containing lexical representation of

   184      *     xsd:boolean.

   185      * @return

   186      *     A boolean value represented by the string argument.

   187      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:boolean.

   188      */

   189     public boolean parseBoolean( String lexicalXSDBoolean );

   191     /**

   192      * <p>

   193      * Converts the string argument into a byte value.

   194      * @param lexicalXSDByte

   195      *     A string containing lexical representation of

   196      *     xsd:byte.

   197      * @return

   198      *     A byte value represented by the string argument.

   199      * @throws NumberFormatException <code>lexicalXSDByte</code> does not contain a parseable byte.

   200      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:byte.

   201      */

   202     public byte parseByte( String lexicalXSDByte );

   204     /**

   205      * <p>

   206      * Converts the string argument into a QName value.

   207      *

   208      * <p>

   209      * String parameter <tt>lexicalXSDQname</tt> must conform to lexical value space specifed at

   210      * <a href="http://www.w3.org/TR/xmlschema-2/#QName">XML Schema Part 2:Datatypes specification:QNames</a>

   211      *

   212      * @param lexicalXSDQName

   213      *     A string containing lexical representation of xsd:QName.

   214      * @param nsc

   215      *     A namespace context for interpreting a prefix within a QName.

   216      * @return

   217      *     A QName value represented by the string argument.

   218      * @throws IllegalArgumentException  if string parameter does not conform to XML Schema Part 2 specification or

   219      *      if namespace prefix of <tt>lexicalXSDQname</tt> is not bound to a URI in NamespaceContext <tt>nsc</tt>.

   220      */

   221     public javax.xml.namespace.QName parseQName( String lexicalXSDQName,

   222                                              javax.xml.namespace.NamespaceContext nsc);

   224     /**

   225      * <p>

   226      * Converts the string argument into a Calendar value.

   227      * @param lexicalXSDDateTime

   228      *     A string containing lexical representation of

   229      *     xsd:datetime.

   230      * @return

   231      *     A Calendar object represented by the string argument.

   232      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:dateTime.

   233      */

   234     public java.util.Calendar parseDateTime( String lexicalXSDDateTime );

   236     /**

   237      * <p>

   238      * Converts the string argument into an array of bytes.

   239      * @param lexicalXSDBase64Binary

   240      *     A string containing lexical representation

   241      *     of xsd:base64Binary.

   242      * @return

   243      *     An array of bytes represented by the string argument.

   244      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:base64Binary

   245      */

   246     public byte[] parseBase64Binary( String lexicalXSDBase64Binary );

   248     /**

   249      * <p>

   250      * Converts the string argument into an array of bytes.

   251      * @param lexicalXSDHexBinary

   252      *     A string containing lexical representation of

   253      *     xsd:hexBinary.

   254      * @return

   255      *     An array of bytes represented by the string argument.

   256      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:hexBinary.

   257      */

   258     public byte[] parseHexBinary( String lexicalXSDHexBinary );

   260     /**

   261      * <p>

   262      * Converts the string argument into a long value.

   263      * @param lexicalXSDUnsignedInt

   264      *     A string containing lexical representation

   265      *     of xsd:unsignedInt.

   266      * @return

   267      *     A long value represented by the string argument.

   268      * @throws NumberFormatException if string parameter can not be parsed into a <tt>long</tt> value.

   269      */

   270     public long parseUnsignedInt( String lexicalXSDUnsignedInt );

   272     /**

   273      * <p>

   274      * Converts the string argument into an int value.

   275      * @param lexicalXSDUnsignedShort

   276      *     A string containing lexical

   277      *     representation of xsd:unsignedShort.

   278      * @return

   279      *     An int value represented by the string argument.

   280      * @throws NumberFormatException if string parameter can not be parsed into an <tt>int</tt> value.

   281      */

   282     public int parseUnsignedShort( String lexicalXSDUnsignedShort );

   284     /**

   285      * <p>

   286      * Converts the string argument into a Calendar value.

   287      * @param lexicalXSDTime

   288      *     A string containing lexical representation of

   289      *     xsd:Time.

   290      * @return

   291      *     A Calendar value represented by the string argument.

   292      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Time.

   293      */

   294     public java.util.Calendar parseTime( String lexicalXSDTime );

   296     /**

   297      * <p>

   298      * Converts the string argument into a Calendar value.

   299      * @param lexicalXSDDate

   300      *     A string containing lexical representation of

   301      *     xsd:Date.

   302      * @return

   303      *     A Calendar value represented by the string argument.

   304      * @throws IllegalArgumentException if string parameter does not conform to lexical value space defined in XML Schema Part 2: Datatypes for xsd:Date.

   305      */

   306     public java.util.Calendar parseDate( String lexicalXSDDate );

   308     /**

   309      * <p>

   310      * Return a string containing the lexical representation of the

   311      * simple type.

   312      * @param lexicalXSDAnySimpleType

   313      *     A string containing lexical

   314      *     representation of the simple type.

   315      * @return

   316      *     A string containing the lexical representation of the

   317      *     simple type.

   318      */

   319     public String parseAnySimpleType( String lexicalXSDAnySimpleType );

   321     /**

   322      * <p>

   323      * Converts the string argument into a string.

   324      * @param val

   325      *     A string value.

   326      * @return

   327      *     A string containing a lexical representation of xsd:string

   328      */

   329     public String printString( String val );

   331     /**

   332      * <p>

   333      * Converts a BigInteger value into a string.

   334      * @param val

   335      *     A BigInteger value

   336      * @return

   337      *     A string containing a lexical representation of xsd:integer

   338      * @throws IllegalArgumentException <tt>val</tt> is null.

   339      */

   340     public String printInteger( java.math.BigInteger val );

   342     /**

   343      * <p>

   344      * Converts an int value into a string.

   345      * @param val

   346      *     An int value

   347      * @return

   348      *     A string containing a lexical representation of xsd:int

   349      */

   350     public String printInt( int val );

   353     /**

   354      * <p>

   355      * Converts a long value into a string.

   356      * @param val

   357      *     A long value

   358      * @return

   359      *     A string containing a lexical representation of xsd:long

   360      */

   361     public String printLong( long val );

   363     /**

   364      * <p>

   365      * Converts a short value into a string.

   366      * @param val

   367      *     A short value

   368      * @return

   369      *     A string containing a lexical representation of xsd:short

   370      */

   371     public String printShort( short val );

   373     /**

   374      * <p>

   375      * Converts a BigDecimal value into a string.

   376      * @param val

   377      *     A BigDecimal value

   378      * @return

   379      *     A string containing a lexical representation of xsd:decimal

   380      * @throws IllegalArgumentException <tt>val</tt> is null.

   381      */

   382     public String printDecimal( java.math.BigDecimal val );

   384     /**

   385      * <p>

   386      * Converts a float value into a string.

   387      * @param val

   388      *     A float value

   389      * @return

   390      *     A string containing a lexical representation of xsd:float

   391      */

   392     public String printFloat( float val );

   394     /**

   395      * <p>

   396      * Converts a double value into a string.

   397      * @param val

   398      *     A double value

   399      * @return

   400      *     A string containing a lexical representation of xsd:double

   401      */

   402     public String printDouble( double val );

   404     /**

   405      * <p>

   406      * Converts a boolean value into a string.

   407      * @param val

   408      *     A boolean value

   409      * @return

   410      *     A string containing a lexical representation of xsd:boolean

   411      */

   412     public String printBoolean( boolean val );

   414     /**

   415      * <p>

   416      * Converts a byte value into a string.

   417      * @param val

   418      *     A byte value

   419      * @return

   420      *     A string containing a lexical representation of xsd:byte

   421      */

   422     public String printByte( byte val );

   424     /**

   425      * <p>

   426      * Converts a QName instance into a string.

   427      * @param val

   428      *     A QName value

   429      * @param nsc

   430      *     A namespace context for interpreting a prefix within a QName.

   431      * @return

   432      *     A string containing a lexical representation of QName

   433      * @throws IllegalArgumentException if <tt>val</tt> is null or

   434      * if <tt>nsc</tt> is non-null or <tt>nsc.getPrefix(nsprefixFromVal)</tt> is null.

   435      */

   436     public String printQName( javax.xml.namespace.QName val,

   437                               javax.xml.namespace.NamespaceContext nsc );

   439     /**

   440      * <p>

   441      * Converts a Calendar value into a string.

   442      * @param val

   443      *     A Calendar value

   444      * @return

   445      *     A string containing a lexical representation of xsd:dateTime

   446      * @throws IllegalArgumentException if <tt>val</tt> is null.

   447      */

   448     public String printDateTime( java.util.Calendar val );

   450     /**

   451      * <p>

   452      * Converts an array of bytes into a string.

   453      * @param val

   454      *     an array of bytes

   455      * @return

   456      *     A string containing a lexical representation of xsd:base64Binary

   457      * @throws IllegalArgumentException if <tt>val</tt> is null.

   458      */

   459     public String printBase64Binary( byte[] val );

   461     /**

   462      * <p>

   463      * Converts an array of bytes into a string.

   464      * @param val

   465      *     an array of bytes

   466      * @return

   467      *     A string containing a lexical representation of xsd:hexBinary

   468      * @throws IllegalArgumentException if <tt>val</tt> is null.

   469      */

   470     public String printHexBinary( byte[] val );

   472     /**

   473      * <p>

   474      * Converts a long value into a string.

   475      * @param val

   476      *     A long value

   477      * @return

   478      *     A string containing a lexical representation of xsd:unsignedInt

   479      */

   480     public String printUnsignedInt( long val );

   482     /**

   483      * <p>

   484      * Converts an int value into a string.

   485      * @param val

   486      *     An int value

   487      * @return

   488      *     A string containing a lexical representation of xsd:unsignedShort

   489      */

   490     public String printUnsignedShort( int val );

   492     /**

   493      * <p>

   494      * Converts a Calendar value into a string.

   495      * @param val

   496      *     A Calendar value

   497      * @return

   498      *     A string containing a lexical representation of xsd:time

   499      * @throws IllegalArgumentException if <tt>val</tt> is null.

   500      */

   501     public String printTime( java.util.Calendar val );

   503     /**

   504      * <p>

   505      * Converts a Calendar value into a string.

   506      * @param val

   507      *     A Calendar value

   508      * @return

   509      *     A string containing a lexical representation of xsd:date

   510      * @throws IllegalArgumentException if <tt>val</tt> is null.

   511      */

   512     public String printDate( java.util.Calendar val );

   514     /**

   515      * <p>

   516      * Converts a string value into a string.

   517      * @param val

   518      *     A string value

   519      * @return

   520      *     A string containing a lexical representation of xsd:AnySimpleType

   521      */

   522     public String printAnySimpleType( String val );

   523 }

Mercurial > jdk8-mips64-public > jaxws / file revision

src/share/jaxws_classes/javax/xml/bind/DatatypeConverterInterface.java@9c07ef4934dd

src/share/jaxws_classes/javax/xml/bind/DatatypeConverterInterface.java