オプション - スコープ対象、グローバル

Optional API は、GlideQuery、Stream、または GlideRecord API によって返される単一のレコードとやり取りします。当該の API が存在しない場合も同様です。null または未定義のクエリー結果を処理することでエラーになりにくいスクリプトを作成します。

Optional オブジェクトは以下の方法で取得できます。

• 以下に挙げる GlideQuery クラス内のメソッドから Optional オブジェクトを返します。詳細については、「GlideQuery」を参照してください。
  • getBy()
  • get()
  • insert()
  • insertOrUpdate()
  • update()
  • selectOne()
  • avg()
  • max()
  • min()
  • sum()
• Stream クラス内の find() メソッドから Optional オブジェクトを返します。Stream の詳細については、「Stream API」を参照してください。
• 必要に応じて、lasy() メソッドを使用して Optional の値を生成します。

これらのメソッドは静的であり、クラスのインスタンスを必要としません。

• lazy()
• of()
• empty()

これらの静的メソッドは、GlideRecord などの単一の値を返す API で使用できます。

スコープ対象またはグローバルのサーバー側スクリプトで、Optional API を使用します。この API には GlideQuery [com.sn_glidequery] プラグインが必要です。

実装

この API は、メソッド呼び出しが連鎖していて、各メソッドが前のメソッドで返された結果に基づいて構築されるビルダーパターン。メソッドを使用してクエリの属性を定義します。メソッドは、ターミナルメソッド (クエリ結果を返すメソッド) を呼び出すまで実行されないため、クエリを実行する前にクエリの要件を定義できます。 内の GlideQuery および Stream API と連動します。

クエリが単一のレコードを返す場合、システムは Optional オブジェクトに結果をラップします。クエリがレコードのストリームを返す場合、システムは Stream オブジェクトに結果をラップします。これらのオブジェクトを使用すると、各 API で一連のメソッドを使用して結果を管理できます。

たとえば、この スクリプトはタスクテーブルでクエリを実行し、レコードを優先度別にグループ化して、合計再アサイン回数が 4 を超える各優先度を返します。

var query = new global.GlideQuery('task')
    .where('active', true) //Returns new GlideQuery object with a "where" clause.
    .groupBy('priority') //Returns new GlideQuery object with a "group by" clause.
    .aggregate('sum', 'reassignment_count') //Returns new GlideQuery object with a "sum(reassignment_count)" clause.
    .having('sum', 'reassignment_count', '>', 4) //Returns new GlideQuery object with a "having reassignment_count > 4" clause.
    .select() //Returns a stream of records wrapped in a Stream object.  
    .forEach(function (priority){ //Terminal method in the Stream class that executes the query and returns the result. 
      gs.info("Priority " + priority.group.priority + ": " + priority.sum.reassignment_count + " reassignments");
    });

出力:

Priority 1: 11 reassignments
Priority 3: 6 reassignments
Priority 5: 5 reassignments

ターミナルメソッド

パフォーマンス上の理由から、クエリーはターミナルメソッドを呼び出すときにのみデータをフェッチします。Optional クラスのターミナルメソッドは次のとおりです。

• get()
• orElse()
• ifPresent()
• isEmpty()
• isPresent()

Optional - empty(文字列 reason)

空の Optional オブジェクトを返します。このメソッドを Else 節で使用して、結果を返さない可能性があるクエリーを処理します。

注:

このメソッドは静的です。このメソッドを使用するためにクラスのインスタンスは必要ありません。

表 : 1. パラメーター

名前	タイプ	説明
reason	文字列	オプション。空の Optional オブジェクトで Optional.get() が呼び出されたときにログに表示される理由。

表 : 2. 返される内容

タイプ	説明
オプション	単一のレコードを操作するために使用されるオブジェクト。

この例では、クエリーが結果を返さない場合に空の Optional オブジェクトを生成する方法を示します。

var now_GR = new GlideRecord('task');
now_GR.addQuery('approval', 'not requested'); 
now_GR.query();
var optional;
if (now_GR.next()) {
optional = Optional.of(now_GR.getUniqueValue());
} else {
    optional = Optional.empty("no results");
}

gs.info(optional.get());

出力：

NiceError: [2020-08-26T23:23:37.402Z]: get() called on empty Optional: no results

Optional - filter(関数 predicate)

述語関数 (単一の値を受け取って true または false を返す関数) を、Optional オブジェクト内のレコードに適用します。関数が true を返す場合、このメソッドは Optional レコードをそのまま返します。関数が false を返す場合は、空の Optional オブジェクトを返します。

表 : 3. パラメーター

名前	タイプ	説明
predicate	関数	Optional オブジェクト内の値に適用する述語関数。ブーリアン値を返す必要があります。

表 : 4. 返される内容

タイプ	説明
オプション	単一のレコードを操作するために使用されるオブジェクト。

この例では、Optional の結果にフィルター関数を適用する方法を示します。

var filteredQuery = new global.GlideQuery('sys_user')
    .getBy({ sys_id: 'f682abf03710200044e0bfc8bcbe5d38' }, ['phone'])
    .filter(function (user) {
        return phoneRegex.test(user.phone);
    });

Optional - flatMap(関数 fn)

Optional オブジェクトを返す関数をクエリーの結果に適用します。このメソッドを使用して、1 つ目のクエリーの結果を用いて 2 つ目のクエリーを実行します。

表 : 5. パラメーター

名前	タイプ	説明
fn	関数	Optional オブジェクトを返したクエリーの結果に適用する関数。

表 : 6. 返される内容

タイプ	説明
オプション	単一のレコードを操作するために使用されるオブジェクト。

この例は、前のクエリーの結果に基づいてユーザーテーブルのクエリーを実行する方法を示しています。

new global.GlideQuery('alm_asset')
    .whereNotNull('owned_by')
    .selectOne('owned_by')
    .flatMap(function (asset) {
        return new global.GlideQuery('sys_user')
            .getBy({ sys_id: asset.owned_by }, ['first_name', 'last_name', 'company.name'])
    })
    .ifPresent(GQ.jsonDebug);

出力：

{
  "sys_id": "46d59205a9fe198101d603f5de37bfa3",
  "first_name": "John",
  "last_name": "Bohnhamn",
  "company": {
    "name": "ACME North America"
  }
}

Optional - get()

Optional オブジェクト内のレコードを返します。クエリがレコードを返さない場合はエラーをスローします。

表 : 7. パラメーター

名前	タイプ	説明
なし

表 : 8. 返される内容

タイプ	説明
任意	Optional オブジェクト内のレコード。値が null または未定義の場合は、エラーがスローされます。

この例は、単一のレコードの値を取得する方法を示しています。

var value = new global.GlideQuery('sys_user')
    .selectOne('first_name') //Returns the result of the query inside an Optional object
    .get(); //Calls Optional.get() on the Optional object

gs.info(JSON.stringify(value));

出力：

{
   "first_name":"fred",
   "sys_id":"005d500b536073005e0addeeff7b12f4"
}

Optional - ifPresent(関数 fn)

Optional オブジェクト内のレコードに関数を適用します。Optional オブジェクトにレコードが含まれていない場合、関数は実行されません。

表 : 9. パラメーター

名前	タイプ	説明
fn	関数	Optional オブジェクト内のレコードに適用する関数。

表 : 10. 返される内容

タイプ	説明
なし

この例は、値が存在する場合にその値を出力する方法を示しています。

var user = new global.GlideQuery('sys_user')
    .where('sys_id', 'f682abf03710200044e0bfc8bcbe5d38')
    .selectOne('zip')
    .ifPresent(function (user) {
      gs.info('Zip Code: ' + user.zip);
    });

Optional - isEmpty()

Optional オブジェクトが空の場合に true を返します。

表 : 11. パラメーター

名前	タイプ	説明
なし

表 : 12. 返される内容

タイプ	説明
ブーリアン	クエリーの結果に値が含まれているかどうかを示すフラグ。 有効な値： true：クエリーが null または未定義を返します。 false：クエリーが値を返します。

この例では、クエリーの結果が空かどうかを確認する方法を示します。

var checkEmpty = new global.GlideQuery('sys_user')
    .where('last_name', 'Barker')
    .selectOne()
    .isEmpty();

gs.info(checkEmpty);

出力：

true

Optional - isPresent()

Optional オブジェクトに値が含まれているかどうかを確認します。

表 : 13. パラメーター

名前	タイプ	説明
なし

表 : 14. 返される内容

タイプ	説明
ブーリアン	クエリーの結果に値が含まれているかどうかを示すフラグ。 有効な値： true：クエリーが値を返します。 false：クエリーが null または未定義を返します。

この例では、クエリーで結果が返されるかどうかを確認する方法を示します。

var checkPresent = new global.GlideQuery('sys_user')    
   .where('last_name', 'Luddy')
   .selectOne('first_name')
   .isPresent();

gs.info(checkPresent);

出力：

true

Optional - lazy(関数 lazyGetFn)

新しい Optional オブジェクトを返します。オブジェクトには、レコードが入っているのではなく、コードで要求された場合にのみ呼び出されるレコードを取得する関数が入っています。

このメソッドを使用して、値が必要になるまでその値の取得を遅らせます。これは、遅いソースから値を要求する際に、不必要にコードの速度を低下させたくない場合に行います。そうでない場合は、GlideQuery および Stream の API を使用すれば Optional オブジェクトを返すことができます。

注:

このメソッドは静的です。このメソッドを使用するためにクラスのインスタンスは必要ありません。

表 : 15. パラメーター

名前	タイプ	説明
lazyGetFn	関数	クエリーの結果として単一のレコードを返す関数。例： var userGr = new GlideRecord('sys_user');

表 : 16. 返される内容

タイプ	説明
オプション	Optional<result> という形式のクエリーの結果を含むオブジェクト。

この例では、GlideRecord クエリーに基づいて Optional オブジェクトを取得する方法を示します。

var userOptional = global.Optional.lazy(function () {
    var userGr = new GlideRecord('sys_user');
    userGr.setLimit(1);
    userGr.query();
    return userGr.next() ? userGr.getUniqueValue() : null;
});

gs.info(userOptional);

出力：

Optional<005d500b536073005e0addeeff7b12f4>

Optional - map(関数 fn)

関数をクエリーの結果に適用します。

表 : 17. パラメーター

名前	タイプ	説明
fn	関数	クエリーの結果に適用する関数。

表 : 18. 返される内容

タイプ	説明
オプション	関数によって更新されたクエリーの結果を Optional<result> という形式で含むオブジェクト。

この例は、値を大文字に変換する関数をクエリーの結果に適用する方法を示しています。

var value = new global.GlideQuery('sys_user')
    .whereNotNull('first_name')
    .selectOne('first_name')
    .map(function (user) {
	       return user.first_name.toUpperCase();
    });

gs.info(value);

出力：

Optional<ABEL>

Optional - of(任意 value)

指定された値を Optional オブジェクト内にラップします。たとえば、GlideRecord クエリーの結果を Optional オブジェクトでラップすることで、関連するメソッドを使用できます。

注:

このメソッドは静的です。このメソッドを使用するためにクラスのインスタンスは必要ありません。

表 : 19. パラメーター

名前	タイプ	説明
value	任意	Optional オブジェクト内の値。

表 : 20. 返される内容

タイプ	説明
オプション	Optional<value> の形式で渡された値を含むオブジェクト。

この例では、GlideRecord クエリーに基づいて Optional オブジェクトを生成する方法を示します。

var now_GR = new GlideRecord('task');
now_GR.addQuery('approval', 'not requested'); 
now_GR.query();
var optional;
if (now_GR.next()) {
optional = Optional.of(now_GR.getUniqueValue());
} else {
    optional = Optional.empty("no results");
}

gs.info(optional.get());

出力：

00c269162d761010f87708b56757cbb3

Optional - orElse(任意 defaultValue)

クエリーが結果を返さない場合に、Optional オブジェクト内にデフォルト値を追加します。

表 : 21. パラメーター

名前	タイプ	説明
defaultValue	任意	クエリーが結果を返さない場合に Optional オブジェクト内に追加する値。

表 : 22. 返される内容

タイプ	説明
任意	クエリーが結果を返さない場合に Optional オブジェクト内に追加する値。

この例は、クエリーが正しくない場合でも値を返す方法を示しています。

var user = new global.GlideQuery('sys_user')
    .get('1234', ['first_name', 'last_name'])
    .orElse({ first_name: 'Default', last_name: 'User' });

gs.info(JSON.stringify(user))

出力：

{
   "first_name":"Default",
   "last_name":"User"
}