Menggunakan layanan web SharePoint dengan klien Java

Saya dulu berpikir bahwa Unta adalah sesuatu untuk diasapi atau ditunggangi di gurun, tetapi itu terjadi sebelum saya membuka mulut di tempat kerja suatu hari dan berkata, "Tentu saya dapat secara otomatis menyimpan dokumen ini ke SharePoint." SharePoint telah ada sejak lama, jadi saya berasumsi bahwa pasti ada Java API atau mungkin beberapa layanan web yang terpapar yang dapat saya konsumsi. Yah, ternyata saya benar-benar menyelesaikan pekerjaan, dan seperti banyak hal, itu berakhir lebih baik daripada awalnya. Tetapi ada beberapa rintangan di sepanjang jalan, yang ingin saya bantu agar dihindari pembaca JavaWorld lainnya.

Dalam tip Java ini saya akan menunjukkan kepada Anda bagaimana melakukan operasi CRUD dasar pada folder dokumen SharePoint dari klien Java. Demonstrasi akan berfokus pada beberapa metode yang lebih populer yang mungkin diminta oleh setiap konsumen layanan web SharePoint, yang ditemukan di layanan Salin dan Daftar Microsoft. Untuk operasi CRUD, kami akan menggunakan CAML (Collaborative Application Markup Language), bahasa berbasis XML yang digunakan dalam banyak metode yang diekspos oleh Copydan Lists. Anda akan mempelajari cara membuat struktur CAML valid yang diteruskan sebagai parameter metode atau ditetapkan ke properti objek, yang kemudian diteruskan sebagai parameter ke layanan ini.

Semoga tips ini dapat meyakinkan Anda bahwa ada CAML yang dapat Anda gunakan untuk mendapatkan dokumen bisnis dari titik A ke titik B, tanpa mengandalkan empat kaki dan punuk.

Kode demonstrasi

Kode demonstrasi saya sangat sederhana: Saya tidak menggunakan kode sumber terbuka selain untuk logging dan implementasi saya tidak memiliki ketergantungan pada teknologi Java EE, jadi Anda dapat menjalankan kode sumber langsung dari Eclipse dalam aplikasi Java standar.

Latar Belakang

Saya bekerja dalam kelompok yang melakukan manajemen informasi untuk volume data yang besar yang pada akhirnya disimpan di berbagai data-mart (layanan, ekspor, laporan, dan sebagainya). Konsumen, baik internal maupun eksternal perusahaan, mengkonsumsi data untuk membuat keputusan bisnis dan pribadi. Berbagai jenis pemantauan terjadi di lingkungan ini, termasuk audit otomatis dan laporan yang dijalankan terhadap data yang disimpan di data-mart. Audit memastikan bahwa data berada dalam keadaan yang konsisten, baik di seluruh pasar maupun di dalam pasar tempatnya berada. Laporan audit diemail ke berbagai orang dan kemudian disimpan secara manual di SharePoint.

Karena mesin yang digunakan untuk memantau memiliki konsep penulis keluaran yang dapat dicolokkan, wajar untuk mempertimbangkan menyiapkan penulis untuk SharePoint. Kami sudah menulis ke database, server SMTP, dan sistem file, jadi ini sepertinya langkah logis berikutnya dan cara untuk menghindari proses manual.

Triknya, tentu saja, membuat semuanya berhasil.

Memulai: Berkomunikasi dengan SharePoint

Aplikasi sampel untuk artikel ini menunjukkan cara berkomunikasi dengan SharePoint dari klien Java. Saya menulis aplikasi menggunakan Eclipse 3.6.2 dan Java 1.6.0_32. Gambar 1 menunjukkan dua paket utama yang terdapat dalam aplikasi sampel.

Paket pertama com.jw.sharepoint.examples,, berisi semua kode kustom untuk solusi tersebut. Ia menggunakan kode yang terdapat dalam com.microsoft.sharepoint.webservicespaket, yang merupakan kode yang dihasilkan.

Sebelum menyelami bagaimana kode khusus disusun, saya akan menjelaskan cara membuat paket Microsoft. Pertama, ingatlah bahwa kita akan menggunakan dua layanan web untuk menjalankan panggilan layanan: Copydan Lists. Anda bisa mengakses layanan ini di situs SharePoint yang Anda coba untuk berkomunikasi dengan di lokasi berikut ini:

  • //server/site/_vti_bin/Lists.asmx
  • //server/site/_vti_bin/Copy.asmx

Menghasilkan paket layanan web

Untuk membuat kode untuk paket layanan web yang akan kami gunakan wsimport, yang terletak di bindirektori instalasi Java Anda, dengan asumsi Anda menggunakan Java 1.6 atau lebih tinggi. Jika situs SharePoint Anda menjalankan HTTPS, Anda mungkin mengalami masalah wsimportsaat mengarahkannya langsung ke server Anda melalui URL di atas, dalam hal ini Anda akan menerima kesalahan seperti ini:

[ERROR] sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPath BuilderException: unable to find valid certification path to requested target

Masalah dalam kasus ini adalah cacertsfile Anda tidak memiliki sertifikat dari situs. Cara mudah untuk menyiasatinya adalah dengan menggunakan browser Anda untuk mengunduh file WSDL secara lokal. Untuk contoh yang tercantum di bawah ini saya telah melakukan hal itu dan menyimpan WSDL di c:\temp\. Kode 1 dan Kode 2 menunjukkan potongan kode yang saya gunakan untuk menghasilkan kode sumber, bersama dengan hasilnya. Anda dapat mengabaikan peringatan untuk setiap layanan.

Daftar 1. Salin pembuatan kode layanan

C:\temp>"%JAVA_HOME%\bin\wsimport" -d . -p com.microsoft.schemas.sharepoint.soap -keep -extension -Xnocompile Copy.wsdl parsing WSDL... [WARNING] SOAP port "CopySoap12": uses a non-standard SOAP 1.2 binding. line 229 of file:/C:/temp/Copy.wsdl generating code...

Daftar 2. Daftar pembuatan kode layanan

C:\temp>"%JAVA_HOME%\bin\wsimport" -d . -p com.microsoft.schemas.sharepoint.soap -keep -extension -Xnocompile list.wsdl parsing WSDL... [WARNING] SOAP port "ListsSoap12": uses a non-standard SOAP 1.2 binding. line 1511 of file:/C:/temp/list.wsdl generating code...

Setelah Anda membuat kode, kode tersebut siap untuk dimasukkan ke dalam solusi dan digunakan. Anda dapat menghapus –Xnocompileopsi dari wsimportperintah. Opsi ini akan menyebabkan file kelas dibuat bersama dengan sumbernya, tetapi untuk latihan ini kita hanya akan menyalin file sumber yang dihasilkan ke dalam solusi dan membiarkan Eclipse mengkompilasinya seolah-olah kita telah membuat kode sumber.

Catatan tentang keamanan

Agar berhasil menjalankan layanan SharePoint, saya harus menyimpang dari metode normal konsumsi layanan web saya, yang sebagian besar selalu melibatkan penggunaan Axis2. Saya segera menemukan bahwa Axis2 bermasalah dengan otorisasi NTML. Mungkin saja untuk mengatasi kesalahan ini dengan menggunakan JCIFS bersama dengan Axis2 (lihat Sumberdaya) tetapi itu sepertinya berlebihan untuk sesuatu yang relatif mudah. Dengan pendekatan yang saya tunjukkan tidak ada rintangan keamanan yang harus diatasi. Jika situs SharePoint Anda menggunakan HTTPS, Anda perlu memastikan bahwa cacertsfile tersebut diperbarui dengan sertifikat situs (lihat Sumber daya untuk detailnya).

Karena contoh dimaksudkan untuk dieksekusi sebagai aplikasi konsol di Eclipse, saya meneruskan argumen VM berikut dalam konfigurasi run:

-Djavax.net.ssl.trustStore=path to your updated cacerts file

Kode kustom

Kode kustom untuk solusi ini terletak di com.jw.sharepoint.examplespaket di kode sumber artikel. Ini berisi kelas kustom untuk setiap fungsi SharePoint yang akan kami uji:

  1. SharePointUploadDocumentExample mendemonstrasikan cara mengunggah dokumen ke SharePoint.
  2. SharePointDeleteListItemExample mendemonstrasikan cara menghapus dokumen dari SharePoint menggunakan CAML untuk meminta daftar dan menghapus item daftar.
  3. SharePointListExample mendemonstrasikan cara membuat kueri folder di SharePoint menggunakan CAML dan kemudian menafsirkan hasilnya.

Perhatikan bahwa saya tidak akan secara eksplisit membahas kelas terakhir SharePointListExample,. The SharePointDeleteListItemExamplekelas berisi fungsi untuk query, sehingga SharePointListExampledisajikan bagi Anda untuk belajar pada Anda sendiri.

Tentang kelas khusus

As shown in Figure 2, each of the custom classes follows the same pattern and extends the SharePointBaseExample class, which provides basic SharePoint functionality, as well as utility functions for dealing with CAML and XML. The custom classes also use specific properties files that they load via an initialize() function that is called in main. The properties files have all the properties needed for communicating with SharePoint and any other data that is required at runtime for the class in question.

Figure 2. Class diagram for the custom code (click to enlarge)

Each of the properties files located in the demonstration code's Configuration directory has the name of the class it supports with a .properties extension. Most of the properties contained in these files should be self-explanatory. Table 1 briefly describes the additional properties contained in SharePointDeleteListItemExample.properties.

Table 1. Additional properties of the SharePointDeleteListItemExample class

Property Description Example value
username The username for authentication to the SharePoint site. This should be fully domain qualified if running on Linux or using a different ID than used for Windows authentication. Domain\bigbird
password The password to the SharePoint site sesame
wsdl URL to the Lists.asmx WSDL //abc.xyz.com/project/epms9615/_vti_bin/Lists.asmx?wsdl
Endpoint URL to the Lists.asmx //abc.xyz.com/project/epms9615/_vti_bin/Lists.asmx
Folder The name of the base folder to use. Prod Support Folder
copy.wsdl URL to the Copy.asmx WSDL //abc.xyz.com/team/eds/_vti_bin/Copy.asmx?wsdl
copy.endpoint URL to the Copy.asmx //abc.xyz.com/team/eds/_vti_bin/Copy.asmx
copy.location The location to place files for upload //abc.xyz.com/project/epms9615/Prod%20Support%20Folder/

Daily%20Monitoring%20Status/AuditDeleteTesting/

copy.sourceFile The local file to use for uploading Configuration/SharePointDeleteListItemExample.properties
delete.FileRef.base The base URL to the SharePoint site, used in delete file requests. //abc.xyz.com/

Additional configuration files

Some additional configuration files are located in the Configuration directory. These are simple XML snippets written in CAML. We'll use these files, described in Table 2, throughout the solution.

Table 2. Additional configuration files

CAML file Description
Query.xml A CAML file containing the query that we'll use to list files from the SharePoint server. This file shows an example of a query that uses three fields with two different data types (Text and DateTime), as well as two different operators (Contains and Eq).
QueryOptions.xml A static file that we'll use throughout the examples to tell a SharePoint service that we want it to search all subfolders of the current folder.
Delete.xml A CAML file that we'll use to delete SharePoint files. Strings are substituted at runtime.
DeleteListItemQuery.xml A CAML file that we'll use to perform a query of candidate files available for removal from SharePoint

First demo: Uploading a file to SharePoint

Our first exercise will be uploading a file to SharePoint via the CopySoap web service. For this we'll use some of the classes that we generated in Listing 1 and Listing 2 by executing wsimport on the Copy.asmx.

In the SharePointBaseExample class you'll notice a method named getCopySoap(). We'll use this method to return a generated CopySoap instance, which we'll then use to upload a file by calling the method uploadDocument(CopySoap port, String sourceUrl).

The getCopySoap() method is shown in Listing 3.

Listing 3. getCopySoap()

protected CopySoap getCopySoap() throws Exception { logger.info("Creating a CopySoap instance..."); Copy service = new Copy(new URL(getProperties().getProperty("copy.wsdl")), new QName("//schemas.microsoft.com/sharepoint/soap/", "Copy")); CopySoap copySoap = service.getCopySoap(); BindingProvider bp = (BindingProvider) copySoap; bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, getProperties().getProperty("username")); bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, getProperties().getProperty("password")); bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, getProperties().getProperty("copy.endpoint")); return copySoap; }

A Copy class is instantiated using a two-argument constructor, which takes the copy service's WSDL location along with the QName instance to use. We get the CopySoap instance we need from the Copy instance. Once this is done we can cast it to a BindingProvider, which performs the protocol binding and contains the associated context objects for request-and-response message processing. From the BindingProvider we can then set the username, password, and endpoint information on the request-context Map.

Kode 4 menunjukkan mainmetode kelas SharePointUploadDocumentExample. Cara ini sangat sederhana; itu menggunakan getCopySoap()dan uploadDocument(CopySoap port, String sourceUrl)untuk mengunggah dokumen ke SharePoint. File sumber yang akan disalin ke SharePoint ditentukan dalam SharePointUploadDocumentExamplefile properti terkait, yang diteruskan ke uploadDocument(…)metode melalui nilai copy.sourceFileproperti.

Daftar 4. Metode utama upload dokumen

public static void main(String[] args) { logger.debug("main..."); try { SharePointUploadDocumentExample example = new SharePointUploadDocumentExample(); example.initialize(); CopySoap p = example.getCopySoap(); example.uploadDocument(p, properties.getProperty("copy.sourceFile")); } catch (Exception ex) { logger.error("Error caught in main: ",ex); } }

uploadDocument ()

Selanjutnya kita akan memanggil uploadDocument()metode tersebut. Ada beberapa hal yang perlu diketahui tentang metode ini: