問題タブ [api-design]

の上SortedMap.subMap

これは次のAPIですSortedMap<K,V>.subMap：

SortedMap<K,V> subMap(K fromKey, K toKey)fromKey：キーの範囲が包括的からtoKey排他的までのこのマップの部分のビューを返します。

この包括的下限、排他的上限コンボ（「ハーフオープン範囲」）は、Javaで普及しているものであり、利点はありますが、すぐにわかるように、癖もあります。

次のスニペットは、次の簡単な使用法を示していますsubMap。

最後の行は重要です：7=Sevenの排他的な上限の性質のため、除外されsubMapます。ここで、実際に包括的上限が必要であると仮定すると、次のようなユーティリティメソッドを記述してみることができます。

次に、上記のスニペットを続行すると、次のようになります。

いくつかの重要な観察を行う必要があります。

• 良いニュースは、値のタイプは気にしないということですが...
• subMapInclusiveInteger動作するためのキーを想定していますto + 1。
  • Longたとえばキーも使用する一般的なバージョンは使用できません（関連する質問を参照）
  • 言うまでもなく、代わりLongに比較する必要がありますLong.MAX_VALUE
  • キーとしての数値プリミティブボックスタイプなどのオーバーロードは、Byteすべて個別に記述する必要がありますCharacter
  • オーバーフローしてスローされるためtoInclusive == Integer.MAX_VALUE、特別なチェックを行う必要があります+1subMapIllegalArgumentException: fromKey > toKey
• これは、一般的に言って、過度に醜く、過度に具体的な解決策です
  • Stringキーはどうですか？または、そうでさえないかもしれないいくつかの未知のタイプComparable<?>？

したがって、問題は次のとおりです。、、、を取り、包括的範囲のクエリを実行する一般的なメソッドを作成することは可能ですかsubMapInclusive？SortedMap<K,V>K fromKey, K toKeysubMap

関連する質問

• インデックス付き範囲の上限は常に排他的であると見なされますか？
• Javaで数値ボックスタイプの汎用+1メソッドを作成することは可能ですか？

の上NavigableMap

境界が包括的であるか排他的であるかを示すためにNavigableMap.subMap2つの追加の変数をとるオーバーロードがあることに注意する必要があります。booleanこれがで利用可能になっていたらSortedMap、上記のどれも尋ねられなかったでしょう。

したがってNavigableMap<K,V>、包括的範囲クエリを使用するのが理想的でしたが、 （とりわけ）Collectionsユーティリティメソッドを提供しますが、と同じ贅沢を提供することはできません。SortedMapNavigableMap

関連する質問

• の同期スレッドセーフラッパーの作成NavigableMap

排他的な上限範囲クエリのみを提供するAPIの場合

• これは、排他的な上限範囲クエリの問題を浮き彫りにしますか？
• 排他的な上限が唯一の利用可能な機能である場合、過去に包括的範囲クエリはどのように実行されましたか？

次のスニペットに気づきました...

equals(Object x)...メソッドはのように定義されfinalているため、列挙型には使用できませんEnum。なんでそうなの？

equals(Object)列挙型のオーバーライドが必要なユースケースは考えられません。この振る舞いの背後にある理由を知りたいだけです。

私は、開発者が3D でシミュレートされたサッカー リーグ用の RoboCup エージェントを作成できるようにする .NET API を設計中です。

API が C# コードでどのように機能するかにはかなり満足していますが、このプロジェクトを使用して F# スキルを向上させたいと考えています (現在は練習ではなく読書に基づいています)。

そこで、C# と F# の両方のコードで使用される API を設計する際に、どのようなことを考慮する必要があるかをお聞きしたいと思います。

いくつかのポイント。

• 私は行列演算とベクトル演算をかなり多用しています。これらは現在不変のクラス/構造体です。
• API は現在、消費者の実装 (例: ) とのいくつかのインターフェースを定義し、IAgentそれらの実装のインスタンス (例: ) を使用してMyAgent他の API クラス (例: ) を構築しますnew Client(myAgent)。
• API がイベントを発生させます。
• API は、いくつかのデリゲート タイプを公開します。
• API にはいくつかの列挙型が含まれています。

API のバージョンをできるだけ早くリリースしたいと考えており、F# から操作するのが難しすぎることに気付いたとしても、後で大きな変更を加えたくありません。アドバイスをいただければ幸いです。

私はGoogleGuavaが大好きで、それをよく使用していますが、私がいつも書いている方法が1つあります。

私にとって、これはIterables（Iteratorsそのことに関しても）非常に便利な追加であるように思われるので、なぜそれが欠落しているのか疑問に思います。NoSuchElementExceptionまた、おそらくnullを見つけることと要素を見つけないことを区別するために、をスローするメソッドを持つことのポイントを理解できますが、その状況は、使用している述語が次の場合にのみ発生します。

これは一般的なケースではないようです。

では、なぜguavaの設計者は、それが見つからない場合にnullを返すのではなく、この動作を選択したのでしょうか。

これが[Iterables.find（）][1]のjavadocです。

[1]： http: //google-collections.googlecode.com/svn/trunk/javadoc/com/google/common/collect/Iterables.html#find (java.lang.Iterable、com.google.common.base。述語）

次のコードがスローされNullPointerExceptionます：

getInteger静的なので、コンパイラはnullを呼び出していますか？それは意味がありません！

何が起こっていますか？

プラットフォームに依存しないAPIドキュメントを開発するためにどのようなツールがありますか？

私は提案されたAPIを設計中であり、構造化された簡単に編集可能な方法でドキュメントを作成したいと考えています。私が見た答えの多くは基本的に「組み込みの言語固有のドキュメントツールを使用する」でしたが、APIを実装するのではなく、「トップレベル」から設計しているため、これはあまり役に立ちません。APIドキュメント用のCMSを探しています

PBWikiまたはConfluenceを使用するためのいくつかの提案を見てきましたが、バージョン管理の側面は優れていますが、プレーンなWikiが最良のオプションであるとは確信していません。

理論的には、API呼び出し用のCCKとAPIを読み取るためのビューを使用したDrupalビルドですが、これは私が探しているものにとっては少し手間がかかります。

APIドキュメント管理システムはありますか？APIのプラットフォームに依存しないドキュメントを作成および管理するための最良のオプションは何ですか？

これに関連する質問を見てきましたが、まだ満足のいく答えはありません。

ドキュメントによると、メソッドは次をString.valueOf(Object obj)返します。

引数が、の場合、;nullに等しい文字列。"null"それ以外の場合は、の値obj.toString()が返されます。

しかし、私がこれをやろうとするとどうしてですか？

代わりにNPEをスローしますか？（信じられない場合は、自分で試してみてください！）

どうしてこれが起こっているのですか？ドキュメントは私に嘘をついていますか？これはJavaの主要なバグですか？

(より大きなプロジェクトの一部として) 電子メール通知サービスを作成する必要があります。

HTMLテンプレートに基づくいくつかのタイプの通知メッセージを送信するために使用されます。

次の 2 つの方法で設計できます。

1. 最初の方法はビルダー パターンに基づいています。それは（私が思うに）普遍的であり、必要なすべてのケースを処理できます。しかし、それを使用する人にとってはあまり便利ではありません。典型的な使用法は次のようになります。

   /li>

2. 2 番目の方法は、すべてのケースを明示的に実装することです。これは、使用コード (以下に示す) は可能な限り単純にすることを意味しますが、新しいケースを処理する必要があるたびに API を変更 (新しいメソッドを追加) する必要があります。

   /li>

どちらの方がよいですか？なんで？（問題があれば言語はJavaです）

ありがとう！

私は有用な回答の多くを統合し、以下の独自の回答を考え出しました

たとえば、Foo明示的な初期化と終了が必要な API を作成しています。(言語に依存しないはずですが、ここでは C++ を使用しています)

どうやら、私たちのライブラリはマルチスレッドや再入可能性などを考慮していないようです。関数を 1 回だけ呼び出す必要があるとしましょうInit。他の入力で再度呼び出すと、大混乱が生じます。

これを発信者に伝える最善の方法は何ですか? 次の 2 つの方法が考えられます。

1. 内部InitLibraryではassert、呼び出し元を 2 回初期化したと非難するいくつかの静的変数があります。
2. 内部InitLibraryで、いくつかの静的変数をチェックし、ライブラリがすでに初期化されている場合は黙って中止します。

方法 1 は明らかに明示的ですが、方法 2 の方がユーザーフレンドリーです。メソッド＃2には、呼び出し元がInitLibrary2回呼び出されるべきではないという事実に気付かないという欠点があると考えています。

各アプローチの長所/短所は何ですか? これらすべてを覆すより賢い方法はありますか?

編集

ここでの例は非常に不自然であることを知っています。@daemonが指摘したように、私は自分自身を初期化する必要があり、呼び出し元に迷惑をかけません。ただし、実際には、自分自身を適切に初期化するためにさらに情報が必要な場所があります ( my variable name の使用に注意してくださいsomeMagicInputRequiredAtRuntime)。これは初期化/終了に限定されませんが、引用と引用の「耐障害性」を選択するか、ひどく失敗するかのジレンマが存在する他の例です。

先日、アプリケーションに重要なサービスを実装していましたが、それは何があっても実行し続けるはずです。そこで、次の構成を使用しました。

...importantPeriodicTaskがRuntimeExceptionまたはErrorを実際にスローすると、ScheduledExecutorServiceはこのタスクの実行を停止します（スケジュールされなくなります）。

もちろん、これはまさにjavadocが言っていることです。

タスクの実行で例外が発生した場合、それ以降の実行は抑制されます。

恥ずかしいのですが、なぜ作者ScheduledExecutorServiceがこのように実装したのか理解できませんでした。

確かに、RuntimeExceptionまたはError、特にErrorは通常はキャッチされません。しかし実際には、特にRuntimeExceptionの場合、実際のデプロイメントでは非常に一般的にスローされます。その特定の操作は失敗するはずですが、その孤立したエラーのためにアプリ自体が失敗しないことがほとんどの場合望ましいと思います。

ある周期的なタスクの抑制が他の種類の周期的なタスクに影響を与えないのは事実です。しかし、ほとんどの定期的なタスクの性質を考えると、これらのタスクは、孤立したタスクではなく、「サービス」として認識されるべきではありませんか？

つまり、その1つのインスタンスだけがimportantPeriodicTask失敗し、タスク自体のスケジュールが変更され続けるべきではないでしょうか。