Stream Gatherers عمليًا، الجزء 2
تتواصل رحلتنا مع Stream Gatherers التي أُضيفت في Java 22 عبر JEP 461 – وهذه المرة ننتقل إلى الـ gatherers المضمّنة وننظر في ما تستطيع فعله.
في هذا المقال نستكشف Stream Gatherers التي وصلت في Java 22 عبر JEP 461. ونركّز على الـ gatherers المضمّنة وننظر في ما تستطيع فعله. كما سنتعمق في بناء عمليات أكثر تعقيدًا بتركيب هذه الـ gatherers المضمّنة، لنبيّن الوظائف الإضافية والمرونة التي تضيفها إلى Stream API في Java. والهدف من هذا الاستكشاف أن نُظهر أين تفيد هذه الأدوات القوية في معالجة التدفقات وما الذي تقدّمه.
نظرة على الـ Gatherers المضمّنة
في هذا القسم نستعرض الـ gatherers المضمّنة مثل fold وmapConcurrent وscan وwindowFixed وwindowSliding، مع وصف موجز لكل منها ثم عرضه أثناء العمل.
Fold
يدمج هذا الـ Gatherer العناصر في نتيجة واحدة أثناء معالجة التدفق، على نحو مشابه لـ Stream::reduce. والفرق أن reduce يغلّف نتيجته في Optional، بينما يعيد Fold تدفقًا يحتوي مباشرةً على القيمة النهائية المجمَّعة.
لنأخذ مثالًا بسيطًا يحسب المضروب (factorial):
System.out.println("Fold example:");
Stream.of(1, 2, 3, 4, 5)
.gather(Gatherers.fold(() -> 1, (a, b) -> a * b))
.forEach(System.out::println);
كما هو موضح، تقبل دالة المصنع الخاصة بـ fold وسيطين:
- initial: كائن Supplier يوفّر القيمة الابتدائية لعملية الطي
- folder: كائن BiFunction يُستخدم لدمج العناصر واحدًا تلو الآخر
المخرجات:
Fold example:
120
Map Concurrent
تتيح عملية “Map Concurrent” تشغيل الدوال بالتزامن على عناصر التدفق، بحد أقصى لمستوى التزامن وبالاعتماد على الخيوط الافتراضية (virtual threads)، مع الحفاظ على ترتيب التدفق.
وهكذا نستخدمها لمضاعفة كل عنصر:
System.out.println("Map concurrent example:");
Stream.of(1, 2, 3, 4, 5)
.gather(Gatherers.mapConcurrent(4, a -> a *2))
.forEach(System.out::println);
تقبل الدالة معاملين:
- maxConcurrency: يحدد مستوى التزامن المطلوب.
- mapper: الدالة Function التي تُطبَّق على كل عنصر
وتُظهر المخرجات معالجة متوازية فعّالة: يُضاعَف كل رقم ويُحتفظ بالترتيب الأصلي:
Map concurrent example:
2
4
6
8
10
Scan
ينفّذ هذا الـ Gatherer مسحًا بالبادئة (Prefix Scan)، فيبني النتائج خطوة بخطوة باستخدام الدوال المعطاة. ويبدأ بقيمة ابتدائية يحصل عليها من Supplier، ولكل عنصر في التدفق تُطبَّق BiFunction على العنصر الحالي والعنصر التالي. ثم تُرسَل كل نتيجة متراكمة إلى المراحل اللاحقة، مما يتيح إنتاج تسلسل من القيم المتراكمة تدريجيًا بصورة ديناميكية.
لنستخدم الدالة scan لحساب المضروب مرة أخرى:
System.out.println("Scan example:");
Stream.of(1, 2, 3, 4, 5)
.gather(Gatherers.scan(()->1, (a,b) -> a*b))
.forEach(System.out::println);
وعلى النقيض من الدالة fold، تجعل scan التدفق يُظهر كل خطوة وسيطة من الحساب، لا النتيجة النهائية فقط:
Scan example:
1
2
6
24
120
Window Fixed
يرتّب عناصر التدفق في مجموعات متتالية ومرتبة بحجم ثابت. والتدفق الفارغ لا ينتج أي نوافذ. وقد تحتوي النافذة الأخيرة على عدد أقل من العناصر عندما لا يقبل إجمالي عدد العناصر في التدفق القسمة على حجم النافذة قسمةً تامة.
وهذا مثال يقسّم عناصر التدفق إلى نوافذ من عنصرين لكل منها:
System.out.println("Window fixed example:");
Stream.of(1, 2, 3, 4, 5)
.gather(Gatherers.windowFixed(2))
.forEach(System.out::println);
نحصل على المخرجات التالية:
Window fixed example:
[1, 2]
[3, 4]
[5]
ما نلاحظه أن المجموعة الأخيرة تحتوي على عنصر واحد فقط، لأن عدد عناصر التدفق فردي، ولا يمكن تقسيمه بالتساوي بحجم نافذة يساوي اثنين.
Window Sliding
يقسّم الـ Gatherer المسمّى “Window Sliding” العناصر إلى نوافذ متداخلة ديناميكيًا بحجم معين. وتتحرك كل نافذة جديدة عنصرًا واحدًا إلى الأمام بالنسبة إلى سابقتها، مما يُبقي البيانات متدفقة باستمرار. وما يميّز هذه العملية أنها تنتج عدة نوافذ متداخلة، بحيث تظهر بعض العناصر في نوافذ متتالية، فتعطي صورة كاملة عن تسلسل التدفق.
لنشغّل عملية windowSliding على التدفق نفسه الذي استخدمناه سابقًا:
System.out.println("Window sliding example:");
Stream.of(1, 2, 3, 4, 5)
.gather(Gatherers.windowSliding(2))
.forEach(System.out::println);
تبدو المخرجات الآن هكذا:
Window sliding example:
[1, 2]
[2, 3]
[3, 4]
[4, 5]
نرى هذه المرة نوافذ أكثر، تحتوي كل منها على عنصرين. ولاحظ أن بعض العناصر تظهر في نافذتين متتاليتين.
الـ Gatherers المضمّنة أثناء العمل
بعد أن فهمنا كيف تعمل الـ gatherers المضمّنة، لنستخدمها في حل مشكلات أكثر عملية: ضمان ترتيب آمن للحيوانات، ومحاكاة ألعاب بين اللاعبين، وتتبّع سجل رصيد حساب مصرفي.
الترتيب الآمن للحيوانات
لمعالجة مشكلة الترتيب الآمن للحيوانات، ننظر في تسلسل مكوّن من ثلاثة أنواع من الحيوانات:
- ذئب،
- خروف،
- كلب راعٍ.
القاعدة الأساسية أنه لا يجوز أن تضم أي ثلاثة حيوانات متتالية ذئبًا وخروفًا ما لم يوجد كلب راعٍ لحمايته، وإلا تعرّض الخروف للخطر. ونريد تنفيذ منطق تحقق يفحص ما إذا كان تدفق الحيوانات يستوفي هذه القاعدة. وكخطوة أولى، نمذج أنواع الحيوانات بـ enum، لنضع الأساس للمنطق.
public enum Animal {
SHEEP, SHEEP_DOG, WOLF
}
بعد ذلك سنبني Gatherer يغلّف منطق التحقق هذا:
public class AnimalStreamUtils {
public static Gatherer<Animal, ?, Boolean> isValidSequence() {
Predicate<List<Animal>> validTriplePredicate = triple -> !(
triple.contains(SHEEP) && triple.contains(WOLF) && !triple.contains(SHEEP_DOG)
);
var tripleWindowGatherer = Gatherers.<Animal>windowSliding(3);
var areAllTriplesValidGatherer = Gatherers.<List<Animal>, Boolean>fold(
() -> true,
(result, triple) -> result && validTriplePredicate.test(triple)
);
return tripleWindowGatherer.andThen(areAllTriplesValidGatherer);
}
}
النقاط الأساسية:
- AnimalStreamUtils: فئة مساعدة تعرض دالة مصنع تجعل ربط الـ Gatherer أبسط وأكثر ملاءمة.
- validTriplePredicate: يفحص كل ثلاثية للتأكد من أنها آمنة، مستبعدًا الحالات التي قد يهدد فيها ذئب خروفًا.
- tripleWindowGatherer: ينتج ثلاثيات متتالية من الحيوانات لتحليلها، بحيث يُقيَّم التسلسل بأكمله.
- areAllTriplesValidGatherer: يتأكد من أن كل ثلاثية من الحيوانات آمنة وفق المعايير المحددة.
- Gatherer:andThen: تدمج هذه الدالة الـ gatherers في واحد: \
stream.gather(a.andThen(b)) تعادل stream.gather(a).gather(b).
وبعد أن جهّزنا الـ Gatherer، لننتقل إلى اختبار طريقة عمله.
var validSequence = List.of(SHEEP, SHEEP_DOG, WOLF, WOLF);
System.out.println("Valid animal sequence result:");
validSequence.stream()
.gather(AnimalStreamUtils.isValidSequence())
.forEach(System.out::println);
var invalidSequence = List.of(SHEEP_DOG, SHEEP, WOLF, WOLF);
System.out.println("\nInvalid animal sequence result:");
invalidSequence.stream()
.gather(AnimalStreamUtils.isValidSequence())
.forEach(System.out::println);
يعطينا تشغيله المخرجات المتوقعة:
Valid animal sequence result:
true
Invalid animal sequence result:
false
محاكاة الألعاب
ننتقل إلى المشكلة التالية: نريد إقران اللاعبين ومحاكاة ألعاب بينهم. وتنتهي كل لعبة بفوز أحد اللاعبين أو بالتعادل.
نبدأ بنموذج Player بسيط لا يحمل سوى اسم، يُستخدم لتعريف كل لاعب في الألعاب المحاكاة:
public record Player(String name) {
}
ثم نضيف واجهة Game بتنفيذين منفصلين: CompletedGame التي تمثّل لعبة انتهت بنجاح، وInvalidGame التي تُستخدم عندما لا يكون عدد اللاعبين كافيًا.
public interface Game {
Game INVALID_GAME = new InvalidGame();
static Game completedGame(Player player1, Player player2, GameResult result) {
return new CompletedGame(player1, player2, result);
}
}
record CompletedGame(Player player1, Player player2, GameResult result) implements Game {
}
class InvalidGame implements Game {
@Override
public String toString() {
return "INVALID GAME";
}
}
GameResult هو enum يصف النتائج الممكنة: فوز أحد اللاعبين أو التعادل. كما يوفّر دالة تنتج نتيجة عشوائية لكل لعبة.
public enum GameResult {
PLAYER1_WON, PLAYER2_WON, DRAW;
private static final Random RANDOM = new Random();
public static GameResult randomResult() {
return switch (RANDOM.nextInt(3)) {
case 0 -> PLAYER1_WON;
case 1 -> PLAYER2_WON;
default -> DRAW;
};
}
}
بعد ذلك نبني Gatherer يقرن اللاعبين ويدير ألعابهم، متكفلًا بعملية المطابقة كلها.
public class GameGatherers {
public static Gatherer<Player, ?, Game> performGamesGatherer() {
Gatherer<Player,?, List<Player>> pairPlayersGatherer = Gatherers.windowFixed(2);
Gatherer<List<Player>,?, Game> simulateGamesGatherer = Gatherers.mapConcurrent(4, players -> {
if(players.size() != 2) {
return Game.INVALID_GAME;
}
return Game.completedGame(players.get(0), players.get(1), GameResult.randomResult());
});
return pairPlayersGatherer.andThen(simulateGamesGatherer);
}
}
النقاط الأساسية:
- pairPlayersGatherer: يضع اللاعبين في أزواج بحيث يشارك كل منهم في لعبة واحدة فقط، معتمدًا على windowFixed لتولّي المواجهات.
- simulateGamesGatherer: يحاكي الألعاب بين اللاعبين المقترنين. وعندما لا يكفي عدد اللاعبين لتكوين زوج، يعيد INVALID_GAME. وإلا فإنه ينشئ لعبة بنتيجة عشوائية.
- andThen: وأخيرًا ندمج الـ gatherer‑ين للحصول على النتيجة المقصودة.
والآن لنرَ الـ Gatherer أثناء العمل:
var listOfPlayers = List.of(
new Player("John"),
new Player("Marry"),
new Player("George"),
new Player("Ann"),
new Player("Pete"),
new Player("Stuart"),
new Player("Adam")
);
System.out.println("\nGames result:");
listOfPlayers.stream()
.gather(GameGatherers.performGamesGatherer())
.forEach(System.out::println);
ينتج هذا المخرجات التالية:
Games result:
CompletedGame[player1=Player[name=John], player2=Player[name=Marry], result=PLAYER2_WON]
CompletedGame[player1=Player[name=George], player2=Player[name=Ann], result=DRAW]
CompletedGame[player1=Player[name=Pete], player2=Player[name=Stuart], result=DRAW]
INVALID GAME
تُعلَّم اللعبة الأخيرة بأنها غير صالحة لأن عدد اللاعبين فردي، وهذا يبيّن كيف يتعامل إعدادنا مع الحالات التي لا يمكن فيها إقران الجميع.
سجل رصيد الحساب المصرفي
في المهمة الأخيرة نعود إلى السجل Money الذي قدّمناه أول مرة في مقالنا الافتتاحي عن Stream Gatherers.
public record Money(BigDecimal amount, Currency currency) {
public Money add(Money money) {
return new Money(money.amount.add(this.amount), currency);
}
public Money multiply(BigDecimal multiplier) {
return new Money(amount.multiply(multiplier), currency);
}
}
بالتعامل مع Money على أنه تمثيل لرصيد الحساب المصرفي وللمعاملات معًا، نريد تتبّع كيف يتغير الرصيد عبر سلسلة من المعاملات. والحل هو كتابة Gatherer، كما هو موضح أدناه، يطبّق بكفاءة أثر كل معاملة على الرصيد الابتدائي.
public class MoneyUtils {
public static Gatherer<Money, ?, Money> computeBalanceHistory(Money balance){
return Gatherers.scan(() -> balance, Money::add);
}
}
العناصر الأساسية هي:
- الرصيد الابتدائي، الممرَّر إلى الدالة computeBalanceHistory، هو نقطة بدء الحساب.
- تحدّث الدالة Gatherers::scan الرصيد مع كل معاملة في التدفق، بما يعكس التغيرات المالية.
لنجرّب الـ Gatherer الآن:
var transactions = List.of(
new Money(BigDecimal.valueOf(-10), PLN),
new Money(BigDecimal.valueOf(20), PLN),
new Money(BigDecimal.valueOf(50), PLN)
);
var balance = new Money(BigDecimal.valueOf(270), PLN);
System.out.println("\n Balance history:");
transactions.stream()
.gather(MoneyUtils.computeBalanceHistory(balance))
.forEach(System.out::println);
وهذه هي النتائج:
Balance history:
Money[amount=260, currency=PLN]
Money[amount=280, currency=PLN]
Money[amount=330, currency=PLN]
مهما بدا هذا الحل قصيرًا، فقد يكون مفيدًا في كثير من حالات الاستخدام.
الخلاصة
في هذا المقال المتابِع عن Stream Gatherers، نظرنا عن كثب في الوظائف المضمّنة مثل fold وmapConcurrent وscan وwindowFixed وwindowSliding. بدأنا بنظرة عامة ثم استخدمنا هذه الـ gatherers لحل مشكلات أكثر عملية، لنبيّن مدى قابليتها للاستخدام. وغالبًا ما كان الحصول على النتائج المرجوة يتطلب الجمع المقصود بين عدة gatherers بالدالة andThen، مما يبرز مدى مرونة هذه الأدوات القوية لمعالجة التدفقات وفائدتها.
من الواضح أن الـ Gatherers مخصصة لبناء حلول مفصّلة حسب الحاجة، لكن ميزاتها المضمّنة تفتح أيضًا إمكانات قيّمة لعمليات التدفقات، مما يجعل التعامل معها أبسط وأفضل.
يسعدنا أن نسمع رأيك في هذه الـ gatherers المضمّنة. هل هي مفيدة لك؟ وهل هناك وظيفة تعتقد أنها ناقصة؟