アノテーションインターフェース DateTimeFormat

@DocumentedSE @RetentionSE(RUNTIMESE) @TargetSE({METHODSE,FIELDSE,PARAMETERSE,ANNOTATION_TYPESE}) public @interface DateTimeFormat
フィールドまたはメソッドのパラメーターを日付または時刻としてフォーマットする必要があることを宣言します。

書式設定は、文字列から日付 / 時刻オブジェクトを解析する場合と、日付 / 時刻オブジェクトを文字列に出力する場合に適用されます。

スタイルパターン、ISO 日付 / 時刻パターン、またはカスタムフォーマットパターン文字列によるフォーマットをサポートします。DateSE、CalendarSE、LongSE (ミリ秒のタイムスタンプ) および JSR-310 java.time 値型に適用できます。

スタイルベースの書式設定の場合、style() 属性を目的のスタイルパターンコードに設定します。コードの最初の文字は日付スタイルで、2 番目の文字は時刻スタイルです。短いスタイルの場合は 'S'、中間の場合は 'M'、長い場合は 'L'、完全な場合は 'F' の文字を指定します。日付または時刻は、スタイル文字 '-' を指定することで省略できます。例: 'M-' は、時刻なしの日付の中間形式を指定します。サポートされているスタイルパターンコードは、FormatStyleSE で定義されている列挙定数に対応しています。

警告 : スタイルベースの書式設定と解析は、Java ランタイムに応じて変更される可能性のあるロケール依存のパターンに依存します。具体的には、日付 / 時刻の解析と書式設定に依存するアプリケーションは、JDK 20 以降で実行する場合、互換性のない動作の変更が発生する可能性があります。ISO 標準の形式または自分で制御する具体的なパターンを使用すると、システムやロケールに依存しない信頼性の高い日付 / 時刻値の解析と書式設定が可能になります。フォールバックパターンを使用すると、互換性の課題に対処することもできます。詳細については、Spring Framework wiki の JDK 20 以降での日付と時刻のフォーマットページを参照してください。

ISO ベースのフォーマットの場合、iso() 属性を DateTimeFormat.ISO.DATE などの目的の DateTimeFormat.ISO フォーマットに設定します。

カスタムフォーマットの場合は、pattern() 属性を "yyyy/MM/dd hh:mm:ss a" などの日時パターンに設定します。

各属性は相互に排他的であるため、アノテーションインスタンスごとに 1 つの属性のみを設定します（フォーマットのニーズに最も便利な属性）。

  • パターン属性を指定すると、スタイル属性と ISO 属性の両方よりも優先されます。
  • iso() 属性を指定すると、style 属性よりも優先されます。
  • アノテーション属性が指定されていない場合、適用されるデフォルトの形式は、スタイルコード "SS" （短い日付、短い時間）のスタイルベースです。

タイムゾーン

style() または pattern() 属性が使用される場合は常に、DateSE 値をフォーマットするときに JVM のデフォルトのタイムゾーンが使用されます。 DateSE 値をフォーマットするときに iso() 属性が使用される場合は常に、UTC がタイムゾーンとして使用されます。同じタイムゾーンがフォールバックパターンにも適用されます。タイムゾーンとして UTC を一貫して使用するために、-Duser.timezone=UTC を使用して JVM をブートストラップできます。

導入:
3.0
作成者:
Keith Donald, Juergen Hoeller, Sam Brannen
関連事項:

  • ネストされたクラスの要約

    ネストされたクラス
    修飾子と型
    クラス
    説明
    static enum
    DateTimeFormat.ISO
    一般的な ISO 日時形式パターン。

  • オプション要素の概要

    オプション要素
    修飾子と型
    オプションの要素
    説明
    StringSE[]
    fallbackPatterns
    プライマリ pattern()、iso()、style() 属性の解析が失敗した場合のフォールバックとして使用するカスタムパターンのセット。
    DateTimeFormat.ISO
    iso
    フィールドまたはメソッドパラメーターのフォーマットに使用する ISO パターン。
    StringSE
    pattern
    フィールドまたはメソッドのパラメーターをフォーマットするために使用するカスタムパターン。
    StringSE
    style
    フィールドまたはメソッドパラメーターのフォーマットに使用するスタイルパターン。

  • 要素の詳細

    • style

      StringSE style
      フィールドまたはメソッドパラメーターのフォーマットに使用するスタイルパターン。

      短い日付、短い時間の場合、デフォルトは "SS" です。デフォルトのスタイル以外の一般的なスタイルに従ってフィールドまたはメソッドのパラメーターをフォーマットする場合は、この属性を設定します。

      詳細については、クラスレベルのドキュメントを参照してください。

      関連事項:
      デフォルト:
      "SS"

    • iso

      DateTimeFormat.ISO iso
      フィールドまたはメソッドパラメーターのフォーマットに使用する ISO パターン。

      サポートされている ISO パターンは、DateTimeFormat.ISO 列挙型で定義されています。

      デフォルトは DateTimeFormat.ISO.NONE で、この属性を無視する必要があることを示します。ISO 形式に従ってフィールドまたはメソッドパラメーターをフォーマットする場合は、この属性を設定します。

      関連事項:
      デフォルト:
      NONE

    • pattern

      StringSE pattern
      フィールドまたはメソッドのパラメーターをフォーマットするために使用するカスタムパターン。

      デフォルトでは空の文字列になり、カスタムパターン文字列が指定されていないことを示します。スタイルまたは ISO 形式で表されないカスタムの日付時刻パターンに従ってフィールドまたはメソッドパラメーターをフォーマットする場合は、この属性を設定します。

      メモ: このパターンは、オーバーフローに対する厳密な解析セマンティクスを備えた元の SimpleDateFormatSE スタイルに従います (たとえば、うるう年以外の Feb 29 値を拒否します)。結果として、'yy' 文字は、DateTimeFormatterSE 仕様のような「紀元年」ではなく、従来のスタイルで年を示します (つまり、厳密な解決モードで DateTimeFormatter を通過すると、'yy' は 'uu' に変わります)。

      関連事項:
      デフォルト:
      ""

    • fallbackPatterns

      StringSE[] fallbackPatterns
      プライマリ pattern()、iso()、style() 属性の解析が失敗した場合のフォールバックとして使用するカスタムパターンのセット。

      例: 解析と出力に ISO 日付形式を使用したいが、さまざまな日付形式のユーザー入力の寛大な解析を許可する場合は、次のように構成できます。

       @DateTimeFormat(iso = ISO.DATE, fallbackPatterns = { "M/d/yy", "dd.MM.yyyy" })

      フォールバックパターンは、解析にのみ使用されます。値を文字列として出力するためには使用されません。プライマリ pattern()、iso()、style() 属性は、常に出力に使用されます。フォールバックパターンに使用されるタイムゾーンの詳細については、クラスレベルのドキュメントを参照してください。

      導入:
      5.3.5
      デフォルト:
      {}