idlj(1) Java IDL and RMI-IIOP Tools idlj(1) نام (NAME) idlj - اتصالات جاوا را برای یک فایل مشخص از زبان تعریف واسط (IDL) تولید می‌کند. خلاصه دستور (SYNOPSIS) idlj [ options ] idlfile options گزینه‌های خط فرمان. بخش گزینه‌ها را ببینید. گزینه‌ها می‌توانند به هر ترتیبی ظاهر شوند، اما باید قبل از idlfile قرار گیرند. idlfile نام فایلی که حاوی تعاریف زبان تعریف واسط (IDL) است. توضیحات (DESCRIPTION) کامپایلر IDL-to-Java اتصالات جاوا را برای یک فایل مشخص IDL تولید می‌کند. برای جزئیات اتصالات، بخش Java IDL: IDL to Java Language Mapping را در http://docs.oracle.com/javase/8/docs/technotes/guides/idl/mapping/jidlMapping.html ببینید. برخی از نگارش‌های پیشین کامپایلر IDL-to-Java با نام idltojava شناخته می‌شدند. ایجاد اتصالات کلاینت و سرور (EMIT CLIENT AND SERVER BINDINGS) دستور idlj زیر برای یک فایل IDL با نام My.idl اتصالات سمت کلاینت را تولید می‌کند. idlj My.idl سینتکس پیشین معادل دستور زیر است: idlj -fclient My.idl مثال بعدی اتصالات سمت سرور را تولید می‌کند و شامل اتصالات سمت کلاینت به همراه اسکلت (skeleton) است که همگی مبتنی بر POA (مدل وراثت یا Inheritance Model) هستند. idlg -fserver My.idl اگر می‌خواهید هر دو نوع اتصالات سمت کلاینت و سرور را تولید کنید، از یکی از دستورهای (معادل) زیر استفاده کنید: idlj -fclient -fserver My.idl idlj -fall My.idl دو مدل ممکن در سمت سرور وجود دارد: مدل وراثت Servant قابل حمل (Portable Servant Inheritance Model) و مدل Tie. بخش Tie Delegation Model را ببینید. Portable Servant Inheritance Model. مدل پیش‌فرض سمت سرور، مدل Portable Servant Inheritance است. با فرض یک واسط My که در My.idl تعریف شده است، فایل MyPOA.java تولید می‌شود. شما باید پیاده‌سازی واسط My را ارائه دهید، و واسط My باید از کلاس MyPOA ارث‌بری کند. فایل MyPOA.java یک اسکلت مبتنی بر جریان است که کلاس org.omg.PortableServer.Servant در نشانی http://docs.oracle.com/javase/8/docs/api/org/omg/PortableServer/Servant.html را گسترش می‌دهد. واسط My واسط callHandler و واسط عملیات مرتبط با واسط IDL را که اسکلت پیاده‌سازی می‌کند، پیاده‌سازی می‌نماید. پودمان PortableServer برای آداپتور شیء قابل حمل (POA) نوع بومی Servant را تعریف می‌کند. به بخش Portable Object Adapter (POA) در نشانی http://docs.oracle.com/javase/8/docs/technotes/guides/idl/POA.html مراجعه کنید. در زبان برنامه‌نویسی جاوا، نوع Servant به کلاس جاوای org.omg.PortableServer.Servant نگاشت می‌شود. این کلاس به عنوان کلاس پایه برای تمام پیاده‌سازی‌های servant در POA عمل کرده و تعدادی متد ارائه می‌دهد که می‌توانند توسط برنامه‌نویس فراخوانی شوند، و متدهایی که توسط POA فراخوانی شده و می‌توانند توسط کاربر برای کنترل جنبه‌های رفتاری servant بازنویسی (override) شوند. گزینه دیگر برای مدل وراثت، استفاده از پرچم -oldImplBase برای ایجاد اتصالات سمت سرور است که با نگارش‌های پیش از Java SE 1.4 سازگار باشند. پرچم -oldImplBase غیر استاندارد است و این APIها منسوخ (deprecated) شده‌اند. از این پرچم تنها باید برای سازگاری با سرورهای موجود نوشته‌شده با Java SE 1.3 استفاده کنید. در این حالت، باید یک makefile موجود را ویرایش کنید تا پرچم -oldImplBase به کامپایلر idlj اضافه شود. در غیر این صورت نگاشت‌های سمت سرور مبتنی بر POA تولید می‌شوند. برای تولید اتصالات سمت سروری که سازگاری با نگارش‌های پیشین را حفظ کنند، به صورت زیر عمل کنید: idlj -fclient -fserver -oldImplBase My.idl idlj -fall -oldImplBase My.idl با داشتن واسط My تعریف‌شده در My.idl، فایل _MyImplBase.java تولید می‌شود. شما باید پیاده‌سازی واسط My را ارائه دهید، و واسط My باید از کلاس _MyImplBase ارث‌بری نماید. Tie Delegation Model. مدل دیگر سمت سرور مدل Tie نامیده می‌شود. این یک مدل تفویض (delegation model) است. از آنجا که امکان تولید هم‌زمان tieها و اسکلت‌ها وجود ندارد، آن‌ها باید به طور جداگانه تولید شوند. دستورهای زیر اتصالات مربوط به مدل Tie را تولید می‌کنند: idlj -fall My.idl idlj -fallTIE My.idl برای واسط My، دستور دوم فایل MyPOATie.java را تولید می‌کند. سازنده کلاس MyPOATie یک delegate دریافت می‌کند. در این مثال، با استفاده از مدل پیش‌فرض POA، سازنده همچنین به یک POA نیاز دارد. شما باید پیاده‌سازی delegate را ارائه دهید، اما نیازی نیست که از کلاس دیگری ارث‌بری کند، فقط باید از واسط MyOperations ارث‌بری داشته باشد. برای استفاده از آن با ORB، باید پیاده‌سازی خود را در کلاس MyPOATie کپسوله‌سازی کنید، برای مثال: ORB orb = ORB.init(args, System.getProperties()); // Get reference to rootpoa & activate the POAManager POA rootpoa = (POA)orb.resolve_initial_references("RootPOA"); rootpoa.the_POAManager().activate(); // create servant and register it with the ORB MyServant myDelegate = new MyServant(); myDelegate.setORB(orb); // create a tie, with servant being the delegate. MyPOATie tie = new MyPOATie(myDelegate, rootpoa); // obtain the objectRef for the tie My ref = tie._this(orb); ممکن است زمانی که پیاده‌سازی شما باید از پیاده‌سازی دیگری ارث‌بری کند، ترجیح دهید به جای مدل وراثت معمول از مدل Tie استفاده کنید. جاوا اجازه هر تعداد وراثت از واسط را می‌دهد، اما تنها یک جایگاه برای وراثت کلاس وجود دارد. اگر از مدل وراثت استفاده کنید، این جایگاه اشغال می‌شود. با مدل Tie، آن جایگاه برای استفاده خودتان آزاد می‌ماند. عیب آن این است که سطحی از غیرمستقیم‌سازی را ایجاد می‌کند: در هنگام فراخوانی هر متد، یک فراخوانی متد اضافه رخ می‌دهد. برای تولید سمت سرور، اتصالات مدل Tie که با نگارش‌های نگاشت زبان IDL به جاوا در نسخه‌های پیش از Java SE 1.4 سازگار باشند. idlj -oldImplBase -fall My.idl idlj -oldImplBase -fallTIE My.idl برای واسط My، این دستور فایل My_Tie.java را تولید می‌کند. سازنده کلاس My_Tie یک شیء impl دریافت می‌کند. شما باید پیاده‌سازی را برای impl ارائه دهید، اما نیازی نیست که از کلاس دیگری ارث‌بری کند، فقط باید واسط HelloOperations را پیاده‌سازی نماید. اما برای استفاده از آن با ORB، باید پیاده‌سازی خود را درون My_Tie قرار دهید، برای مثال: ORB orb = ORB.init(args, System.getProperties()); // create servant and register it with the ORB MyServant myDelegate = new MyServant(); myDelegate.setORB(orb); // create a tie, with servant being the delegate. MyPOATie tie = new MyPOATie(myDelegate); // obtain the objectRef for the tie My ref = tie._this(orb); اگر می‌خواهید فایل‌های تولیدشده به دایرکتوری دیگری غیر از دایرکتوری فعلی هدایت شوند، کامپایلر را به این روش فراخوانی کنید: idlj -td /altdir My.idl. برای رابط My، اتصالات به جای ./My.java، در /altdir/My.java و غیره ایجاد می‌شوند. تعیین مکان‌های جایگزین برای فایل‌های INCLUDE اگر فایل My.idl فایل idl دیگری به نام MyOther.idl را شامل شود (include کند)، کامپایلر فرض می‌کند که فایل MyOther.idl در دایرکتوری محلی قرار دارد. اگر به عنوان مثال در /includes قرار دارد، کامپایلر را با دستور زیر فراخوانی کنید: idlj -i /includes My.idl اگر به عنوان مثال My.idl فایل Another.idl را نیز شامل شود که در /moreIncludes قرار دارد، کامپایلر را با دستور زیر فراخوانی کنید: idlj -i /includes -i /moreIncludes My.idl از آنجا که این شکل از include می‌تواند بسیار طولانی شود، روش دیگری برای مشخص کردن محل جستجوی فایل‌های ضمیمه‌شده به کامپایلر در نظر گرفته شده است. این روش مشابه ایده یک متغیر محیطی است. فایلی به نام idl.config در دایرکتوری که در متغیر CLASSPATH شما فهرست شده است ایجاد کنید. درون idl.config، خطی به این صورت قرار دهید: includes=/includes;/moreIncludes کامپایلر این فایل را پیدا کرده و فهرست includes را می‌خواند. توجه داشته باشید که در این مثال نویسه جداکننده بین دو دایرکتوری یک نقطه ویرگول (;) است. این نویسه جداکننده وابسته به پلتفرم است. در پلتفرم Windows از نقطه ویرگول، در پلتفرم Unix از دونقطه (:) و به همین ترتیب استفاده کنید. تولید اتصالات برای فایل‌های INCLUDE به طور پیش‌فرض، اتصالات Java تنها برای رابط‌ها، ساختارها و مواردی تولید می‌شوند که در فایل idl موجود در خط فرمان تعریف شده باشند. انواع تعریف‌شده در فایل‌های includeشده تولید نمی‌شوند. به عنوان مثال، دو فایل idl زیر را در نظر بگیرید: My.idl file: #include interface My { }; MyOther.idl file: interface MyOther { }; یک تبصره برای این قاعده پیش‌فرض وجود دارد. هر دستور #include که در حوزه سراسری (global scope) ظاهر شود طبق آنچه توضیح داده شد رفتار می‌کند. این دستورات #include را می‌توان مشابه دستورات import در نظر گرفت. دستورات #include که درون یک حوزه بسته (enclosed scope) ظاهر می‌شوند به عنوان دستورات #include واقعی تلقی می‌شوند؛ بدین معنی که با کدهای داخل فایل ضمیمه‌شده به گونه‌ای برخورد می‌شود که گویی در فایل اصلی آمده‌اند و بنابراین اتصالات Java برای آن تولید می‌شوند. در اینجا یک مثال آورده شده است: My.idl file: #include interface My { #include }; MyOther.idl file: interface MyOther { }; Embedded.idl enum E {one, two, three}; دستور idlj My.idl را اجرا کنید تا فهرست زیر از فایل‌های Java تولید شود. دقت کنید که MyOther.java تولید نشده است، زیرا در یک #include شبه-import تعریف شده بود. اما E.java تولید شده است، زیرا در یک #include واقعی تعریف شده بود. توجه داشته باشید از آنجا که فایل Embedded.idl درون حوزه رابط My ضمیمه شده است، درون حوزه My (در MyPackage) ظاهر می‌شود. اگر از پرچم -emitAll استفاده شده بود، تمامی انواع در تمامی فایل‌های ضمیمه‌شده تولید می‌شدند. ./MyHolder.java ./MyHelper.java ./_MyStub.java ./MyPackage ./MyPackage/EHolder.java ./MyPackage/EHelper.java ./MyPackage/E.java ./My.java فرض کنید برای شرکتی به نام ABC کار می‌کنید که فایل IDL زیر را ساخته است: Widgets.idl file: module Widgets { interface W1 {...}; interface W2 {...}; }; اگر این فایل را از طریق کامپایلر IDL-to-Java اجرا کنید، اتصالات (bindings) جاوا برای W1 و W2 درون بستهٔ Widgets قرار می‌گیرند. یک قرارداد صنعتی وجود دارد که بیان می‌کند بسته‌های یک شرکت باید درون بسته‌ای به نام com. قرار داشته باشند. برای پیروی از این قرارداد، نام بسته باید com.abc.Widgets باشد. برای قرار دادن این پیشوندِ بسته روی ماژول Widgets، دستور زیر را اجرا کنید: idlj -pkgPrefix Widgets com.abc Widgets.idl اگر فایل IDL دیگری دارید که Widgets.idl را شامل می‌شود، پرچم -pkgPrefix باید در آن دستور نیز آورده شود. در غیر این صورت، فایل IDL شما به جای بستهٔ com.abc.Widgets به دنبال بستهٔ Widgets خواهد گشت. اگر چندین بسته از این دست دارید که به پیشوند نیاز دارند، قرار دادن آن‌ها در فایل idl.config که پیش‌تر شرح داده شد ممکن است آسان‌تر باشد. هر خط پیشوند بسته باید به فرم PkgPrefix.= باشد. خط مربوط به مثال قبل به صورت PkgPrefix.Widgets=com.abc خواهد بود. این گزینه بر شناسهٔ مخزن (Repository ID) تأثیری نمی‌گذارد. تعریف نمادها پیش از کامپایل (DEFINE SYMBOLS BEFORE COMPILATION) ممکن است نیاز داشته باشید برای فرایند کامپایل نمادی را تعریف کنید که درون فایل IDL تعریف نشده است، مثلاً برای گنجاندن کدهای اشکال‌زدایی در اتصالات. دستور idlj -d MYDEF My.idl معادل قرار دادن خط #define MYDEF درون My.idl است. حفظ اتصالات از پیش موجود (PRESERVE PREEXISTING BINDINGS) اگر فایل‌های اتصال جاوا از قبل موجود باشند، پرچم -keep مانع از بازنویسی آن‌ها توسط کامپایلر می‌شود. حالت پیش‌فرض این است که تمام فایل‌ها بدون در نظر گرفتن وجود قبلی آن‌ها تولید می‌شوند. اگر آن فایل‌ها را سفارشی‌سازی کرده‌اید (کاری که نباید انجام دهید مگر اینکه کاملاً بر محتوای آن‌ها مسلط باشید)، گزینهٔ -keep بسیار کاربردی است. دستور idlj -keep My.idl تمامی اتصالات سمت کلاینت را که از قبل موجود نیستند تولید می‌کند. مشاهده پیشرفت کامپایل (VIEW COMPILATION PROGRESS) کامپایلر IDL-to-Java هنگام پیشروی در مراحل اجرای خود، پیام‌های وضعیت تولید می‌کند. از گزینهٔ -v برای فعال کردن حالت پرگو (verbose) استفاده کنید: idlj -v My.idl. کامپایلر به‌طور پیش‌فرض در حالت پرگو کار نمی‌کند. نمایش اطلاعات نگارش (DISPLAY VERSION INFORMATION) برای نمایش نگارش ساخت کامپایلر IDL-to-Java، گزینهٔ -version را در خط فرمان مشخص کنید: idlj -version. اطلاعات نگارش همچنین درون اتصالات تولیدشده توسط کامپایلر نیز قرار می‌گیرد. هر گزینهٔ اضافی دیگری که در خط فرمان ظاهر شود نادیده گرفته خواهد شد. گزینه‌ها (OPTIONS) -d symbol این گزینه معادل خط زیر در یک فایل IDL است: #define symbol -demitAll تولید تمام انواع، شامل مواردی که در فایل‌های #include یافت می‌شوند. -fside مشخص می‌کند چه اتصالاتی تولید شوند. پارامتر side می‌تواند client، server، serverTIE، all یا allTIE باشد. گزینه‌های -fserverTIE و -fallTIE باعث می‌شوند اسکلت‌های مدل تفویضی (delegate model skeletons) تولید شوند. در صورتی که این پرچم تعیین نشود، مقدار پیش‌فرض -fclient است. -i include-path به‌طور پیش‌فرض، دایرکتوری جاری برای فایل‌های ضمیمه‌شده (included) جستجو می‌شود. این گزینه دایرکتوری دیگری را اضافه می‌کند. -i keep اگر فایلی که قرار است تولید شود از قبل وجود داشته باشد، آن را بازنویسی نمی‌کند. به‌طور پیش‌فرض بازنویسی می‌شود. -noWarn جلوگیری از نمایش پیام‌های هشدار. -oldImplBase اسکلت‌های سازگار با ORBهای JDK پیش از نگارش 1.4 را تولید می‌کند. به‌طور پیش‌فرض، اتصالات سمت سرور مدل وراثت POA تولید می‌شوند. این گزینه با تولید اتصالات سمت سروری که کلاس‌های مدل وراثت ImplBase هستند، سازگاری رو به عقب با نگارش‌های پیشین زبان برنامه‌نویسی جاوا را فراهم می‌کند. -pkgPrefix typeprefix هر جا که type در محدودهٔ فایل (file scope) دیده شود، نام بستهٔ جاوای تولیدشده را برای تمام فایل‌های تولیدشده برای آن نوع، با prefix پیشوندگذاری می‌کند. نوع (type) نام سادهٔ یک ماژول سطح بالا یا یک نوع IDL تعریف‌شده در خارج از هر ماژولی است. -pkgTranslate typepackage هرگاه نام ماژول type در یک شناسه دیده شود، آن را در شناسه برای تمامی فایل‌های موجود در بستهٔ جاوای تولیدشده با package جایگزین می‌کند. توجه داشته باشید که تغییرات pkgPrefix ابتدا اعمال می‌شوند. مقدار type نام سادهٔ یک ماژول سطح بالا یا یک نوع IDL تعریف‌شده در خارج از هر ماژول است و باید دقیقاً با نام کامل بسته مطابقت داشته باشد. اگر بیش از یک ترجمه با یک شناسه مطابقت داشته باشد، همان‌طور که در مثال زیر نشان داده شده است، طولانی‌ترین تطابق انتخاب می‌شود: Command: pkgTranslate type pkg -pkgTranslate type2.baz pkg2.fizz Resulting Translation: type => pkg type.ext => pkg.ext type.baz => pkg2.fizz type2.baz.pkg => pkg2.fizz.pkg نام بسته‌های روبه‌رو شامل org، org.omg یا هر زیربسته‌ای از org.omg را نمی‌توان ترجمه (جایگزین) کرد. هر تلاشی برای ترجمهٔ این بسته‌ها به کدی غیرقابل کامپایل منجر می‌شود و استفاده از این بسته‌ها به عنوان آرگومان نخست پس از -pkgTranslate خطا تلقی می‌گردد. -skeletonName xxx%yyy استفاده از xxx%yyy به عنوان الگو برای نام‌گذاری اسکلت. مقادیر پیش‌فرض عبارتند از: %POA برای کلاس پایهٔ POA (با -fserver یا -fall)، و _%ImplBase برای کلاس oldImplBase (با -oldImplBase و (-fserver یا -fall)). -td dir استفاده از dir برای دایرکتوری خروجی به جای دایرکتوری جاری. -tieName xxx%yyy استفاده از xxx%yyy مطابق با الگو. مقادیر پیش‌فرض عبارتند از: %POA برای کلاس پایهٔ POA (با -fserverTie یا -fallTie)، و _%Tie برای کلاس tie مربوط به oldImplBase (با -oldImplBase و (-fserverTie یا -fallTie)). -nowarn, -verbose اطلاعات انتشار را نمایش داده و خارج می‌شود. -version اطلاعات انتشار را نمایش داده و خارج می‌شود..SH "محدودیت‌ها (RESTRICTIONS)" شناسه‌های گریز داده‌شده در دامنهٔ سراسری نمی‌توانند املایی یکسان با انواع اولیهٔ IDL، Object یا ValueBase داشته باشند. این بدان دلیل است که جدول نمادها از پیش با این شناسه‌ها بارگذاری شده است. مجاز بودن بازتعریف آن‌ها، تعاریف اصلی‌شان را رونویسی خواهد کرد. احتمالاً این یک محدودیت همیشگی است. نوع IDL با عنوان fixed پشتیبانی نمی‌شود. مشکلات شناخته‌شده (KNOWN PROBLEMS) هیچ importی برای شناسه‌های سراسری تولید نمی‌شود. اگر یک شیء محلی صادرنشدهٔ impl را فراخوانی کنید، یک استثنا دریافت خواهید کرد، اما به نظر می‌رسد این امر ناشی از یک NullPointerException در کد DSI مربوط به ServerDelegate باشد. JDK 8 21 November 2013 idlj(1)